Skip to content
Deep Work Plan이 오늘 Product Hunt에 출시됐어요 추천하기
← 전체 스펙 문서

적합성

버전 1.3. 상태: 안정(Stable). 이 문서는 리포지토리가 Deep Work Plan 적합 — 즉 AI-first이며 에이전트가 조종 가능 — 하다는 것이 무엇을 뜻하는지 정의합니다. 키워드 MUST, MUST NOT, SHOULD, SHOULD NOT, MAY는 RFC 2119에 기술된 대로 해석됩니다.

적합성은 “AI-first”가 인상이 아니라 객관적이고 확인 가능한 속성이 되도록 존재합니다. 리포지토리는 아래 기준을 충족하거나 충족하지 못하거나 둘 중 하나입니다. verify 하위 스킬(/dwp-verify)이 그것들을 기계적으로 확인합니다.

적합한 리포지토리

DWP 적합 리포지토리는 다음을 모두 충족해야(MUST) 합니다. 모든 산출물은 리포지토리에 맞게 추론되어야 합니다 — 실제 언어, 프레임워크, 명령에 적응되어야 합니다. 범용 스텁, 플레이스홀더, 또는 다른 리포지토리에서 복사한 내용은 기준을 충족하지 않습니다.

  1. 루트의 AGENTS.md. 리포지토리는 (a) 문서 색인, (b) 리포지토리의 필수 규칙, (c) 이 리포지토리에서 실제로 실행 가능한 명령으로 이루어진 Quick Commands 블록을 포함하는 루트 AGENTS.md를 담아야(MUST) 합니다. 플레이스홀더 명령(예: npm을 사용하지 않는 리포지토리의 npm test)은 나타나서는 안 됩니다(MUST NOT). 색인은 존재하지 않는 docs/ 파일을 링크해서는 안 되며(MUST NOT), 파일은 150~500줄 예산 내에 머물러야(SHOULD) 하고, 무한정 커지는 대신 세부 사항을 docs/로 옮기고 링크해야 합니다.
  2. CLAUDE.md가 AGENTS.md로 해석됨. CLAUDE.md가 존재하고 AGENTS.md로 해석되어야(MUST) 합니다(심링크, 또는 단일 진실 공급원을 보장하는 동등한 것). 둘은 어긋나서는 안 됩니다(MUST NOT).
  3. docs/ 계층. 리포지토리는 표준 범주(아키텍처, 표준, 테스트, 개발 명령, 보안, 에이전트 온보딩)를 실제 리포지토리별 내용으로 다루는 docs/ 디렉터리를 담아야(MUST) 합니다. 복잡한 모듈은 자체 README.md를 갖춰야(SHOULD) 합니다. 테스트 가이드는 실제 테스트, lint, 타입 검사 도구 사슬을 — 또는 그것이 전혀 없는 리포지토리의 경우, 온보딩 중에 스택으로부터 제안된 구체적인 셋업을 — 정의해야(MUST) 합니다. 비어 있는 테스트 가이드나 “테스트 없음”은 이 기준을 충족하지 않습니다. 동작을 검증하는 정의된 방법이 없으면, 계획에는 객관적인 검증 게이트가 없습니다.
  4. .agents/ 홈. 리포지토리는 agents/, commands/, skills/를 갖춘 .agents/ 디렉터리와 디스크에 있는 것과 일치하는 .agents/docs/ 아래의 카탈로그를 담아야(MUST) 합니다. dwp-* 명령은 설치된 스킬에 대한 얇은 위임자여야(MUST) 합니다. .claude 경로는 .agents로 해석되어야(MUST) 합니다.
  5. gitignore된 .dwp/ 작업 공간. 리포지토리는 plans/를 갖춘 .dwp/ 디렉터리를 담아야(MUST) 하며, .dwp/는 gitignore되어야(MUST) 합니다. tmp/ 스크래치 공간이 존재해야(SHOULD) 하며 gitignore되어야(SHOULD) 합니다.
  6. 방법론 스킬이 해석 가능함. Deep Work Plan 스킬은 리포지토리 안의 에이전트가 그 하위 스킬을 호출할 수 있도록 설치되거나 참조되어야(MUST) 합니다.

리포지토리는 선택적 애드온이 하나도 없어도 완전히 적합합니다. 선택적 애드온(devcontainer, Dailybot, dependency-upgrade, design-system)은 적합성에 필수여서는 안 됩니다(MUST NOT). 표준 2.3.0부터 AI Diff Reviewer 로컬 리뷰(벤더 스킬 + 확장 파일)는 기준선의 일부입니다. 그 부재는 2.3.0 이상을 선언한 리포지토리에 대해서는 실패이고, 레거시 리포지토리에 대해서는 하니스 버전 발견 사항입니다. 그 CI 표면은 선택적으로 남습니다.

잘 구성된 계획

.dwp/plans/의 Deep Work Plan은 다음일 때 잘 구성된 것입니다.

  1. 모든 작업은 명시적 범위, 인수 기준, 그리고 적어도 하나의 검증 게이트(객관적으로 합격하거나 불합격하는 명령이나 검증)를 선언해야(MUST) 합니다.
  2. 새로운 핵심 기능을 추가하거나 제품 동작을 변경하는 모든 작업은 그 동작에 대한 자동화된 테스트 커버리지를 인수 기준에 포함해야(MUST) 하고, 검증 게이트에서 빌드만이 아니라 리포지토리의 테스트를 그 lint 및 타입 검사 검사와 함께 실행해야(MUST) 합니다. 기존 테스트는 통과 상태를 유지해야(MUST) 합니다. 동작 변경은 그것이 깨뜨리는 테스트를 삭제하거나 건너뛰는 대신 갱신해야(MUST) 합니다. 순수 문서, 설정, 또는 연구 작업은 테스트 생성에서 면제되지만 그래도 리포지토리의 게이트를 실행합니다.
  3. 인증, 입력 처리, 비밀 값이나 설정, 네트워크 표면, 또는 의존성을 건드리는 모든 작업은 해당 변경의 보안 기대치를 인수 기준에 담아야(MUST) 하고, 모든 커밋에는 비밀 자료가 없어야(MUST) 합니다.
  4. 계획은 작업이 중단을 견디고 다른 에이전트가 재개할 수 있도록 진행 상황을 영속화해야(MUST) 합니다. 작업은 그 검증 게이트 기록 중 하나라도 여전히 실패한 미해결 실행을 보여주는 동안에는 completed로 기록되어서는 안 되며(MUST NOT), 작업 자체의 완료 로그는 기록된 상태와 모순되어서는 안 됩니다(MUST NOT)(예를 들어 로그가 여전히 “Status: pending”으로 읽히는 completed 작업은 통과가 아니라 결함입니다).
  5. 계획은 기록된 최종 리뷰로 닫아야(MUST) 합니다. 이 버전에서 작성된 계획은 정확히 하나의 필수 Final Review — 보안 점검, 최종 상태 검증, 스킬 조정 — 로 끝나야(MUST) 합니다. 이전 버전에서 작성된 계획은 세 개의 필수 최종 작업(보안 검토, 스킬 & 에이전트 발견, 임원 보고서)으로 끝나며 적합 상태를 유지합니다. 치명적인 보안 발견은 수정되거나 명시적으로 수용될 때까지 완료를 차단합니다. 완료 자체는 단순한 상태 전환이 아니라 검증되고 복구 가능한 트랜잭션입니다: 종단 작업은 상태를 쓰기 전에 완성된 계획의 산출물을 검증하고 기계로 확인 가능한 FINALIZATION.json 영수증을 남기는 보호된 발행 단계를 통해 마감됩니다; 중단된 발행은 증거로부터 복구되며, 결코 조용히 완료로 재선언되지 않습니다. 게이트 기록이 인용하는 모든 증거 포인터는 계획 자체의 폴더 안에서 해석되어야(MUST) 합니다 — 매달려 있거나 벗어난 포인터는 통과 증거가 아니라 발견 사항입니다.
  6. 작업은 긴 과정에서 방향 이탈을 막기 위해 실행 전에 계획의 목표에 다시 닻을 내려야(SHOULD) 합니다.

적합성 검증

적합성은 점검이 아니라 기계적으로 검증되어야(SHOULD) 합니다. /dwp-verify를 실행하면 위 기준에 대비한 합격/불합격 보고서가 만들어집니다. AGENTS.md의 존재와 실제 내용, CLAUDE.md 해석, docs/ 범주, .agents/ 카탈로그 대 디스크 일치, .dwp/와 tmp/의 gitignore 상태, 그리고 — 계획의 경우 — 모든 작업이 인수 기준과 검증 게이트를 담고 있는지가, 동작을 변경하는 작업에 대한 테스트 커버리지 및 기록된 최종 리뷰의 존재와 함께 확인됩니다. 계획의 경우, 계획의 마크다운과 기계 가독 상태가 서로 일치하는지도 확인합니다(README와 state.json이 어긋나 있는 것은 결코 조용히 통과되지 않는 발견 사항입니다), 완료된 작업이 모순되지 않는 게이트 및 로그 증거를 담고 있는지도, 그리고 — 완료된 계획이 그 지점에 도달한 경우에는 — 발행 영수증이 그것이 주장하는 완료를 뒷받침하는지도 확인합니다. 검사기는 버전 인식입니다. 레거시 계획(세 개의 필수 최종 작업, 변경 표면 없음)을 적합한 것으로 수용해야(MUST) 하며, 이 버전을 선언했지만 그 아래에서 객관적으로 무효인 계획을 거부해야(MUST) 합니다. 또한 누락되었거나 오래된 DWP standard: 출처 표시 줄을, 표적 하니스 업그레이드를 지목하는 발견 사항으로 보고합니다. 기계적 계층은 자신의 한계에 정직합니다: 유능한 인터프리터(Python 3.9+)가 없으면 검사를 건너뛰는 대신 0이 아닌 종료 코드와 명시적인 UNVERIFIED 판정과 함께 종료합니다 — 검사기는 검증하지 않은 결과를 결코 보고하지 않습니다.

리포지토리는 온보딩 후 그리고 완료된 각 계획 후 다시 검증되어야(SHOULD) 합니다. 그래야 적합성이 한 번 단언되는 것이 아니라 유지됩니다.