Skip to content
← 전체 스펙 문서

적합성

버전 1.1. 상태: 안정(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).
  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/와 drafts/를 갖춘 .dwp/ 디렉터리를 담아야(MUST) 하며, .dwp/는 gitignore되어야(MUST) 합니다. tmp/ 스크래치 공간이 존재해야(SHOULD) 하며 gitignore되어야(SHOULD) 합니다.
  6. 방법론 스킬이 해석 가능함. Deep Work Plan 스킬은 리포지토리 안의 에이전트가 그 하위 스킬을 호출할 수 있도록 설치되거나 참조되어야(MUST) 합니다.

리포지토리는 애드온이 하나도 없어도 완전히 적합합니다. 애드온(devcontainer, Dailybot, dependency-upgrade, design-system)은 선택형이며 적합성에 필수여서는 안 됩니다(MUST NOT).

잘 구성된 계획

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

  1. 모든 작업은 명시적 범위, 인수 기준, 그리고 적어도 하나의 검증 게이트(객관적으로 합격하거나 불합격하는 명령이나 검증)를 선언해야(MUST) 합니다.
  2. 새로운 핵심 기능을 추가하거나 제품 동작을 변경하는 모든 작업은 그 동작에 대한 자동화된 테스트 커버리지를 인수 기준에 포함해야(MUST) 하고, 검증 게이트에서 빌드만이 아니라 리포지토리의 테스트를 그 lint 및 타입 검사 검사와 함께 실행해야(MUST) 합니다. 기존 테스트는 통과 상태를 유지해야(MUST) 합니다. 동작 변경은 그것이 깨뜨리는 테스트를 삭제하거나 건너뛰는 대신 갱신해야(MUST) 합니다. 순수 문서, 설정, 또는 연구 작업은 테스트 생성에서 면제되지만 그래도 리포지토리의 게이트를 실행합니다.
  3. 인증, 입력 처리, 비밀 값이나 설정, 네트워크 표면, 또는 의존성을 건드리는 모든 작업은 해당 변경의 보안 기대치를 인수 기준에 담아야(MUST) 하고, 모든 커밋에는 비밀 자료가 없어야(MUST) 합니다.
  4. 계획은 작업이 중단을 견디고 다른 에이전트가 재개할 수 있도록 진행 상황을 영속화해야(MUST) 합니다.
  5. 계획은 세 개의 필수 최종 작업 — 보안 검토, 스킬 & 에이전트 발견, 임원 보고서 — 을 포함해야(MUST) 합니다. 치명적인 보안 발견은 수정되거나 명시적으로 수용될 때까지 완료를 차단합니다.
  6. 작업은 긴 과정에서 방향 이탈을 막기 위해 실행 전에 계획의 목표에 다시 닻을 내려야(SHOULD) 합니다.

적합성 검증

적합성은 점검이 아니라 기계적으로 검증되어야(SHOULD) 합니다. /dwp-verify를 실행하면 위 기준에 대비한 합격/불합격 보고서가 만들어집니다. AGENTS.md의 존재와 실제 내용, CLAUDE.md 해석, docs/ 범주, .agents/ 카탈로그 대 디스크 일치, .dwp/와 tmp/의 gitignore 상태, 그리고 — 계획의 경우 — 모든 작업이 인수 기준과 검증 게이트를 담고 있는지가, 동작을 변경하는 작업에 대한 테스트 커버리지와, 보안 검토를 포함한 세 개의 필수 최종 작업의 존재와 함께 확인됩니다.

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