소프트웨어 팩토리은(는) 무엇을 하나요?

먼저 모든 범위 의문을 해소하십시오. 의무를 고정하십시오. 모든 무거운 단계를 새로운 서브 에이전트에 위임하십시오. 코드를 작성하지 않은 독립적인 검증자가 완료를 증명하십시오.

┌──────────┐   ┌──────┐   ┌────────┐   ┌───────┐   ┌────────┐
│ DISCOVER │ → │ PLAN │ → │ CHECKS │ → │ BUILD │ → │ VERIFY │
└──────────┘   └──────┘   └────────┘   └───────┘   └────────┘
 0 의문점      확인       의무        배치        작성자 != 검증자

5가지 동작, .specs/features/<feature>/ 아래 3개의 지속 가능한 산출물, 그리고 컨텍스트 윈도우를 절대 비대하게 만들지 않는 메인 채팅의 Thin Orchestrator로 구성됩니다.

DISCOVER: 읽기 전용 scout 서브 에이전트가 코드베이스를 스캔하고 간결한(~30줄) 모호성 보고서를 반환합니다. 메인 채팅은 구체적인 옵션과 권장 기본값을 제시하며 사용자와 인터뷰하여 확인되지 않은 가정이 0개가 될 때까지 진행합니다(모든 행에 Confirmed? y). discovery.md를 참조하십시오.
PLAN: planner 서브 에이전트가 .specs/features/<feature>/plan.md를 작성하고(Problem, Flow, Impact, Relations, Surface, Landing, Criteria, Out of scope, Assumptions, Observable, Sources) validate_plan.py를 실행합니다. 사용자는 plan.md에 대해 빠르게 서명합니다. plan.md를 참조하십시오.
CHECKS: plan.md 서명 후, 자동화된 사후 계획 루프가 시작됩니다. specifier 서브 에이전트가 .specs/features/<feature>/checks.md를 도출하고(주장 + 증명, Coverage 조인, Test policy, Swept, Handoff 산술) validate_checks.py를 실행합니다. checks.md를 참조하십시오.
BUILD: 슬라이스/배치당 하나의 builder 서브 에이전트가 체크만을 엄격히 참고하여 테스트를 작성하고, 코드를 구현하며, 증명을 실행하고, checks.md를 업데이트한 후 check_commit.py를 사용하여 커밋합니다. build.md를 참조하십시오.
VERIFY (및 FIX 루프): 독립적인 verifier 서브 에이전트(절대 빌더가 아님)가 <feature base>..HEAD를 모든 체크에 대해 감사하고, .specs/features/<feature>/verification.md를 작성하며, validate_verification.py를 실행합니다. 어떤 체크가 실패하면 fixer 서브 에이전트가 순위가 매겨진 격차를 해결하고 새로운 verifier가 재검증합니다(최대 3회). verify.md 및 orchestration.md를 참조하십시오.

이러한 형태의 이유

코딩 에이전트는 두 가지 예측 가능한 이유로 복잡한 기능에서 실패합니다:

컨텍스트 윈도우 팽창: 단일 채팅 세션이 저장소를 탐색하고, 사용자와 인터뷰하고, 계획을 작성하고, 체크를 도출하고, 테스트와 코드를 작성하고, 자체 작업을 검증하면 컨텍스트 윈도우가 가득 차서 손실 압축을 유발합니다.
확인되지 않은 요구사항 및 자체 검토 사각지대: 제품 동작을 조용히 추측하거나(Confirmed? n) 작성자가 스스로 완료를 인증하도록 하면 작성자 자신의 사각지대가 그대로 제품에 포함됩니다.

software-factory는 두 가지를 모두 해결합니다:

Thin Orchestrator (메인 채팅에서 15k 토큰 미만): 메인 채팅은 엄격하게 코디네이터 및 사용자 인터뷰어 역할을 합니다. 모든 코드베이스 읽기, 산출물 작성, 코딩, 테스트 및 검증은 격리된 임시 서브 에이전트(scout, planner, specifier, builder, verifier, fixer) 내에서 실행되며, 이들은 디스크의 .specs/features/<feature>/ 파일과 git 커밋을 통해서만 통신합니다. 전체 디스패치 프로토콜: orchestration.md를 참조하십시오.
작고 고정된 의무 집합 및 독립적인 검증자: 클래스별 Purpose/Location/Interfaces와 같은 세분화된 작업 체크리스트나 구성 요소 카탈로그는 없어 오래될 위험이 없습니다. 일방향(one-way) 결정은 Landing에서 문자 그대로 형태를 갖습니다. 되돌릴 수 있는 배치는 diff에서 결정됩니다.

중요한 규칙

고정된 규칙 집합입니다. 모든 프로필에서 유지됩니다:

확인되지 않은 가정 제로 (Confirmed? y). 제품이나 범위 동작을 조용히 추측하지 마십시오. DISCOVER 단계에서 발견된 모든 회색 영역은 구체적인 옵션과 권장 기본값을 제시하여 질문하거나, 사용자가 명시적으로 위임해야 합니다(Confirmed? y). validate_plan.py는 Confirmed?가 n이거나 비어 있는 행을 거부합니다.
Thin Orchestrator 및 엄격한 단계별 단일 서브 에이전트 경계 (scout != planner != specifier != builder != verifier). 메인 채팅을 약 15k 토큰 미만으로 유지하십시오. 두 단계를 단일 서브 에이전트 호출로 병합하지 마십시오:
- scout는 오직 탐색만 수행하고 약 30줄의 모호성 보고서를 반환합니다.
- planner는 오직 plan.md 작성 + validate_plan.py 실행만 수행한 후 중단하고 종료합니다.
- specifier는 오직 checks.md 작성 + validate_checks.py 실행만 수행한 후 중단하고 종료합니다(테스트 파일이나 구현 코드를 절대 작성해서는 안 되며 BUILD 단계로 계속 진행해서는 안 됩니다).
- builder는 specifier가 반환된 후에만 실행됩니다. 다중 슬라이스 기능(S1, S2, ...)의 경우 슬라이스당 별도의 builder 서브 에이전트를 순차적으로 디스패치하여 각 슬라이스가 새로운 컨텍스트 윈도우에서 실행되고 사용자에게 진행 상황을 보고하도록 합니다.
- verifier는 최종 builder가 커밋한 후에만 새로운 서브 에이전트에서 실행됩니다.
모든 체크는 구체적인 값이 있는 하나의 관찰 가능한 주장과 증명입니다. 즉, 종료 코드로 판단되는 정확한 테스트 선택기 또는 명령어입니다. 증명 없이는 체크도 없습니다.
테스트는 체크가 말하는 것을 단언(assert)하며, 코드가 우연히 하는 것을 단언하지 않습니다. 구현을 읽고 테스트를 작성하지 마십시오.
스위트를 통과시키기 위해 단언을 약화시키거나, 테스트를 삭제하거나, 건너뛰지 마십시오. 진정으로 잘못된 체크는 수정이 아니라 중단하고 질문하는 대상입니다.
체크와 Test policy 행은 승인되면 고정됩니다. plan.md에서 Landing, Relations, Surface는 추가적입니다. 빌드 중 발견된 문(door)은 이를 닫는 코드보다 먼저 행이 추가되며, 사용자가 승인한 행은 절대 다시 작성되지 않습니다. Flow와 Impact는 경로를 변경하는 커밋에서 진실을 유지합니다.
검증자는 새로운 서브 에이전트이며, 절대 작성자가 아니며, 절대 선택 사항이 아니며, 요청을 기다리지 않습니다. 오케스트레이터는 기능의 마지막 커밋이 <feature base>..HEAD에 도달한 직후 모든 체크와 함께 검증자를 디스패치합니다.
프로필은 최소 기준이며 validate_verification.py에 의해 강제됩니다.
완료 게이트는 느낌이 아니라 스크립트입니다: validate_verification.py가 0으로 종료되어야 합니다.
피해 범위: 승인된 명세는 로컬 편집 및 로컬 커밋을 승인합니다. git push, 배포 및 프로덕션 데이터 변경은 해당 작업에 대한 명시적인 승인이 필요합니다.

프로필

프로젝트는 AGENTS.md 또는 이와 동등한 파일에서 얼마나 많은 검증이 실행될지 선언합니다. 선언이 없는 경우: light.

## software-factory

profile: light
budget: 150k

프로필	추가 사항	잡을 수 없는 것
`light` (기본값)	각 명명된 테스트가 존재하고 실행되는 것으로 표시된 `HEAD`에서 증명 실행, 체크당 하나의 위치 지정된 단언, 수준 및 샘플링 격차, `Swept existing` 재읽기	증명이 없는 집합 멤버; 잘못된 구현에서도 통과할 테스트
`standard`	재계산된 `Coverage` 조인, 각각 판정이 있는 `Test policy` 행, 단언 표면당 하나의 결함	바인딩 소스와 모순되는 체크; 아무도 구축하지 않은 화면
`ui`	바인딩 소스를 열어 비교, 화면당 복사 및 배열 열거	간격, 색상 및 글꼴 두께만 화면당 열거됨

validate_verification.py는 checks.md가 승인된 프로필과 다른 보고서는 실패 처리하고, 결함 행이나 재계산된 커버리지가 없는 standard 보고서는 실패 처리하며, 바인딩 소스 섹션이 없는 ui 보고서는 실패 처리합니다.

산출물

.specs/
├── STATE.md                    # 결정 로그 (AD-NNN) + Handoff 스냅샷
├── LESSONS.md                  # scripts/lessons.py 에 의해 렌더링됨 - 절대 수동 편집 금지
├── lessons.json                # 기계 소유
└── features/<feature>/
    ├── plan.md                 # 문제, 흐름, 영향, 관계, 표면, 착륙, 기준, 가정 (모두 y), 관찰 가능
    ├── checks.md               # 주장 + 증명, 커버리지 조인, 테스트 정책, 스위프트, 핸드오프 배치
    └── verification.md         # 독립적인 검증자의 보고서

각 파일은 해당 단계가 콘텐츠를 생성할 때 생성합니다. 대략 3개 미만의 파일이 변경되고 일방향 문(one-way door)이 없으며 범위 모호성이 전혀 없는 변경의 경우, ## Intent 단락이 있는 checks.md만 작성하고 plan.md는 건너뜁니다.

`plan.md`의 5가지 제한된 설계 섹션

섹션	검토 내용	제외 항목
`Flow`	경로, 홉당 한 줄	존재하지 않거나 문(door)에 의해 생성되지 않은 모든 모듈 - 즉, 배치
`Impact`	밑에서 변경되는 사항: 용어 및 기존 데이터	위험 등록부
`Relations`	엔터티, 카디널리티, 일방향 제약 조건	열 및 유형
`Surface`	경로, 입력, 출력, 상태	요청 본문 명세 및 체크 ID - 아직 존재하지 않음
`Landing`	일방향 문(door), 리터럴 형태와 거부된 대안	리팩터링이 되돌리는 모든 것

흐름

발견 — 읽기 전용 scout 서브 에이전트를 디스패치하여 저장소, .specs/STATE.md 및 .specs/LESSONS.md를 검사하고 약 30줄의 모호성 보고서를 반환합니다. 사용자를 진정한 제품 및 범위 회색 영역(턴당 최대 2개의 질문, 권장 기본값이 있는 구체적인 옵션)을 Observable 표면과 9가지 암시적 차원에 걸쳐 0개의 의문점이 남을 때까지 안내합니다: discovery.md를 참조하십시오.
계획 — 확인된 발견 결정과 함께 planner 서브 에이전트를 디스패치하여 .specs/features/<feature>/plan.md를 작성하고 validate_plan.py를 통과하도록 합니다. plan.md를 사용자에게 제시하여 빠른 서명을 받습니다: plan.md를 참조하십시오.
체크 — plan.md가 승인되면 자동으로 실행됩니다. 전용 specifier 서브 에이전트를 디스패치하여 .specs/features/<feature>/checks.md를 도출하고(주장 + 증명, Coverage 조인, Swept 및 ## Handoff 배치 크기 조정) validate_checks.py를 통과시킨 다음, 코드나 테스트가 작성되기 전에 해당 서브 에이전트를 종료합니다: checks.md를 참조하십시오.
구축 — specifier가 완료된 후 슬라이스(S1, S2, ...)당 하나의 새로운 builder 서브 에이전트를 순차적으로 디스패치합니다. 각 빌더는 할당된 슬라이스에 대한 체크에서 테스트를 작성하고, 구현하고, 증명을 실행하고, checks.md에 Boundary를 기록하고, check_commit.py로 커밋한 후 종료합니다: build.md를 참조하십시오.
검증 및 수정 — 새로운 verifier 서브 에이전트를 <feature base>..HEAD에 대해 디스패치하여 verification.md를 작성하고 validate_verification.py를 실행합니다. 실패하면 fixer 서브 에이전트를 디스패치하고 재검증합니다(최대 3회): verify.md를 참조하십시오.
오케스트레이션 및 서브 에이전트 디스패치 — Thin-Orchestrator 규칙, 컨텍스트 윈도우 예산, 및 멀티 에이전트 매핑(antigravity, claude, codex): orchestration.md를 참조하십시오.
영구 메모리 — 프로젝트 결정(STATE.md), 세션 핸드오프, 및 검증 기반 교훈(lessons.py): memory.md를 참조하십시오.

스크립트

<skill-dir>을 이 SKILL.md가 포함된 디렉토리로 결정하고 python3 <skill-dir>/scripts/<name>.py를 호출하십시오. cwd가 프로젝트 루트와 다를 때 --root를 전달하십시오. 0이 아닌 종료는 중지 및 수정을 의미합니다.

시점	명령어
파이프라인 단계 및 다음 서브 에이전트 역할 검사	`orchestrate.py status <feature> --root <dir>`
격리된 서브 에이전트 프롬프트 생성	`orchestrate.py prompt --role <scout
오케스트레이터를 통한 단계 게이트 실행	`orchestrate.py gate --phase <plan
CLI를 통해 서브 에이전트 디스패치 (또는 `--dry-run`)	`orchestrate.py dispatch --role --agent <antigravity
`plan.md` 제시 전	`validate_plan.py <feature>`
`BUILD` 시작 전	`validate_checks.py <feature>`
각 커밋 전	`check_commit.py --message "<msg>"`
완료 선언 전	`validate_verification.py <feature>`
증류 시	`lessons.py add ...`
검증자, 스크립트 또는 템플릿 편집 후	`selftest.py`

서브 에이전트 및 핸드오프

모든 단계는 자체 서브 에이전트 호출 내에서 엄격히 격리됩니다(scout -> planner -> specifier -> builder [S1] -> builder [S2] -> ... -> verifier -> fixer). specifier (CHECKS)와 builder (BUILD)를 동일한 서브 에이전트에서 절대 결합하지 마십시오. BUILD 중 기능에 여러 슬라이스(S1, S2, ...)가 있는 경우 슬라이스당 별도의 builder 서브 에이전트를 순차적으로 디스패치하여 각 빌더가 깨끗한 컨텍스트 윈도우로 시작하고, 빠르게 완료하며, 초록불에 슬라이스를 커밋하고, Thin Orchestrator에 진행 업데이트를 반환하도록 합니다.

마지막 빌더 슬라이스가 초록불을 반환하면 Orchestrator는 사용자에게 묻지 않고 즉시 독립적인 verifier 서브 에이전트를 같은 턴에 디스패치합니다.

지식 체인

엄격한 순서: 기존 코드 및 규칙, 프로젝트 문서, 라이브러리 문서(가능한 경우 Context7), 웹 검색, 그런 다음 불확실한 것으로 표시합니다. API, 플래그, 명령어 또는 동작을 절대 만들어내지 마십시오.

출력 동작

산출물을 생성하고 단계를 설명하지 마십시오. 판정으로 시작하십시오. 결정을 단정적으로 명시하십시오. filler와 기계적인 헤징을 줄이십시오. 섹션 제목은 영어로 유지하십시오(이는 게이트에서 검증되는 스키마입니다).

소프트웨어 팩토리