plan-it은(는) 무엇을 하나요?
막연한 요구사항을 구축 가능한 전달 패키지로 전환합니다. 이것은 계획 컨덕터입니다: /build-it이 시작되는 지점에서 정확히 끝나는 라이프사이클의 규율 있는 전반부입니다. 발견(실제 현황 조사), 명세(설계 문서 작성), 애자일 분할(PRD, 에픽, 테스트, 공유 계약)을 수행한 후 전달합니다.
/plan-it ─────────────► docs/ + delivery/ ─────────────► /build-it
(발견 → 명세 → 계획) (구축 가능한 패키지) (구축 실행)
사람이 직접 사용할 수 있으며, 새로운 요구사항을 받아 작업자를 파견하기 전에 전달 패키지로 변환해야 하는 모든 오케스트레이션 컨덕터 에이전트가 사용할 수 있습니다.
다섯 가지 불가침 규칙 (강제하세요 — 단순히 제안하지 마세요)
이것들은 모든 성공적인 실행에서 역설계된 하중 지지 규칙입니다. 하나라도 위반하면 다운스트림 구축이 표류하거나 조용히 실패합니다.
-
병렬 계획 전에 공유 CONTRACT를 동결하십시오. CONTRACT는 법입니다: 표준 엔티티, 스키마, API/인터페이스, 열거형, 저장소/브랜치 맵, 그리고 "배송 완료"의 정의. 스쿼드는 이에 맞춰 작성합니다; 모든 교차 발견은 날짜가 있는 수정(v1.0 → v1.1 …)으로 다시 통합됩니다. 동결된 계약 없음 → 병렬 스쿼드 없음.
-
모든 인간 전용 결정을 하나의 게이트로 일괄 처리하십시오. 되돌릴 수 없는 결정(저장소 토폴로지, 호스팅, 제품명, 아키텍처 모드, 구축 vs 구매)을 미리 결정하지 마십시오. 각각에 권장 사항을 첨부하여 함께 제시하고, 인간이 번호를 붙여 답변하도록 하십시오. 이 게이트는 인간이 비전을 주입하는 곳입니다 — 단순히 옵션을 선택하는 것이 아닙니다 — 당신이 제안하지 않은 개념을 추가할 여지를 남기십시오. 각 답변을 소유자 + 날짜로 잠급니다.
-
디스크에서 모든 에이전트의 출력을 검증하십시오 — "유휴 ≠ 전달됨." 팀이 유휴 상태가 된다고 해서 파일을 썼다는 의미는 아닙니다. 팬아웃 후에 실제 경로가 존재하고 비어 있지 않은지 확인한 후 진행하십시오. 팀이 출력을 메시지로 보관한 경우, 정확한 절대 경로에
Write하도록 지시하십시오. "완료"를 절대 신뢰하지 마십시오. -
동결 전에 저장소가 아닌 라이브 시스템에 대해 계획을 검증하십시오. 실행 중인 시스템을 다루는 계획의 경우, 저장소는 가설입니다; 배포된 현실이 진실이며, 둘은 표류합니다. CONTRACT를 동결하기 전에 실제 시스템에 대해 검증하고 관찰 결과를 (저장소에서 추론된 추측이 아닌) 기록하십시오. 실전 검증 완료: 한 프로그램에서 모든 비행 중 수정 사항은 저장소에서 추론된 가정이 현실과 모순되어 발생했습니다 — 잘못된 표준 식별자(매니페스트가 배포된 카탈로그에서 표류됨), 존재하지만 죽은 호스트를 가리키는 구성 값, 이미 배포된 "구축 예정" 구성 요소, 그리고 발견된 자격 증명이 잘못된 것. 구체적인 검사는 3단계의 라이브 검증 게이트를 참조하십시오.
-
기계를 실행하고, 산문을 실행하지 마십시오. 파이프라인의 제어 흐름은
machine.json(명시적 상태 차트)에 있으며, 이 문서에 있지 않습니다 — 이 산문은 기계를 설명합니다. 호출 시, (대상 프로젝트에서).plan-it/state.json을 읽거나 초기화하고state에서 재개하며, 모든 전환 시에 기록합니다. 모든 보호된 전환에서 가드의 매핑된 하위 명령(node scripts/gate-check.mjs <check> …)을 실행하고 0이 아닌 종료 코드에서 절대 진행하지 마십시오 — 수정, 재실행, 전환. Node를 사용할 수 없는 경우 동일한 검사를 수동으로 수행하고 상태 파일에 기록합니다(저하, 절대 중단하지 않음). 전체 프로토콜:references/machine.md.
결정론적 코어 (v2) — 왜 기계인가
산문("1단계 수행, 게이트를 절대 건너뛰지 마십시오")으로 작성된 제어 흐름은 결정론 문헌에서 산문 제어 흐름이라고 부릅니다: 이는 긴 요약 경향이 있는 컨텍스트에서 모델의 규율에 의존하며, 때로는 모델이 따르지 않을 수 있습니다. v2는 적절한 고도에서 이를 반전시킵니다 — 가장자리에서는 비결정론, 코어에서는 결정론:
machine.json— XState v5 호환 파이프라인 상태 차트: 15개 상태, 세 개의 인간 게이트(meta.gate+meta.human), 보호된 전환,parallelPlanning의AMENDMENT자체 루프. stately.ai/viz에 붙여넣어 시각화하십시오..plan-it/state.json— 지속된 실행: 현재 상태, 게이트 승인(소유자 + 날짜), 계약 버전, 검증된 아티팩트 레지스트리, 기록. 이것이 충돌이나 새 세션에서 실행이 생존하는 이유입니다.scripts/gate-check.mjs— 종료 코드로서의 가드:verify(규칙 3, 유휴 ≠ 전달됨),freeze(규칙 1, 계약 없음 → 스쿼드 없음),handoff(플레이북 §F의 기계화 가능한 절반),state(규칙 2, 게이트 기록됨),adversary(규칙 6 / D4 — 실패 모드 깊이: 모델링된 기계는 다섯 가지 캐스케이드 클래스를 포함하거나 면제해야 함; 선형 워크플로의 경우 해당 없음).LINT_CLEAN및ADVERSARY_CLEAN전환(verify -> adversaryGate -> handoff)은 마지막 두 개를 게이트합니다.
모호한 단계 — 발견, 합성, 명세 작성, 판단 —은 LLM-At-The-Node로 유지됩니다(기계에서 llmAtTheNode로 태그됨). 이를 공식화하지 마십시오; 모델링은 혼란을 대체할 때만 의례가 아닙니다. 세부 사항, 상태 파일 스키마 및 재개 프로토콜: references/machine.md.
하드 강제 (v2.1, Claude Code에서만 플러그인 설치): PreToolUse 훅(scripts/hooks/planit-guard.mjs)은 실행의 계약이 동결되지 않은 동안 PRD/에픽 전달물에 대한 Write/Edit 호출을 거부합니다 — 규칙 1은 명령이 아니라 하네스가 거부하는 것이 됩니다. 실패-개방: 계획-IT 작업이 아닌 것은 건드리지 않습니다. 스킬 전용 설치는 대신 규칙 5 규율에 의존합니다.
테스트 계약 — 품질 차별화 요소 (이것을 불가침으로 만드십시오)
전달된 코드 품질을 가장 높이는 단일 요소: 모든 PRD/에픽은 자체 테스트 계약을 생성하는 것으로 끝납니다 — 구현을 강조하는 최대 20개의 구체적인 사용 사례/시나리오 — 기능이 100% 통과할 때까지 "완료"되지 않습니다. 빌드 에이전트는 기능만 전달하는 것이 아니라 계약을 충족해야 하며, 녹색이 될 때까지 /iterate합니다.
이것은 명명된 입증된 규율입니다: Specification by Example(Gojko Adzic) + 코드용 ATDD/BDD(구체적인 예제는 실행 가능한 인수 테스트 및 살아있는 문서가 됨) 및 스킬/LLM 기능용 Eval-Driven Development(예상 출력으로 골든 등록, 통과할 때까지 반복). 계획 시간에 사례를 작성하는 것이 핵심입니다 — 그것들은 사후 고려 사항이 아니라 바인딩 계약이 됩니다.
테스트 계약의 규칙:
- 계획 시간에 작성 — 각 에픽/PRD 작성의 마지막 단계는 테스트 계약입니다. 예상 출력은 지금 등록됩니다("먼저 설계; 예상 출력 등록"), 빌드 중에 발견되지 않습니다.
- 기능당 최대 ~20개의 고품질 사례 — 실제 동작 + 가장자리를 강조하기에 충분함; 수천 개의 얕은 사례가 아님(품질 > 수량 — 평가 문헌에 따르면 자동 대량 = "슬롭"). 실제/가능한 실패 모드에서 사례를 도출하십시오. 형태별 개수 규칙: 대형 Shape-1 다중 스쿼드 프로그램은 에픽당 10개 이상의 사례 하한을 유지합니다(각 에픽은 큰 기능); 소형 형태(단일 스킬/기능, S/M)는 패키지 전체에 걸쳐 총 ~20개 사례를 작성합니다(에픽당 소수). 절대 동시에 둘 다 하지 마십시오 — 형태로 선택하여 리뷰어가 올바른 소형 패키지를 과소 테스트로 표시하지 않도록 하십시오.
- 바인딩 — 완료 정의 = 계약의 100% 통과; 그때까지는
/iterate. 부분 배송 없음; 모의에서 VERIFIED 없음(대상에 도달할 수 없는[REAL]사례 -> 가짜 녹색이 아닌 IMPLEMENTED-NOT-VERIFIED). - 구현별 테스트 유형 선택(다음 중 하나 이상: 단위 / e2e / 사용 사례 / 스트레스):
| 구현 | 테스트 유형 | 방법 |
|---|---|---|
| CRUD / REST API | 사용 사례(해피+에지) + e2e | 모든 시나리오를 API를 통해 그리고 Chrome CDP를 사용하여 UI를 통해 실행(chrome-cdp-control); 로직 단위 테스트 |
| 스킬 / 프롬프트 / LLM 함수 | 예상 출력이 있는 사용 사례 | 실행, 실제와 예상 비교 — 폐쇄형 출력은 정확히 일치, 개방형 출력은 루브릭 / LLM-as-judge(make-eval, promptfoo, DeepEval G-Eval) |
| 에이전트 / 상태 저장 / 다단계 | 스트레스 시나리오 + 사용 사례 | 6개 축: 비동기, 팬아웃, 에스컬레이션, 인간 게이트, 재귀, 사이클 가드(설정/예상/통과) |
| 순수 로직 / 라이브러리 | 단위 + 속성 기반 | 열거된 사례 + 불변성 |
| 데이터 파이프라인 / 마이그레이션 | 골든 값 + e2e | 수동 계산된 예상 값; 멱등성/롤백 |
| 부하/남용 표면이 있는 모든 것 | 스트레스 / 적대적 | 동시성, 속도, 잘못된 입력, 레드팀 |
- 실행 경로:
/full-qa가 계약을 실행하고,/iterate가 100%까지 반복하며,chrome-cdp-control이 UI 시나리오를 구동합니다. 계약은 plan-it에서 build-it으로의 다리입니다:/build-it의 완료 정의 = 이 계약.
문법 및 계약 헤더 형식: references/formats.md(테스트 계약 블록 + §4–5).
자율성 자세 (자율적 폭발로 안내됨)
높은 노력으로 연구 및 작성을 자율적으로 실행하지만, 세 개의 게이트에서 중지합니다:
| 게이트 | 시기 | 질문 |
|---|---|---|
| G1 — 범위 | 인테이크 후(2단계) | 노력을 소모하기 전에 크기(기능 vs 프로그램) + 번호가 매겨진 완료 정의 확인 |
| G2 — 결정 | 명세 초안 작성 후(7단계) | 각각에 권장 사항이 있는 "당신만이 내릴 수 있는 결정" 일괄 처리 |
| G3 — 전달 | 애자일 분할 전(8단계) | "명세가 정렬된 것으로 보입니다 — PRD/에픽으로 진행할까요?" |
게이트 사이의 모든 것은 감독 없이 실행됩니다. 시작 시 /effort xhigh을 권장하십시오(직접 설정할 수 없음 — 사용자에게 아직 실행하지 않은 경우 /effort xhigh을 실행하라고 알리십시오).
0단계 — 인테이크
먼저 기계(규칙 5): 대상 프로젝트에 .plan-it/state.json이 존재하는 경우 node scripts/gate-check.mjs state .plan-it/state.json을 실행하고 인쇄된 상태에서 재개하십시오 — 이미 history에 있는 단계를 다시 시작하지 마십시오. 존재하지 않는 경우 지금 intake 상태로 생성하고(스키마는 references/machine.md에 있음) 실행의 나머지 부분 동안 모든 전환에서 업데이트된 상태로 유지하십시오.
요구사항을 도착하는 모든 형태로 받아들이십시오: 브레인 덤프, 붙여넣은 녹취록, 원하는 목록, 또는 한 줄. 내용이 아닌 포인터를 기대하십시오 — 세션 이름(/read-chat "<name>"), 저장소 경로, 문서 폴더. 당신의 임무는 실제 현황을 가져오는 것이지, 건네받는 것이 아닙니다.
사전에 캡처:
- 사용자 자신의 말로 된 원시 비전(나중에
02 §1에서 다시 인용할 것입니다). - 이전 세션/저장소/문서에 대한 포인터를 연구합니다.
- 사용 사례(자동 감지 — 게이트 G1에서 패키징 형태를 결정합니다):
- 새로운 단일 앱, 그린필드 · 대형 기존 저장소의 기능 · 처음부터 다중 하위 시스템 프로그램 · 다중 앱 플랫폼(많은 PRD) · 리팩터링/마이그레이션/부채 · 연구 스파이크(아직 구축 없음) · PM/보드 자동화 · 이미 구축된 시스템 문서화/감사.
- 연구 방법: 기본값은 xhigh에서 병렬 Claude 팀.
요구사항이 포인터 없이 기존 저장소가 있는 하나의 모호한 단락이라면 괜찮습니다 — 사전 검증(3단계)이 대상을 찾을 것입니다.
1단계 — 완료 정의 잠금
모호한 산문을 번호가 매겨진 개별적으로 검증 가능한 완료 정의 + 짧은 명시된 가정 목록으로 재구성합니다. 이것은 계획 작업 자체에 대한 사용자와의 계약입니다. 예시 형태:
이 계획 실행의 완료 정의:
1. 실제 현황 조사 결과 문서(모든 주장 -> 경로:줄 또는 표)
2. 각 결과/모순을 해결하는 비전 + 아키텍처 문서
3. 데이터/인터페이스 계약
4. ... (자동 크기 조정 — 2단계 참조)
N. 전달: 계약 동결, 각각 10개 이상의 테스트가 있는 PRD+에픽, 킥오프 프롬프트
가정: <목록>
2단계 — 범위 및 형태 거버너 ⏸ 게이트 G1
노력을 소모하기 전에 크기(얼마나) 그리고 형태(어떤 형태)를 선택하십시오. 둘 다 사용자와 확인하십시오.
크기는 아티팩트 수를 조정합니다:
| 신호 | 크기 |
|---|---|
| 단일 기능, 1개 하위 시스템 | S |
| 다중 기능 / 새 하위 시스템, 1–2개 저장소 | M |
| 처음부터 프로그램 / 많은 하위 시스템 | L |
형태는 사용 사례별로 선택됩니다(전체 정의 + 사용 사례->형태 표는 references/templates.md PART D에 있음):
- 다중 문서 +
delivery/(기준) — 처음부터 프로그램, 병렬 스쿼드. - 단일 파일 PRD-as-everything — 그린필드 단일 앱; 계약이 G-규칙으로 인라인됨.
- 연구 -> 잠긴 아키텍처 -> 마스터+단계 PRD — 대형 기존 저장소의 기능.
implementation/<name>/와 번호가 매겨진 PRD-NN — 다중 앱 플랫폼, 많은 PRD.- 리팩터링/부채 작업 스트림 카탈로그 — 브라운필드 제자리. (+ 연구 스파이크, 실행 가능 보드 및 역방향 문서 모드 — PART D 참조.)
단계는 동일합니다 — 아티팩트 수와 형태만 변경됩니다. 기능에 4개 스쿼드 조직을 제공하지 마십시오; 브라운필드 리팩터링에 그린필드 비전 문서를 제공하지 마십시오. 선택한 크기 + 형태 + 번호가 매겨진 완료 정의를 제시하고 진행하기 전에 승인을 받으십시오. 승인 시 .plan-it/state.json에 G1 = {approved, owner, date} 및 선택한 크기/형태를 기록하십시오 — G1_APPROVED 전환은 gateRecorded에 의해 보호됩니다.
3단계 — 사전 검증
팬아웃 전에 정확한 대상을 찾아 에이전트가 모호한 지침이 아닌 정확한 경로를 얻도록 하십시오:
- 세션 읽기 스킬(
/read-chat또는 유사)이 설치된 경우 포인터 세션을 해결하십시오; 그렇지 않으면 관련 기록이나 요약을 요청하십시오. - 명명된 저장소를
ls/grep하십시오;docs/, 스키마 파일, 진입점을 찾으십시오. - 저장소가 볼트 연결된 경우(해당
CLAUDE.md에 따라) 위키 핫 캐시/인덱스를 읽으십시오.
출력: 연구 팀을 시드하는 {하위 시스템 -> 읽을 정확한 경로} 목록.
라이브 검증 게이트(규칙 4) — 계획이 실행 중인 시스템을 다루는 경우
저장소는 되어야 하는 것을 알려줍니다; 라이브 시스템은 있는 것을 알려줍니다. 8단계 동결 전에 이를 수행하고 결과를 관찰된 사실로 계약에 기록하십시오:
- 구성 도달 가능성, 존재 여부가 아님. 계획이 의존하는 모든 환경/구성 레버(기본 URL, API 호스트, 기능 플래그)에 대해 적중하십시오 — 설정되어 있는지 확인하는 것만으로는 충분하지 않습니다. 값이 죽은 호스트로 설정되어 "존재하는가" 검사를 통과하고 조용히 프로덕션을 망칠 수 있습니다.
- 라이브 레지스트리 / 표준 식별자. 중