핵심 정리
/plan
목표:
- 인증 모듈 리팩터링
계획에 꼭 포함할 것:
- 단계별 파일 이동 범위
- 각 단계의 검증 방법
- 롤백 전략
- 사용자 영향이 없는지 확인하는 기준계획 흐름
큰 작업에서 계획을 먼저 분리해야 검토 가능성이 생긴다
큰 리팩터링, 마이그레이션, 아키텍처 변경은 바로 구현을 시키기보다 먼저 계획을 분리하는 것이 공식 가이드의 기본 권장 흐름입니다. /plan을 쓰거나, 먼저 질문으로 요구사항을 인터뷰하게 만들면 불명확한 부분을 구현 전에 드러낼 수 있습니다. Codex가 충분히 유능해도 목표와 범위가 모호한 상태에서 시작하면 검토하기 어려운 넓은 diff가 나옵니다. 구현 능력보다 검토 가능성을 먼저 설계하는 것이 실제 성공률을 높이는 방법입니다.
계획 요청 예시
- 먼저 3단계 계획만 제시해라.
- 각 단계마다 수정 파일과 검증 명령을 적어라.
- 공개 API를 건드리는 단계가 있으면 따로 표시해라.
- 마지막에 "이 단계가 실패하면 어디까지 되돌리면 되는가"를 적어라.마일스톤 크기가 실패 비용을 결정한다
마일스톤이 너무 크면 한 번의 diff가 읽기 어려워지고, 너무 작으면 흐름이 끊깁니다. 보통 검증 가능한 단위로 나누는 것이 좋습니다. "Implement milestone 1" 같이 마일스톤 단위로 쪼개서 위임하고 각 결과를 검토하는 흐름이 실패 비용을 낮춥니다. 한 마일스톤이 실패해도 앞선 마일스톤의 결과가 안전하게 보존되기 때문에, 전체를 다시 시작할 필요가 없습니다.
롤백 전략이 없으면 실패 이후 복구 경로가 없다
좋은 계획은 "무슨 파일을 어느 단계에서 바꾸는가", "각 단계가 끝났는지 무엇으로 판단하는가", "실패하면 어디까지 되돌릴 수 있는가"를 포함합니다. 롤백 전략 없이 시작하면 중간 단계에서 문제가 생겼을 때 어디까지 되돌려야 하는지 판단할 기준이 없습니다. 각 단계 전에 Git 체크포인트를 만들어 두면 롤백 전략과 자연스럽게 연결됩니다.
Definition of Done은 각 단계마다 통과 기준을 미리 적는 방식이 더 안정적이다
Definition of Done은 마지막 한 줄 체크리스트가 아니라, 각 단계마다 통과 기준을 미리 적어 두는 방식이 더 안정적입니다. "관련 테스트 통과", "공개 API 변경 없음", "빌드 성공"처럼 단계별 기준을 명시해 두면, Codex가 스스로 종료 판단을 내릴 때 이 기준을 참조할 수 있습니다. 완료 기준이 없으면 중간 산출물을 최종 완료로 착각하는 실수가 생깁니다.
계획과 바로 구현을 나누는 기준
- 범위가 작고 검증이 즉시 가능할 때: 바로 구현
- 파일이 여러 개고 공개 API나 데이터 이동이 걸릴 때: /plan 먼저
- 되돌릴 지점이 중요할 때: 마일스톤과 체크포인트부터 정의
- 완료 판단이 애매할 때: Done when을 먼저 적고 시작언제 계획부터 세울까
| 상황 | 적합한 선택 |
|---|---|
| 큰 작업을 시작하기 전에 범위를 잡을 때 | /plan으로 계획 먼저 요청 |
| 단계 크기를 결정하기 어려울 때 | 검증 가능한 단위로 마일스톤 분리 |
| 실패 시 복구 경로를 미리 준비할 때 | 롤백 전략과 Git 체크포인트 병행 |
| 중간 결과가 완료로 넘어가는 것을 막을 때 | 단계별 Definition of Done 명시 |
| 공개 API 변경 여부를 추적할 때 | 계획에 API 변경 단계 별도 표시 |
주의할 점
계획 없이 큰 작업을 한 번에 맡기면, Codex가 충분히 유능해도 검토 난이도가 급격히 올라갑니다. 구현 능력보다 검토 가능성을 먼저 설계하는 편이 실제 성공률이 높습니다.
실패 예시
- "인증 모듈 전체 리팩터링"만 적고 바로 구현을 시작함
- 결과: 파일 이동, API 변경, 테스트 수정이 한 diff에 섞여 어디까지가 안전한지 검토가 어려워짐
- 대응: 단계별 파일 범위, 검증 명령, 롤백 기준을 먼저 적고 마일스톤 단위로 실행한다참고 링크
3 sources