계획 문서: 어떤 순서로, 지금 어디까지
active/에서 만들어 실행하며 갱신하고, 끝나면 남길 지식을 제자리로 옮긴 뒤 completed/로 옮긴다이 페이지는 계획을 언제 만들고, 무엇을 적고, 어떻게 갱신하고 끝내는가에 답한다. 요구는 스펙이, 규약은 설계가 맡으므로 계획에는 그 둘을 뺀 나머지만 남는다.
이 장에서 처음 나오는 말2개
마일스톤Milestone- 독립적으로 결과를 확인하고 검증을 마칠 수 있는 작업 단위. M1·M2처럼 부른다. 매번 승인을 받는 지점이라는 뜻은 아니다.
실행 범위- 이번 요청에서 에이전트가 어디까지 하는가. 조사만, 특정 마일스톤까지, 전체 완료 중 하나.
언제 만드는가
섹션 제목: “언제 만드는가”작업이 한 세션에 끝나지 않거나 다른 도구가 이어받을 때 만든다. 파일 수가 기준이 아니다.
| 상황 | 할 일 |
|---|---|
| 범위와 결과가 분명한 작은 변경 | 만들지 않는다. 대화에서 범위를 확인하고 구현·검증한다 |
| 접근법이 불확실하다 | 코드 조사와 작은 실험으로 가정을 확인한다. 결정할 질문이 남으면 그때 계획에 적는다 |
| 여러 세션·도구가 이어받을 작업 | 만든다 |
| 이슈나 PR이 이미 순서와 상태를 관리한다 | 만들지 않는다. 부족한 인계 정보만 이슈에 보완한다 |
누가 파일 생성을 결정하는지는 레포 정책으로 정한다. 이 사이트는 사용자가 명시적으로 요청할 때만 만든다. “복잡한 기능이면 계획을 쓴다”처럼 AGENTS.md에 조건을 적어 에이전트가 판단하게 할 수도 있다.
계획에 적는 것
섹션 제목: “계획에 적는 것”가상 CSV 내보내기의 계획이다. 스펙의 요구를 다시 쓰지 않고 ID로 가리킨다.
# 7. 업무 목록 CSV 내보내기
지금 위치: 조사 완료 · 구현 미착수 · 다음 M1실행 범위: 로컬 구현·검증·실패 수정까지 전체 완료. 커밋·푸시·배포 제외.
스펙: docs/product-specs/task-export.md (FR-EXP-01~05, NFR-EXP-01~02)관련 설계: docs/design-docs/architecture.md의 api 절
## 완료 조건
- [ ] FR-EXP-01~05와 NFR-EXP-01~02의 수용 기준을 모두 통과한다.- [ ] 기존 목록 조회 테스트가 유지된다.
## 작업
| ID | 의존성·입력 | 결과 | 완료 조건·검증 ||---|---|---|---|| M1 | 기존 조회·권한 코드 | 내보내기 API | FR-EXP-01~05·NFR-EXP-02 테스트, pnpm --filter api test || M2 | M1의 응답·오류 계약 | 버튼·실패 안내 | 다운로드·0건·초과 안내의 화면 동작 || M3 | M1·M2 | 통합 확인·사용 안내 | 수용 기준 전체와 기존 조회 회귀 |
## 실행 기록
| 작업 | 상태 | 결정·변경 파일 | 검증 결과·미해결 | 다음 행동 ||---|---|---|---|---|| 조사 | 완료 | 목록 함수 listTasks()는 페이지 제한이 안에 있어 그대로 못 씀 | 없음 | M1에서 권한·필터 부분을 분리 |
## 완료 기록
(완료 때 채운다: 최종 결과, 검증 근거, 남은 제한, 설계 문서로 옮긴 것)머리의 두 줄이 인계의 핵심이다. 지금 위치는 새 세션이 어디서 시작할지, 실행 범위는 어디까지 하고 멈출지를 말한다. 실행 기록은 조사에서 알게 된 사실과 그로 인한 결정을 남긴다.
작업은 결과를 검증할 수 있게 나눈다
섹션 제목: “작업은 결과를 검증할 수 있게 나눈다”“백엔드 전부, 프런트 전부”가 아니라 “권한을 유지한 API, 그 계약을 쓰는 UI”처럼 나눈다. 각 작업에 입력과 완료 조건이 있어야 실패 위치를 알 수 있다. M2는 M1의 응답 계약에 의존하므로 계약이 바뀌면 M2도 손본다.
멀리 있는 작업의 함수명이나 명령 순서까지 미리 정하지 않는다. 확인이 필요한 가정에는 확인 방법만 붙이고, 가까운 작업부터 구체화한다.
수명주기
섹션 제목: “수명주기”
번호와 파일명
섹션 제목: “번호와 파일명”active/와 completed/를 합쳐 가장 큰 번호 다음을 쓰고 재사용하지 않는다. 번호는 작업
식별자다. 미완료 계획은 ls docs/exec-plans/active/ 한 번으로 찾는다. 파일 머리에 “완료”
상태 줄을 두지 않는다. 폴더가 그 상태를 말한다. 차단된 계획만 상태: 차단과 재개 조건을 적는다.
실행 범위에 따라 멈추는 곳이 다르다
섹션 제목: “실행 범위에 따라 멈추는 곳이 다르다”| 요청 | 어디까지 |
|---|---|
| 조사·계획만 | 계획을 쓰고 구현 전에 멈춘다 |
| M1까지 | M1의 구현·검증·계획 갱신까지 |
| 전체 완료 | 허용된 다음 마일스톤을 이어서 끝낸다. 마일스톤마다 재승인을 요구하지 않는다 |
전체 완료를 맡겼어도 요구 변경과 외부 쓰기는 별개다. 계획을 검토했다는 사실이 푸시·배포 허용은 아니다.
발견한 사실에 맞춰 고친다
섹션 제목: “발견한 사실에 맞춰 고친다”목록 함수가 한 페이지만 반환한다면 재사용 가정이 틀린 것이다. 구현안을 바꾸고 이유·영향· 필요한 검증을 실행 기록에 적는다. 완료 조건을 낮춰 맞추지 않는다. 요구 자체를 바꿔야 한다면 선택지를 제시해 스펙부터 고친다.
완료하면 지식을 제자리로 옮긴다
섹션 제목: “완료하면 지식을 제자리로 옮긴다”완료 조건 전체와 실제 결과를 대조하고 필요한 검증이 끝났을 때만 완료다. 미검증 조건을 남긴 채 폴더만 옮기지 않는다.
| 계획에 남은 정보 | 옮길 곳 |
|---|---|
| 다음 기능에도 적용될 규약·결정 | design-docs/ |
| 구현 중 합의로 달라진 요구 | product-specs/ |
| 새로 생긴 검사 명령·범위 | verification.md |
| 사용법 | README.md |
| 이번 작업의 진행·검증 이력 | 계획에 그대로. completed/로 이동 |
옮긴 뒤 git mv로 completed/에 넣고, 이 계획을 가리키던 링크를 고친다. 완료 계획에
새 작업의 진행 로그를 덧붙이지 않는다.
Plan Mode·ExecPlan과의 관계
섹션 제목: “Plan Mode·ExecPlan과의 관계”두 도구의 Plan Mode는 구현 전에 탐색하고 접근법을 검토하는 세션 안의 기능이다. 합의한 결과를 계획 파일에 적어야 다른 도구가 읽는다. OpenAI Cookbook의 ExecPlan은 이전 대화 없이 구현할 수 있는 자기완결 계획의 사례이며 archived로 분류된 글이다. 형식을 그대로 따를 필요는 없고, 이 페이지의 템플릿이 같은 목적을 맡는다.
이해 확인
섹션 제목: “이해 확인”API 테스트가 통과했지만 버튼은 아직 없다. 완료일까? M1만 완료다. 실행 범위가 전체 완료라면 M2를 이어 가고, M1까지였다면 지금 위치를 “M1 완료 · 다음 M2”로 갱신하고 멈춘다.
완료한 계획의 “수식 주입 방지” 결정을 나중에 찾으려면 어디를 볼까? design-docs/csv-output.md다.
완료 때 옮겼기 때문이다. 옮기지 않았다면 completed/를 뒤져야 하고, 그것이 옮기는 이유다.