DWP 스펙

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

v1.2에서 추가. 네 가지 추가 기능, 호환성 변경 없음: (1) 기계 가독 계획 상태 레이어(manifest.json + state.json, 참고: 계획 상태); (2) 비례적 엄격도 계층(micro / standard / deep, 참고: 비례적 엄격도); (3) 브라운필드 동작 변경을 위한 작업 구조의 선택적 Delta 절; (4) DWP 재개 프로토콜이 명명되고 인용 가능한 여섯 단계 의식으로 격상. 기존 v1.1 계획은 그대로 적합한 상태를 유지합니다.

정의

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

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

계획 구조

계획은 PLAN_<slug>/라는 이름으로 .dwp/plans/ 아래의 디렉터리여야(MUST) 합니다. 디렉터리는 다음을 담아야(MUST) 합니다.

README.md — 계획 개요, 목표, 작업 표, 상태.
작업당 하나의 파일, <n>.task_<slug>.md 형식의 이름.
PROGRESS.md — 실행의 진행 로그.

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

작업 구조

작업 파일

01 목표
02 맥락
03 단계
04 수용 기준
05 검증
06 파일
07 의존성
08 위험
09 완료 및 로그

모든 작업 파일은 동일한 아홉 개의 순서가 정해진 섹션을 따르므로, 각 작업 단위는 자체적으로 완결되고 검토 가능합니다.

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

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

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

Delta 절 (브라운필드 변경)

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

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

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

검증 게이트와 테스트

검증은 완료 주장을 완료의 증거로 바꾸는 게이트입니다. 작업은 그 검증 절의 모든 명령이 실행되어 통과하기 전까지 완료로 표시되어서는 안 됩니다(MUST NOT). 테스트는 이 게이트의 일급 구성 요소이지 선택적 부가물이 아닙니다 — 테스트가 계획이 산출하는 코드를 신뢰할 수 있고 검증 가능하게 만드는 것입니다.

작업이 새로운 핵심 기능을 추가하거나 기존 동작을 실질적으로 변경할 때:

그 인수 기준은 리포지토리의 테스트 관례와 커버리지 기대치를 따르며, 새로운 또는 변경된 동작(정상 경로와 함께 의미 있는 경계 및 오류 사례)에 대한 자동화된 테스트 커버리지를 포함해야(MUST) 합니다.
그 검증은 빌드만이 아니라 리포지토리의 테스트를 그 lint, 타입 검사, 포맷 검사와 함께 — 리포지토리가 정의하는 전체 코드 품질 검사를 — 실행해야(MUST) 합니다. “빌드된다”는 것은 동작 변경에 충분한 게이트가 아닙니다.
기존 테스트는 통과 상태를 유지해야(MUST) 합니다. 영향받는 코드를 다루는 테스트를 깨뜨리는 변경은 그 테스트를 의도된 새 동작으로 갱신해야(MUST) 합니다. 단지 게이트를 통과시키려고 테스트를 삭제, 건너뛰기, 또는 약화시켜서는 안 됩니다(MUST NOT).

순수 문서, 설정, 또는 연구 작업은 테스트 생성에서 면제되지만, 그래도 리포지토리가 정의하는 어떤 검증 게이트든 실행해야(MUST) 합니다. 테스트의 깊이는 변경의 크기와 리포지토리의 성숙도에 비례합니다. 리포지토리에 테스트나 lint 도구 사슬이 전혀 없는 경우, 에이전트는 이 규율을 조용히 건너뛰어서는 안 됩니다(MUST NOT) — 그것은 온보딩 중에 제안된 도구 사슬에 의존합니다(적합성 참고).

보안 규율

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

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

이 작업별 규율은 Security Review 최종 작업을 대체하지 않습니다: 작업별 점검은 문제가 태어난 커밋에서 그것을 잡고, 최종 게이트는 — 테스트와 문서 작업 그 자체를 포함하여 — 계획 전체를 감사합니다. 따라서 모든 계획은 세 가지 필수 최종 작업 — Security Review, 그다음 Skills & Agents Discovery, 그다음 Executive Report — 으로 끝나며, 심각한 보안 발견 사항은 그것이 수정되거나 명시적으로 수용될 때까지 완료를 차단합니다.

작업 완료 프로토콜

검증을 통과한 후 다음 작업으로 진행하기 전에, 에이전트는 순서대로 다음을 해야(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) 합니다.

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

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

실행 루프

DWP 코어 루프예요. 다섯 가지 작업이 계획을 목표에서 완료된 작업까지 이끌고, 검증이 적합성 관문 역할을 해요.

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

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

출력 작업 공간

.dwp/ git 무시 · 폐기 가능
drafts/ 다듬어진 초안 스테이징
plans/
PLAN_<name>/
README.md
PROGRESS.md
<n>.task_<slug>.md
analysis_results/ 보고서
SECURITY_REVIEW.md 보안 검토
EXECUTIVE_REPORT.md 경영 요약 보고서

모든 플랜 출력은 git이 무시하는 `.dwp/` 작업 공간 안에 있어요 — 초안과 플랜은 버전 관리되는 소스와 분리해서 보관해요.

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

기계 가독 계획 상태

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

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

비례적 엄격도

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

계층	언제	형식
micro	단일 원자적 변경: 하나의 관심사, 대략 한 번의 작업, 조율 불필요. 버그 수정, 문구 변경, 설정 조정.	계획 폴더 없음. 에이전트가 목표, 인수 기준, 검증 게이트를 대화 내에 명시하고, 실행하고, 검증하고, 커밋합니다.
standard	실질적 범위의 다단계 작업: 기능, 리팩터링, 하나의 리포지토리 내 마이그레이션. 기본 계층.	전체 계획: 계획 폴더, 아홉 절 작업, 필수 최종 작업.
deep	병렬 그룹, 자식 리포지토리, 또는 여러 무인 세션에 걸친 장기 작업.	오케스트레이터 및/또는 팀 에이전트 기능과 상태 레이어를 갖춘 standard 계획.

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

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

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

버전 관리

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