문서화 표준

버전 5.0.0. 이 표준은 Deep Work Plan이 구조, 작업, 진행 상황을 문서화하는 방식과, 저장소가 에이전트가 안전하게 행동할 수 있도록 스스로를 문서화하는 방식을 정의합니다. DWP 방법론 아래에서 생성된 모든 계획에 적용됩니다. 이번 버전은 이 문서 자체의 버전을 그것이 동반하는 DWP 표준과 맞춥니다 — 기존 요건은 전혀 변경되지 않습니다 — 그리고 아래에서 설명하는 간결한 색인 예산 강제와 기능 계층을 추가합니다. 키워드 MUST, SHOULD, MAY는 RFC 2119에 정의된 대로 사용됩니다.

간결한 진입점으로서의 AGENTS.md

루트 AGENTS.md 파일은 150~500줄 예산 내에 머물러야(SHOULD) 합니다. 생성되거나 하네스가 유지 관리하는 내용이 이를 초과하게 되면, 에이전트는 그 세부 사항을 소유하는 docs/ 가이드(또는 모듈/기능 문서)로 옮기고 색인에서 그것을 링크해야(MUST) 합니다 — 아무것도 버려지지 않고 재배치될 뿐이며, 색인은 옮겨진 내용을 받은 모든 문서를 링크해야(MUST) 합니다. 예산을 초과한 기존의 수작업 AGENTS.md는 결코 조용히 다시 쓰이지 않습니다: 에이전트는 구체적인 이전 계획(무엇을 어디로 옮기고 어떤 링크를 추가할지)을 제안하고, 개발자의 동의가 있을 때만 이를 적용합니다. 적합성 검사기는 이 예산을 권고 사항으로 취급합니다. 줄 수는 객관적이지만 저작권(누가 썼는지)은 그렇지 않기 때문입니다 — 이 MUST는 파일을 생성하거나 갱신하는 하네스를 구속하는 것이지, 누가 그것을 작성했는지에 대한 검사기의 추측을 구속하는 것이 아닙니다. AGENTS.md는 존재하지 않는 docs/ 파일을 링크해서는 안 됩니다(MUST NOT).

모듈별 문서화 계층(아래) 위에는 **기능 계층(feature tier)**이 있습니다: 하나의 모듈보다 큰 주요 기능 영역은 자신의 코드 옆에 자체 docs/ 폴더를 가지며, 자체 README.md를 통해 진입합니다. 어떤 영역이 두 개 이상의 주요 모듈에 걸쳐 있거나, 독립된 하위 앱이나 서브시스템 디렉터리를 소유하거나, 여러 소비자가 의존하는 자체 계약(API 표면, 이벤트나 스키마 계약)을 가지고 있으면 이 계층에 해당합니다. 어떤 영역이 주요 영역으로 기록되면, 그 기능 docs/가 존재해야(SHOULD) 하며, 가장 중요한 항목들은 모듈별 문서와 정확히 동일한 방식으로 그 영역이 걸쳐 있는 모듈들과 루트 AGENTS.md 색인에서 링크되어야(SHOULD) 합니다. 의도적으로 문서화되지 않은 채 남겨진 영역은 기록된 이유를 가집니다 — 이는 누락이 아니라 결정입니다.

계획 README

모든 계획은 다음을 담은 README.md를 가져야(MUST) 합니다.

제목(Title) — # Deep Work Plan: <name>.
목표(Goal) — 계획의 목적에 대한 산문 진술.
원천 자료(Source material) — 정규 입력에 대한 링크나 경로(선택).
작업(Tasks) — 작업 번호, 이름, 상태 체크박스를 담은 Markdown 표.
상태(Status) — <n>/<total> tasks complete 형식의 줄.

작업 파일

각 작업 파일은 <n>.task_<slug>.md라는 이름이어야(MUST) 하며 열 절 구조를 담아야 합니다 — 아홉 개의 고전적 절 더하기 변경 표면(Touched Surface): 작업이 바꾸는 것과 검증되어야 할 것 사이의 계약(계획된 표면 대 실제 표면, 영향받는 소비자, 고립(isolated)·이음새(seam)·공유/핵심(shared/core)·알 수 없음(unknown) 중 하나의 위험 등급, 사용된 테스트 매핑, 그리고 이유와 함께 선택된 게이트).

PROGRESS.md

PROGRESS.md는 추가 전용 실행 로그입니다. 각 항목은 다음을 기록해야(MUST) 합니다.

ISO 8601 타임스탬프.
작업 번호와 이름.
수행한 일.
모든 이탈이나 건너뜀 이유.

상태 표시

[ ] — 시작 안 함.
[~] — 진행 중.
[x] — 완료.
[!] — 차단됨.

제목

모든 제목은 문장형 대소문자(sentence case)를 사용해야(MUST) 합니다. 문서는 마케팅 표현과 느낌표를 피해야(SHOULD) 합니다.

Final Review, 작업 안의 스킬 결정, 선택적 보고서

이 버전에서 작성된 모든 계획은 정확히 하나의 필수 작업으로 끝나야(MUST) 합니다: Final Review — 계획의 전체 변경 집합에 대한 보안 점검, 마지막 관련 상태에서 이루어지는 최종 상태 검증, 그리고 스킬 결정의 조정. 치명적인 보안 발견은 완료를 차단합니다.

작업 안의 스킬 결정. 모든 작업의 완료 & 로그는 **스킬 처분(disposition)**을 담습니다 — none, 기존 스킬이나 에이전트에 대한 갱신, 명명된 생성, 또는 이유와 소유자를 담은 연기. 정당한 저작은 해당 작업 안에서, 검증 게이트 이전에, .agents/ 카탈로그에 대한 중복 검사 후에 이루어집니다; 정당한 항목은 계획의 스킬 후보 원장에 안정적인 후보(T{task}-{seq})로 기록됩니다.
임원 보고서는 요청 시에만 선택적. 완료 시 한 번 제안되며, 명시적인 요청이 있을 때만 지속 가능한 증거로부터 생성됩니다. 응답이 없거나 무인 실행이면 보고서 없이 계획이 완료 상태로 남습니다.
레거시 계획. 이전 버전에서 작성된 계획은 세 개의 필수 최종 작업으로 끝나며 적합 상태를 유지합니다 — 적합성 검사기는 그 형태를 수용해야(MUST) 합니다.