문서화 표준

버전 범위: 이 문서는 보존된 v5.0.0 기반 문서입니다. 현재 표준인 DWP 7.0.0은 사양 색인에 나열된 해당 V6_*.md 및 V7_*.md 확장도 요구합니다. 기존 v5 및 v6 계획은 기록된 규칙을 유지합니다.

버전 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. 이 작업은 순서대로 (a) 필수 로컬 AI Diff Reviewer 리뷰를 포함한, 계획의 전체 변경 집합에 대한 보안 점검, (b) 마지막 관련 상태에서 이루어지는 최종 상태 검증, (c) 스킬 결정의 조정, (d) 변경된 모든 표면에 대한 문서 조정, (e) 계획의 기록이 서로 일치하는 상태에서의 완료를 실행합니다. 치명적인 보안 발견은 완료를 차단합니다.

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