build-it — 자율 전달 오케스트레이터은(는) 무엇을 하나요?
plan-it이 계획하고, build-it이 만듭니다. (이전 명칭: fable-it — v3.1.0에서 이름 변경) 사용자가 목표와 **번호가 매겨진 완료 정의(DoD)**를 전달하면 build-it은 작업 전체를 완료까지 실행합니다 — 일반적으로 무인, 야간 실행이며 정직하고 증거 기반의 보고서를 남깁니다. 이 파일은 이식 가능한 동작 계층입니다: 아래 모든 내용은 SKILL.md를 읽는 모든 에이전트에서 실행할 수 있는 호스트에 구애받지 않는 메커니즘입니다. (Claude Code 플러그인은 번들 하위 스킬과 선택적 시행 훅을 추가하지만, 아래 내용은 이에 의존하지 않습니다.)
세 가지 원칙이 실행을 지배합니다: 게이트, 분위기 아님 (모든 하중 지지 동작에는 트리거, 테스트, 조치가 있음); 상태 외부화 (실행이 반드시 기억해야 하는 모든 것은 디스크에 저장되고 단계 경계에서 다시 읽힘); 새로운 시각으로 검증 (정직함은 구조적입니다 — 원장과 감사 통과, 동기 부여가 아님).
게이트 카탈로그
각 게이트를 결정 지점에서 확인하세요 — 이는 지속적인 훈계가 아닌 자체 감사입니다:
- 턴 종료 게이트 — 트리거: 턴을 종료하기 전 · 테스트: 마지막 문단이 계획, 질문 또는 약속("다음에는...", "다음으로 저는...", "알려주세요...")인가? · 조치: 해당 작업을 지금 수행하거나 BLOCKED 상태와 이유를 보고합니다. 약속으로 턴을 끝내지 마십시오.
- 주장 게이트 — 트리거: DoD 기준 상태를 보고하기 전 · 테스트:
.taskstate/evidence.md에 이 세션에서 이를 뒷받침하는 도구/명령 결과가 포함되어 있나요? · 조치: 원장 항목이 없으면 상태는 기계적으로 IMPLEMENTED-NOT-VERIFIED입니다. VERIFIED는 판단이 아닌 원장 조회입니다. - 상태 변경 게이트 — 트리거: 상태를 변경하는 명령(재시작, 삭제, 설정 편집, 마이그레이션) 전 · 테스트: 증거가 이 특정 조치를 지원하는가, 아니면 신호가 단지 알려진 실패와 패턴 일치하는가? · 조치: 패턴만 일치하면 먼저 누락된 증거를 수집합니다.
- 단계 경계 게이트 — 트리거: 모든 단계 진입 시 (새 에픽, 재개된 세션, 압축 후) · 테스트: 이 단계에서
grounding.md,decisions.md,run-memory.md를 다시 읽었는가? · 조치: 조치를 취하기 전에 다시 읽습니다. - 위임 게이트 — 트리거: 위임된 작업자 또는 병렬 작업이 완료되거나 유휴 상태가 된 후 · 테스트: 출력이 디스크에 존재하고 비어 있지 않으며 할당과 일치하는가? · 조치: 유휴 상태 ≠ 전달됨 — 출력이 없거나 잘못되었으면 재분배하거나 작업을 인계받고; 전사 덤프가 아닌 결론을 전달합니다. (병렬 변경 작업의 경우 존재만으로는 충분하지 않습니다 — 통합 게이트 참조.)
- 인터록 게이트 (안전한 병렬) — 트리거: 실행 시작 시 및 병렬 변경 에이전트를 생성하기 전 · 테스트:
.taskstate/RUNLOCK에 다른 실행이 소유한 라이브 보유자(하트비트 < 10분)가 표시됩니까? · 조치: RUNLOCK을 (소유자 · 호스트 · PID · startedAt · 하트비트) 원자적으로 (독점 생성 — 읽고 확인하고 쓰지 않음) 실행 시작 시 획득하고 하트비트를 타이머로 (2~3분) 단계 경계에서뿐만 아니라 새로 고칩니다. 다른 라이브 실행이 보유하고 있으면 트리를 공동 변경하지 않고 BLOCKED("다른 실행이 이 트리를 소유합니다: <소유자>")를 보고하거나 대기합니다. 오래된 잠금(하트비트 만료 및 소유자가 활동 중임이 입증되지 않음 — 동일 호스트 PID 확인 우선)은 기록된run-memory.md메모와 함께 회수할 수 있습니다. 중지 훅에서 해제합니다. 작업 트리는 공유 상태입니다 — 동시 쓰기를 데이터베이스에 대한 동시 쓰기처럼 취급합니다.references/parallel-safety.md참조. - 작업 트리 게이트 (안전한 병렬) — 트리거: 파일을 쓰거나 편집하는 병렬 에이전트를 파견하기 전 · 테스트: 각 변경 에이전트가 자체 작업 트리를 가지고 있습니까, 아니면 두 개가 하나의
.git을 공유합니까? · 조치: 각 병렬 변경 에이전트에게 실행 기준의agent/<lane>브랜치에 자체git worktree를 제공합니다. 조정자만 브랜치를 순차적으로 병합합니다. 읽기 전용 파견(연구, 검색, 감사)은 트리를 공유할 수 있지만 여전히 git을 변경하지 않습니다. 어떤 작업자도 공유 트리에서git merge/checkout/reset을 실행하지 않습니다 — 이는 조정자 전용, 한 레인씩입니다.references/parallel-safety.md참조. - 통합 게이트 (안전한 병렬) — 트리거: 슬라이스/작업 트리가 병합된 후, 웨이브가 수락되기 전 · 테스트: 병합된 트리가 프로젝트의 통합 형태(빌드, lockfile 존재 + 일관성, 선언된 테스트/lint 통과)를 통과합니까? — 단순히 "작업자의 파일이 존재합니까?"가 아닙니다. · 조치: 병합된 결과에 대해 통합 검사를 실행합니다. 단독으로는 정상이지만 통합이 손상된 슬라이스(표준 사례: lockfile 없이 추가된
package.json)는 재개, 수락되지 않음입니다. 수락은 통합이지 존재가 아닙니다.references/parallel-safety.md참조.
실행 상태 계약
코드를 작성하기 전에 .taskstate/에 다음 네 개의 파일을 만들고 모든 단계 경계에서 처음 세 개를 다시 읽습니다:
| 파일 | 내용 |
|---|---|
grounding.md | 데이터가 모델링되는 방식과 위치; DoD 항목별 검증 경로 + 대상이 이 세션에서 도달 가능한지 여부 |
decisions.md | 모든 교차 결정(스키마, 인터페이스, 명명, 소유권) — 공유 계약; 항목을 다시 논쟁하지 말고 대신 의견 차이를 기록 |
evidence.md | 증거 원장 — 기준별 검증 시도당 하나의 항목: 타임스탬프 · 명령 · 인용된 출력 · 평결, 발생 즉시 추가 |
run-memory.md | 실패한 접근 방식(맹목적으로 재시도 금지), 환경 특이점, 결정 근거, 예상치 못한 일 |
실행 간 메모리: 실행 종료 시 내구성 있는 교훈을 .build-it-reports/lessons.md에 기록합니다. 동일 프로젝트의 향후 실행 시작 시 이를 읽습니다(프로젝트에 v3.1.0 이전 실행의 레거시 .fable-it-reports/lessons.md가 있는 경우 그것도 읽습니다).
주장 근거 규칙: 기준은 evidence.md에 이 세션의 통과 결과가 있는 경우에만 VERIFIED로 보고될 수 있습니다. 그 외는 IMPLEMENTED-NOT-VERIFIED(구축되었지만 실제 확인을 실행할 수 없음 — 무엇이 차단했는지 설명) 또는 BLOCKED(완료할 수 없음 — 사용자가 제공해야 하는 것 설명)입니다. 모의, 가정 또는 기억에 기반하여 VERIFIED로 절대 보고하지 마십시오.
실행
- DoD를 고정합니다. 모호한 목표를 번호가 매겨진 개별 검증 가능한 기준으로 재구성하고 표시합니다. 실행 모델을 선언하고 해당 자세를 적용합니다: 약하거나 작은 모델은 더 자주 재근거하고 게이트를 인라인으로 다시 설명합니다. 강력한 모델은 높은 노력으로 과잉 엔지니어링 억제제(요청되지 않은 리팩터링, 추측성 추상화 금지)를 적용합니다. 확실하지 않을 때는 가장 엄격한 자세를 가정합니다. 트리를 건드리기 전에 RUNLOCK을 획득합니다(인터록 게이트): 다른 실행이 라이브로 보유하고 있으면 BLOCK 또는 대기 — 하나의 작업 트리에 두 명의 작성자는 절대 안 됩니다.
- 자율 자세. 되돌릴 수 있는 작업에 대해 묻지 않고 진행합니다. 되돌릴 수 없는 작업(삭제, 강제 푸시, 파괴적 마이그레이션)은 사전 승인 없이 절대 수행하지 않습니다 — 한 컨텍스트의 승인이 다른 컨텍스트로 이어지지 않습니다. 덮어쓰기 전에 확인합니다. 양면 정직함: 절대 가짜 초록을 만들지 말고, 증거가 원장에 있는 결과에 대해 절대 회피하지 마십시오.
- 사전 근거. 실제 진실의 소스(메모리가 아닌 실제 스키마, 파일, 엔드포인트)를 읽은 다음 네 개의 실행 상태 파일을 씁니다. 이름을 지정할 수 있는 검증 경로가 없는 기준은 지금 플래그 지정됩니다.
- 분해 및 라우팅. 목표를 에픽 → 스토리 → DoD 항목에 매핑된 작업으로 분해합니다(분해를
.taskstate/에 저장합니다). 결정 결합 작업은 하나의 스레드로 유지합니다. 진정으로 독립적인 부분만 병렬화하고decisions.md에 의해 바인딩됩니다. 병렬 변경 작업은 격리되어 실행됩니다(작업 트리 게이트): 각 동시 작성자는 자체git worktree/agent/<lane>브랜치를 얻고 조정자는 브랜치를 순차적으로 병합하며 각 병합 후 통합 게이트를 실행합니다 — "출력이 존재"에 기반하여 웨이브를 수락하지 마십시오. 병합된 빌드/lockfile/테스트를 깨는 슬라이스는 재개됩니다. 읽기 전용 파견은 트리를 공유할 수 있습니다. 호스트가 작업자 모델을 선택할 수 있게 하는 경우 기계 작업은 저렴한 계층으로 라우팅하고 판단/검증은 최상위 계층(세션 모델 — 사용자가 실행하도록 선택한 것)으로 라우팅합니다 — 검증 패스를 절대 다운그레이드하지 말고 각 선택 + 이유를run-memory.md에 기록합니다. 선지불보다는 어려움에 따라 에스컬레이션합니다: 한 번 수정된 재분배 후에도 계약을 이행하지 못하거나 쓰러스팅하는 하위 계층 작업자는 해당 슬라이스가 한 계층 위에서 다시 실행되며 에스컬레이션이 기록되고 보고서에 공개됩니다(에스컬레이션 0건 자체가 보고 가능한 사실입니다). - 사이클을 실행합니다. 수정하기 전에 진단(신뢰하기 전에 근본 원인에 도전), 수정 후 테스트, 모든 결과를 원장에 추가합니다. 기준을 검증하기 전에 해당 대상이 실제로 도달 가능한지 확인합니다 — 모의에 대한 QA 통과는 거짓 초록입니다. 대신 IMPLEMENTED-NOT-VERIFIED로 직접 라우팅합니다. 충돌 후
.taskstate/에서 재개합니다. 인프라 실패는 작업 실패가 아닙니다. - 새로운 시각으로 검증한 다음 보고합니다. 보고서 초안을 작성한 다음 아래의 저하된 검증자 프로토콜에 따라 감사합니다(또는 호스트에 있는 경우 새로운 검토자에게 감사를 넘깁니다 — 절대 건너뛰지 마십시오). 보고서와, 생성된 자격 증명이 있으면 별도의 자격 증명 아티팩트를
.build-it-reports/에 전달합니다.
저하된 검증자 프로토콜
전달 전에 별도의 패스로 초안 보고서를 감사합니다. 명시적으로 "구현 컨텍스트를 제쳐두고"라고 말합니다. 그런 다음 DoD, 초안 보고서 및 .taskstate/evidence.md만 읽고 — 구현 기록은 절대 읽지 않고 — 모든 행을 기본적으로 도전합니다: 원장 항목이 없는 VERIFIED 행 또는 인용된 출력이 실제로 기준을 입증하지 않는 행은 CHALLENGED됩니다. 모든 도전은 전달 전에 해결됩니다: 지금 실제 확인을 실행하고 원장 항목을 추가하거나 행을 IMPLEMENTED-NOT-VERIFIED로 강등합니다. 보고서에 의견 차이를 기록합니다. 도전을 조용히 무시하지 마십시오.
보고서
하나의 평결 소스. DoD 기준당: VERIFIED (원장 증거 인용) / IMPLEMENTED-NOT-VERIFIED (무엇이 검증을 차단했는지, 대신 사용된 것) / BLOCKED (사용자가 결정하거나 제공해야 하는 것). 포함: 조용히 건너뛴 항목 없음 섹션 (건너뛰거나, 샘플링되거나, 제한된 모든 것과 이유), 위임/비용 선택 사항, decisions.md의 결정, 예상치 못한 일, 권장 다음 조치. 잠에서 깬 팀원을 위해 작성: 결과를 먼저, 완전한 문장, 발명된 약어 없음.
설치
Claude Code 플러그인 (권장) — 컨덕터가 라우팅하는 번들 /launch, /iterate, /full-qa 및 /chrome-cdp-control 스킬과 선택적 실패 시 개방 시행 훅을 추가합니다:
/plugin marketplace add DevOtts/build-it
/plugin install build-it@devotts
다른 모든 에이전트 (Cursor, Codex, Copilot, 70개 이상 도구):
npx skills add DevOtts/build-it -a <agent>
번들 스킬 없이 위 메커니즘에 따라 모든 단계를 인라인으로 실행합니다 — 동작 계층이 제품입니다; 저하시키되 깨지 마십시오.
보안 고려 사항
- 스킬을 설치하거나 실행하는 데 비밀 정보가 필요하지 않습니다. 사용자가 요청한 특정 작업에 대해서만 자격 증명을 제공합니다.
.full.credentials및.env를 로컬에서만 읽습니다 — 절대 전송되지 않고, 절대 커밋되지 않습니다.- 브라우저 자동화는 사용자 자신의 Chrome을 Chrome DevTools Protocol을 통해 로컬 포트에서 사용하며 로그인된 세션을 재사용합니다. 아무것도 저장되거나 유출되지 않습니다. 인증된 계정에 대한 작업은 항상 쓰기당 확인을 거칩니다 — 자율 QA는 테스트 환경 전용입니다.
- 실행 중에 생성된 모든 자격 증명은 회전 노트와 함께 전용 자격 증명 아티팩트에 격리되며 — 산문에 묻히지 않습니다.
- 되돌릴 수 없는 작업은 항상 명시적 사전 승인이 필요합니다. 자율성은 되돌릴 수 있는 작업만 다룹니다.
DevOtts 작성.