작업 흐름: 요청·구현·검증·인계
이 페이지는 앞 페이지의 파일들을 실제 작업에서 어떤 순서로 쓰는가에 답한다. 가상 CSV 내보내기를 스펙과 계획에 이어 구현·검증하고 Codex에서 Claude Code로 넘긴다.
이 장에서 처음 나오는 말2개
인계Handoff- 다음 세션이 이전 대화 없이 일할 수 있도록 현재 상태·결정 이유·다음 행동을 파일에 남기는 것.
대조 리뷰Adversarial Review- 구현한 세션과 다른 컨텍스트가 계획·스펙과 diff를 대조해 빠진 조건과 범위 밖 변경을 찾는 단계.
한 작업의 순서
섹션 제목: “한 작업의 순서”- 요청에 결과·범위·실행 범위를 적는다. 절차는 AGENTS.md가 알고 있으므로 다시 쓰지 않는다.
- 조사하고 계획을 만든다. 관련 코드·스펙·설계를 읽고 가정을 확인해 계획의 작업 표를 채운다.
- 구현하고 검증한다. 마일스톤마다 세 종류의 증거를 확인하고 실행 기록에 남긴다.
- 대조 리뷰를 받는다. 다른 컨텍스트가 계획·스펙과 diff를 대조한다.
- 인계 기록을 남긴다. 도구를 바꾸거나 세션을 끝내기 전에 지금 위치·미커밋 변경·다음 행동을 갱신한다.
- 새 세션이 재개한다. 계획과 실제 코드 상태를 대조한 뒤 이어 간다.
요청은 결과와 범위를 드러낸다
섹션 제목: “요청은 결과와 범위를 드러낸다”AGENTS.md가 있는 레포에서는 절차를 프롬프트에 복사하지 않는다. 무엇을 얻을지, 어디까지 맡길지, 무엇을 제외할지를 쓴다. 다음은 스펙이 이미 있고 계획 작성도 요청하는 예다.
docs/product-specs/task-export.md의 CSV 내보내기를 구현해 줘.먼저 기존 조회·권한·CSV 코드와 검사 명령을 확인하고docs/exec-plans/README.md 규칙대로 active/에 계획을 만들어 줘.요구 변경이 필요하지 않으면 구현·검증·실패 수정까지 끝내고 계획의 지금 위치와 검증 결과를 갱신해 줘.커밋·푸시·배포는 제외해 줘.계획까지만 원하면 마지막 두 줄을 “계획 작성까지만 하고 구현은 시작하지 마”로 바꾼다. 완료 범위를 “구현·검증·실패 수정까지”로 적는 이유는 첫 구현에서 멈추지 않게 하기 위해서다.
결과는 세 종류의 증거로 읽는다
섹션 제목: “결과는 세 종류의 증거로 읽는다”| 증거 | CSV 사례에서 확인할 것 | 이것만으로 모르는 것 |
|---|---|---|
| diff와 요구 대조 | FR별 구현 위치, 변경 범위, 빠진 조건 | 실제로 동작하는가 |
| 자동 테스트·타입·빌드 | 권한 제외, 필터·전체 건수, CSV 형식, 기존 조회 유지 | 화면과 API가 실제로 이어졌는가 |
| 사용자 흐름 | 버튼에서 다운로드, 파일 내용, 초과·실패 안내 | 확인하지 않은 환경·입력 |
입력과 예상 관찰은 스펙의 수용 기준이 이미 정했다. 필터 일치 25건과 다른 사용자의 업무를 두고 목록은 10건씩 표시할 때 파일에 25건이 있으면 통과, 10건이면 현재 페이지만 내보낸 것이다.
실패하면 원인을 좁혀 구현과 테스트를 고치고, 영향을 받은 검증만 다시 한다. 기대값을 10건으로 낮춰 통과시키지 않는다. 필수 검사가 통과한 뒤에는 새 변경이 없는 한 반복하지 않는다.
검증 결과는 계획의 실행 기록에 다음 형식으로 남긴다. 적어 둔 명령과 실제로 실행한 것을 구분한다.
- 코드 상태: <브랜치·기준 커밋>, <미커밋 변경 범위>- 자동 검사: <실행 위치와 명령> → <종료 코드·관찰 요약>- 사용자 흐름: <준비한 데이터·조작> → <관찰한 결과>- 미확인: <실행하지 못한 항목·이유·다음 확인 방법>완료 전에 대조 리뷰를 받는다
섹션 제목: “완료 전에 대조 리뷰를 받는다”구현한 세션은 자기 diff를 관대하게 읽는다. 완료 조건 하나가 빠졌거나 요청 밖 파일이 바뀐 것은 새 컨텍스트가 더 잘 찾는다. Claude Code 공식 안내도 완료로 치기 전에 별도 컨텍스트의 리뷰를 권한다(Add an adversarial review step). 두 도구를 쓰는 레포라면 한쪽이 구현하고 다른 쪽이 리뷰하는 배치가 자연스럽다.
docs/exec-plans/active/0007-csv-export.md의 완료 조건과docs/product-specs/task-export.md의 수용 기준을 현재 git diff와 대조해 줘.조건마다 구현·테스트가 있는지, 요청 범위 밖 변경이 섞였는지,계획에 적힌 검증 결과가 실제 코드 상태와 맞는지 확인해 줘.정확성과 요구 누락만 보고하고 스타일 선호는 제외해 줘. 수정은 하지 마.리뷰어는 결함을 찾으라는 요청을 받았으므로 무언가는 보고한다. 완료 조건이나 정확성에 닿는 지적만 반영하고 나머지는 선택 사항으로 둔다.
도구를 바꾸기 전에 현재 상태를 남긴다
섹션 제목: “도구를 바꾸기 전에 현재 상태를 남긴다”Codex에서 M1을 마치고 Claude Code로 넘긴다. 별도 인계 파일은 만들지 않고 계획 머리와 실행 기록을 갱신한다. 대괄호는 실제 값으로 채운다.
지금 위치: M1 완료 · M2 UI 미착수코드 상태: [브랜치·기준 커밋]. 미커밋 변경: [API와 테스트 경로]. 커밋은 요청받지 않아 하지 않음.결정: listTasks()의 권한·필터 부분을 분리해 재사용, 페이지 제한만 뺀 함수 추가.검증: [실행 위치와 명령] → 통과. FR-EXP-01~05·NFR-EXP-02 확인. UI 연결은 미확인.다음 행동: M2에서 [API 경로]를 버튼에 연결하고 0건·초과 안내를 확인.차단 사항: 없음다른 worktree나 기기로 옮길 때는 미커밋 변경도 함께 옮겨야 한다. 계획 경로만 넘겨서는 코드가 가지 않는다.
새 세션은 파일에서 재개한다
섹션 제목: “새 세션은 파일에서 재개한다”새 도구에 줄 요청이다. 같은 도구의 대화 재개 기능과 달리 파일만으로 이어받는다.
docs/exec-plans/active/0007-csv-export.md의 미완료 작업을 끝까지 이어 가 줘.계획의 지금 위치·결정·미해결과 스펙·관련 설계를 읽어 줘.git status·diff·최근 이력을 대조해 계획과 실제 코드 상태가 맞는지 확인하고,다르면 실제 상태를 근거로 기록을 바로잡아 줘. 완료한 작업은 반복하지 마.남은 구현·검증·실패 수정과 계획 갱신까지 하고 커밋·푸시·배포는 제외해 줘.계획에 “테스트 통과”라고 있어도 그 뒤 코드가 바뀌었으면 그 결과는 현재 상태를 증명하지 않는다. 반대로 같은 상태에서 유효한 검사를 새 세션이라는 이유만으로 전부 반복하지도 않는다.
질문과 병렬 작업
섹션 제목: “질문과 병렬 작업”실행 중 결정이 필요하면 확인한 근거, 선택지, 그 결정에 의존하는 작업을 함께 제시해 사용자가 한 번에 판단하게 한다. 답을 기다리는 동안 의존하지 않는 작업은 이어 간다.
두 도구를 동시에 편집자로 쓸 때는 독립된 범위와 작업 사본을 배정한다. 같은 파일을 연속으로 바꿔야 하면 순서대로 한다. 여러 에이전트를 기본으로 두지 말고 실제 어려움에 맞춰 고른다.
이해 확인
섹션 제목: “이해 확인”새 세션이 연 계획에 M1 완료라고 적혔는데 해당 코드가 없다. M2로 갈까? 안 간다. 다른 브랜치·worktree에 있는지, 미커밋 변경이 전달되지 않았는지 확인해 상태부터 맞춘다.
API 검사만 통과했는데 전체 완료라고 보고할 수 있을까? 버튼·다운로드·실패 안내가 남았다. 허용된 범위에서 마저 확인하고, 검증하지 못한 조건은 구분해 보고한다.