DWP 스펙

버전 4.0.0. 상태: 안정(Stable). 이 문서는 Deep Work Plan(DWP) 방법론의 규범적 스펙입니다. 키워드 MUST, MUST NOT, SHOULD, SHOULD NOT, MAY는 RFC 2119에 기술된 대로 해석됩니다.

2.4.0에서 추가, 호환성 변경 없음. (1) 변경 표면(Touched Surface) 절 — 작업이 바꾸는 것과 검증되어야 할 것 사이의 계약, 위험 등급별 게이트 선택(고립 / 이음새 / 공유-핵심 / 알 수 없음); (2) 전체 검증이 계획의 단일 필수 Final Review에서 실행되는 최종 상태 요건이 되며, 명시적인 증거 재사용 규칙이 따름; (3) 작업 안의 스킬 결정이 해당 작업으로 이동하고, 임원 보고서는 요청 시 선택적이 됨; (4) 모드 인식 create 플로우 — 신뢰 모드는 분석과 품질 검사를 유지한 채 직접 구체화; (5) Lite 우선 계획 구체화 — 안내형 create가 실행 불가능한 초안 대신 곧바로 실행 가능한 Lite 계획을 만들며, 언제든 Full 계획으로 승격할 수 있음(참고: Lite 계획); (6) 명시적인 호환성 매트릭스: 이전 버전의 계획과 리포지토리는 적합 상태를 유지합니다.

표준 4.0.0. 버전 도약은 표준의 번호를 제품 라인과 맞추기 위한 것입니다 — 2.x는 역사적 버전이며 3.x 표준은 존재하지 않습니다 — 그리고 2.4.0의 요구 사항은 하나도 바꾸지 않습니다. 이전 버전의 계획과 리포지토리는 여전히 적합합니다.

정의

Deep Work Plan은 복잡한 엔지니어링 작업을 순차적이고 검토 가능한 작업 단위로 분해해 기술하는, 구조화된 Markdown 전용 산출물이며, 자율적으로 일하는 AI 코딩 에이전트가 생성, 실행, 유지하도록 설계되었습니다.

DWP는 스펙 주도입니다. 계획이 곧 스펙이고, 에이전트는 즉흥적으로 하는 대신 그것의 명시적인 인수 기준과 검증 게이트에 맞춰 실행해야(MUST) 합니다. 채팅 로그가 아니라 스펙이 견고한 진실 공급원이므로, 작업은 세션과 에이전트를 넘어 검증 가능하고 재개 가능합니다. 이는 또한 이식 가능한 형태로 만든 하니스 엔지니어링이기도 합니다. 에이전트를 신뢰할 수 있게 만드는 컨텍스트, 제어 루프, 가드레일, 재개 가능한 상태가 일반 Markdown으로 리포지토리 자체에 설치되므로, 적합한 어떤 에이전트든 도구별 프레임워크 없이 리포지토리를 조종할 수 있습니다(MAY).

Create 플로우 — 단일 단계, 모드 인식

create 플로우는 목표, 컨텍스트, 제약, 작업 개요를 한 번에 수집하고, 그 요건 분석(범위, 작업 간 의존성 순서, 변경 표면으로부터의 검증 선택, 비례적 엄격도 계층)을 수행한 다음, 개발자가 선택한 모드에 따라 구체화합니다:

• 안내 모드(기본값). 플로우는 Lite 계획을 곧바로 구체화합니다 — 인라인 {#task-N} 작업 레코드를 담은, 이미 실행 가능하고 한 번에 검토할 수 있는 간결한 제안 — 그리고 개발자에게 이를 Lite로 유지할지, Full 계획으로 승격할지, 수정을 요청할지, 아니면 중단할지 묻습니다. 실행 불가능한 중간 초안은 생성되지 않습니다.
• 신뢰 모드(trust / auto). 플로우는 선택된 표현 형식(Lite, 또는 Lite 다음에 곧바로 Full로 승격된 것)을 검토 단계 없이 직접 구체화합니다 — 개발자가 이를 면제한 것입니다. 요건 분석, 의존성 순서, 그리고 계획 품질 검사는 여전히 실행됩니다: 신뢰는 검토를 면제하지 분석을 면제하지 않습니다. 신뢰 모드 계획은 무인 실행에 대해 사전 승인됨으로 기록됩니다.

두 모드 모두 계획의 형식(Lite 또는 Full)을 동일한 요건 분석의 일부로 결정하며, 결코 나중에 덧붙이지 않습니다. 전체 표현 형식, 생성과 선택, 승격 라이프사이클은 Lite 계획을 참고하십시오.

계획 구조

계획은 .dwp/plans/ 아래에 PLAN_<slug>/라는 이름의 디렉터리여야(MUST) 하며, 다음 두 표현 형식 중 하나입니다:

• Full. 디렉터리는 README.md(계획 개요, 목표, 작업 표, 상태), 작업당 하나씩 <n>.task_<slug>.md 형식으로 이름 붙인 파일, 그리고 PROGRESS.md(실행의 진행 로그)를 담아야(MUST) 합니다.
• Lite. 간결하고 완전히 실행 가능한 작업 레코드가 별도의 작업 파일 대신 안정적인 {#task-N} 앵커 뒤에 README.md 안에 인라인으로 존재합니다 — 각 레코드는 여전히 목표, 변경 표면, 인수 기준, 검증, 완료 로그를 담습니다. PROGRESS.md는 여전히 REQUIRED입니다. Lite 계획은 언제든 Full로 승격되어도(MAY) 됩니다. 전체 라이프사이클은 여기서 반복하지 않고 Lite 계획을 참고하십시오.

계획은 기계 가독 상태 레이어를 추가로 담아도(MAY) 됩니다: manifest.json(정적 식별 정보, 구체화 시 한 번 작성)과 state.json(라이브 작업별 실행 상태). 상태 레이어는 새 계획에 RECOMMENDED이며 무인 실행 및 git이 없는 에이전트 작업 공간에는 REQUIRED입니다. 참고: 계획 상태.

작업 구조

작업 파일

1. 01 Title
2. 02 Context
3. 03 Read Before Starting
4. 04 Goal
5. 05 Touched Surface
6. 06 Instructions
7. 07 Acceptance Criteria
8. 08 Outputs
9. 09 Validation
10. 10 Execution Checklist + Completion & Log

각 작업 파일은 이 열 절을 순서대로 담아야(MUST) 합니다.

1. 목표(Goal) — 작업이 무엇을 달성하는지에 대한 한 단락의 진술.
2. 컨텍스트(Context) — 배경, 링크, 그리고 이 작업이 존재하는 이유.
3. 변경 표면(Touched Surface) — 작업이 바꾸는 것과 검증되어야 할 것 사이의 계약.
4. 단계(Steps) — 수행할 순서대로 정리된 구체적 행동.
5. 인수 기준(Acceptance criteria) — 완료를 정의하는 조건의 체크리스트.
6. 검증(Validation) — 확인을 위해 실행할 명령이나 테스트, 변경 표면에서 선택됨.
7. 파일(Files) — 생성 또는 수정될 것으로 예상되는 경로.
8. 의존성(Dependencies) — 다른 작업이나 외부 선행 조건.
9. 리스크(Risks) — 무엇이 잘못될 수 있는지와 완화책.
10. 완료 & 로그(Completion & Log) — 상태 표시와 함께 시간순 기록.

작업은 추가로 Delta 절(브라운필드 동작 변경에 RECOMMENDED — 아래 참조)과 롤백 절(마이그레이션, 인프라 변경, 배포에 RECOMMENDED)을 담아도(MAY) 됩니다.

변경 표면(Touched Surface)

변경 표면은 작업이 바꾸는 것과 검증되어야 할 것 사이의 계약입니다. 검증이 습관이 아니라 효과로 선택되도록, 그리고 나중의 독자가 왜 그 게이트가 선택되었는지 볼 수 있도록 존재합니다. 동작을 변경하는 작업은 다음을 기록해야(MUST) 합니다:

• 계획된 표면 — 작업이 변경하려는 경로, 모듈, 패키지 또는 설정. 편집 전에 작성됩니다.
• 실제 표면 — 편집 후 실제 diff에서 가져온, 조정된 목록. 에이전트는 게이트를 선택하기 전에 계획된 표면과 실제 표면을 조정해야(MUST) 합니다.
• 영향받는 소비자 — 실제 표면에 의존하는 모듈, 패키지 또는 서비스. 리포지토리의 문서화된 매핑이 확립할 수 있는 한까지. 확립할 수 없는 경우, 그 항목은 그렇게 말해야(MUST) 합니다.
• 위험 등급 — 다음 중 하나: 고립(isolated)(하나의 모듈과 그 테스트에 한정); 이음새(seam)(협력자 사이의 계약, 영속성, 라우팅, 직렬화, 인증 또는 프레임워크 배선을 변경); 공유/핵심(shared/core)(널리 임포트되거나, 의존성·마이그레이션·빌드/테스트 설정·스키마·도구 사슬 변경); 알 수 없음(unknown)(매핑이 누락되었거나 오래되었거나 검증되지 않음).
• 사용된 테스트 매핑 — 어떤 문서화된 매핑이나 도구가 그 선택을 만들었는지.
• 선택된 게이트와 이유 — 정확한 명령들과 그것들이 실제 표면을 덮는 이유.

설정 파일, 스키마, 의존성 매니페스트, 템플릿, 픽스처, 마이그레이션, 에이전트 지시 파일은 동작을 변경할 수 있으며 파일 확장자가 아니라 효과로 분류되어야(MUST) 합니다. 산문, 주석 또는 연구 산출물만 변경하는 작업은 표면이 해당 없음을 선언해도(MAY) 되며, 그래도 리포지토리의 비런타임 검사를 실행합니다.

Delta 절 (브라운필드 변경)

실제 작업의 대부분은 새 동작을 만드는 것이 아니라 기존 동작을 수정합니다. 기존 시스템의 동작을 변경하는 작업은 세 가지 목록 제목을 사용해 변경을 명시적 이전/이후 계약으로 기술하는 Delta 절을 담아야(SHOULD) 합니다.

• ADDED — 작업 후에 존재하고 이전에는 없었던 동작.
• MODIFIED — 양쪽에 존재하며, was: … → now: …로 명시.
• REMOVED — 이전에 존재했고 이후에는 의도적으로 없어진 동작.

각 항목은 관찰 가능한 동작이어야(MUST) 합니다 — 엔드포인트의 응답, CLI 플래그, UI 상태, 기본값 — 구현 세부 사항이 아닙니다. Delta 절은 동작 수준의 리뷰어 차이입니다: 인수 기준이 ADDED/MODIFIED 항목을 검증하고, REMOVED 항목이 삭제를 위한 명시적 허가입니다. REMOVED로 나열되지 않은 것은 계속 작동해야(MUST) 합니다.

검증 게이트 — 위험 등급으로 선택

검증은 완료 주장을 완료의 증거로 바꾸는 게이트입니다: 작업은 그 검증 절의 모든 명령이 실행되어 통과하기 전까지 완료로 표시되어서는 안 됩니다(MUST NOT). 동작을 변경하는 작업의 게이트는 조정된 변경 표면에서 위험 등급으로 선택됩니다:

동작 변경은 비어 있지 않고 관련성 있는 테스트 선택을 산출해야(MUST) 합니다 — 유효하지 않은 선택자나 테스트를 하나도 선택하지 않은 러너는 커버리지가 아닙니다. 리포지토리의 테스트 매핑이 오래된 경우, 올바른 호출을 도출하고 매핑 갱신을 기록합니다; 작은 누락 명령이 전체 온보딩 실행을 요구하는 일은 결코 없습니다. 범위가 한정된 호출이 존재하지 않는 경우, 전체 해당 스위트가 적용됩니다 — 오류가 아니라 레거시 동작입니다.

작업이 새로운 핵심 기능을 추가하거나 기존 동작을 실질적으로 변경할 때, 그 인수 기준은 새로운 또는 변경된 동작에 대한 자동화된 테스트 커버리지를 포함해야(MUST) 하며, 그 검증은 빌드만이 아니라 리포지토리의 테스트를 lint, 타입 검사, 포맷 검사와 함께 실행합니다. 기존 테스트는 통과 상태를 유지해야(MUST) 합니다.

최종 상태 검증

작업별 게이트는 각 작업이 건드린 것을 검증합니다; 그것들은 계획 전체에 대한 검증을 대체하지 않습니다. 계획이 완료되기 전에, 리포지토리의 전체 해당 검증이 마지막 실질적 변경 이후의 최종 관련 상태에서 — Final Review 안에서 — 실행되어 통과해야(MUST) 합니다. 더 이른 시점의 더 넓은 실행은 통합 경계에서 또는 공유/핵심 변경 후에 일어나며, 작업 수 기준 일정으로는 일어나지 않습니다. 통과한 결과는 관련 입력이 동등하다는 증거가 있는 경우에만 재사용해도(MAY) 됩니다; 그렇지 않으면 재실행됩니다. 각 게이트 실행은 간결한 기록을 남깁니다: 명령, 범위, 리비전, 결과, 증거 경로.

보안 규율

보안은 테스트와 똑같이 일급이며, 동일한 두 계층 모델을 따릅니다: 작업이 진행되는 동안의 작업별 규율, 그리고 마지막에 전체 변경 집합에 대한 Final Review의 보안 점검. 작업이 인증 또는 인가, 입력 처리, 비밀 또는 설정, 네트워크·파일·셸 표면, 또는 의존성에 닿을 때마다:

• 그 인수 기준은 그 변경의 보안 기대치 — 입력이 검증되고 이스케이프됨, 코드나 픽스처에 비밀 자료 없음, 인증 검사가 보존되거나 강화됨 — 를 docs/SECURITY.md와 일관되게 명시해야(MUST) 합니다.
• 모든 커밋은 안착되기 전에, 테스트 픽스처와 문서 예시를 포함하여, 비밀이나 자격 증명이 없음을 확인해야(MUST) 합니다. 푸시된 커밋 안의 비밀은 단지 제거되는 것이 아니라 유출된 것으로 취급되어 교체되어야(MUST) 합니다.
• 보안에 민감한 작업이 상당한 경우, 전용 강화 작업을 구현 작업 직후, 종합 테스트 작업 직전에 두어야(SHOULD) 합니다. 그래야 테스트가 동작을 부호화하기 전에 발견 사항이 수정되고, 각 발견 사항이 재작업이 아니라 회귀 사례가 됩니다.

이 작업별 규율은 Final Review의 보안 점검을 대체하지 않습니다: 작업별 점검은 문제가 태어난 커밋에서 그것을 잡고, 최종 게이트는 — 테스트와 문서 작업 그 자체를 포함하여 — 계획 전체를 감사합니다.

계획 수명 주기 — Final Review

이 버전에서 작성된 모든 적합 계획은 정확히 하나의 필수 작업으로 끝납니다: Final Review(작업 N). 이전 버전이 별도의 마무리 작업에 두었던 두 가지 책임이 재배치됩니다: 스킬 결정은 그 패턴을 낳은 작업으로 이동하고, 임원 보고서(Executive Report)는 요청 시 제공되는 선택적 산출물이 됩니다. 보안 점검의 어떤 부분도 완화되지 않습니다.

Final Review는 순서대로 다음을 해야(MUST) 합니다:

(a) 보안 점검 — 하드코딩된 비밀, 인젝션 위험, 새로운 공격 표면, 약화된 인증, 로그나 문서 안의 민감 데이터에 대해 계획의 전체 누적 변경 집합을 검토; 도입된 의존성을 감사; docs/SECURITY.md가 여전히 현실을 반영하는지 확인; 깨끗한 경우에도 보안 검토 보고서를 작성. 치명적인 발견은 계획이 완료되기 전에 수정되거나 — 사용자가 명시적으로 수용합니다.

(b) 최종 상태 검증 — 리포지토리의 전체 해당 검증이 최종 관련 상태에서 실행되어 통과합니다.

(c) 스킬 조정 — 모든 작업이 스킬 처분을 담고 모든 기록된 후보가 처분을 갖습니다; 두 번째 발견 보고서는 없습니다.

(d) 완료 — 산출물, 검증 증거, 한계와 함께 완료를 보고; 임원 보고서를 한 번 제안. 계획은 그 제안에 응답이 있든 없든 완료됩니다.

Final Review는 다른 모든 작업 이후에 순차적으로 실행되며, 병렬 그룹에 배치되는 일은 결코 없습니다.

작업 안의 스킬 결정

“이 작업이 스킬이나 에이전트로 가치 있는 재사용 가능한 패턴을 만들었는가?“라는 질문은 그 증거가 컨텍스트에 있는 동안, 패턴을 낳은 작업 안에서 답해집니다. 모든 작업의 완료 & 로그는 스킬 처분을 담습니다: 없음, 기존 스킬 갱신, 명명된 산출물 생성, 또는 이유를 담은 연기. 정당한 저작은 그 작업 안에서, 검증 게이트와 커밋 이전에, 중복에 대해 기존 카탈로그를 확인한 후에 이루어집니다.

임원 보고서 — 요청 시 선택적

임원 보고서는 더 이상 필수 작업이 아닙니다. 완료 시 에이전트가 한 번 제안합니다; 명시적인 요청이 있을 때만 생성되며, 계획을 재생하지 않고 지속 가능한 증거로부터 충족됩니다. 응답이 없거나 무인 실행이면 보고서 없이 계획이 완료 상태로 남습니다.

작업 완료 프로토콜

검증을 통과한 후 다음 작업으로 진행하기 전에, 에이전트는 순서대로 다음을 해야(MUST) 합니다: (1) 계획 README에서 작업을 [x]로 표시; (2) 계획 상태 카운트 증가; (3) 자리 표시자 없이 작업의 완료 & 로그 채우기; (4) PROGRESS.md에 3~5개 항목 추가; (5) 커밋(계획이 커밋하는 경우) {type}({scope}): {description} — Task {N} of PLAN_{name} 형식으로; (6) 계획이 상태 레이어를 담는 경우, state.json을 원자적으로 재작성 — 작업 completed, 게이트 기록, 결과 기록, 커밋 해시.

여섯 단계는 하나의 논리적 트랜잭션을 구성합니다. 프로토콜 중간에 중단된 에이전트는 다음 작업을 시작해서는 안 됩니다(MUST NOT) — 먼저 부분 완료를 마무리하거나 되돌려야 합니다.

DWP 재개 프로토콜

재개는 계획의 파일과 git 로그만으로 가능해야(MUST) 합니다. git이 없는 작업 공간에서는 — 참고: 아키타입 §3 — 계획의 state.json이 REQUIRED이며 git 로그를 대신합니다.

재개하는 에이전트 — 새 세션, 다른 에이전트, 예약된 데몬 턴, 또는 깨어나는 클라우드 세션 — 는 순서대로 이 의식을 수행해야(MUST) 합니다.

1. 재고정. 계획 README를 읽습니다: 목표, 전역 지침, 작업 목록.
2. 체크포인트 찾기. README에서 첫 번째 체크 해제된 작업을 찾습니다; git 로그와 git status를 읽습니다(git이 없는 경우 state.json의 checkpoint).
3. 상태 조정. state.json이 있는 경우, README 체크박스와 비교합니다; 비동기 시 계속하기 전에 Markdown에서 재생성합니다.
4. 이음새 점검. 재개 지점 작업의 완료 & 로그와 마지막 PROGRESS.md 항목을 읽습니다 — 이전 세션의 마지막 검증된 근거.
5. 스모크 테스트. 리포지토리의 가장 저렴한 상시 검증을 실행해 그 위에 구축하기 전에 세계가 여전히 작동하는지 확인합니다. 실패하는 스모크 테스트는 그 위에 구축하는 것이 아니라 먼저 조사합니다.
6. 원자적으로 계속. 정확히 다음 작업만 실행합니다; 앞으로 묶어서 처리하지 않습니다.

에이전트는 완료된([x]) 표시를 신뢰해야(MUST) 하며 사용자가 명시적으로 요청하거나 스모크 테스트가 완료된 작업을 암시하는 방식으로 실패하지 않는 한 완료된 작업을 재검증해서는 안 됩니다(MUST NOT).

실행 루프

DWP는 다섯 가지 연산을 정의합니다.

• create — 목표로부터 새 계획을 생성합니다.
• execute — 계획을 작업 단위로 실행합니다.
• refine — 기존 계획을 수정합니다.
• resume — 중단된 계획을 재개합니다.
• status — 실행하지 않고 계획 상태를 보고합니다.

출력 작업 공간

출력 작업 공간

• .dwp/ git 무시 · 폐기 가능
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ 보고서
• SECURITY_REVIEW.md 보안 검토
• EXECUTIVE_REPORT.md 경영 요약 보고서

모든 DWP 산출물은 리포지토리 루트의 gitignore된 .dwp/ 디렉터리 아래에 있어야(MUST) 합니다.

기계 가독 계획 상태

계획은 기계 가독 상태 레이어를 담아도(MAY) 됩니다 — manifest.json(정적 식별 정보)과 state.json(라이브 작업별 상태, 검증 게이트 기록, 결과 기록, 체크포인트, 차단 상태). Markdown 계획은 진실 공급원으로 남습니다; JSON 레이어는 파생 프로젝션으로, 프로토콜 지점에서 재생성되고 재개 시 조정됩니다.

상태 레이어는 새 계획에 RECOMMENDED이며, 무인 실행에 REQUIRED이고, git이 없는 에이전트 작업 공간에 REQUIRED입니다. 전체 규범적 정의는 계획 상태를 참고합니다.

비례적 엄격도

엄격도는 작업에 비례해야(MUST) 합니다. 사소한 변경에 대한 형식적 절차는 방법론 실패이지 추가 안전이 아닙니다. 모든 작업은 정확히 하나의 계층에 속합니다.

micro 계층 작업에 대해 계획을 생성하도록 요청받은 에이전트는 계획이 불균형하다고 말하고 인라인 형식을 제안해야(MUST) 합니다. 사소한 단일 파일 변경을 위해 계획 폴더를 생성해서는 안 됩니다(MUST NOT).

Micro 계층 작업도 비협상 조건을 유지합니다: 명시적 목표, 실행되어 통과하는 검증 게이트, 동작 변경에 대한 테스트 규율. 계층은 포장을 변경하지, 게이트를 변경하지 않습니다.

비행 중에 범위가 커지면 — micro 작업이 실제 범위를 드러내거나, standard 계획이 하위 리포지토리를 낳으면 — 에이전트는 멈추고 현재 계층을 늘리는 대신 작업을 다음 계층으로 승격해야(MUST) 합니다.

호환성

이전 버전의 계획과 리포지토리는 적합 상태를 유지하며, 적합성 검사기는 알려진 레거시 산출물(수용)과 이 버전을 선언했지만 그 아래에서 객관적으로 무효인 산출물(거부)을 구별해야(MUST) 합니다:

버전 관리

이 스펙은 시맨틱 버저닝을 따릅니다.