핵심 정리

Goal:
- 무엇을 바꿀지

Context:
- 관련 파일, 재현 절차, 현재 상태

Constraints:
- 건드리면 안 되는 API, 성능 조건, 스타일 규칙

Done when:
- 어떤 테스트와 어떤 결과가 나오면 끝인지

프롬프트 블록

네 구성 요소를 분리하는 이유는 Codex가 각각을 다르게 처리하기 때문이다

공식 Best practices는 강한 기본 프롬프트 구조로 Goal, Context, Constraints, Done when을 명시하라고 권합니다. Goal은 결과를, Context는 현재 상태를, Constraints는 금지선과 선택 기준을, Done when은 종료 조건을 분리해 줍니다. 이 네 가지를 한 문단에 섞으면 Codex는 어디까지가 목표이고 어디부터가 제약인지 모호하게 해석하기 쉽습니다. "버그를 고쳐 줘"보다 "이 재현 절차를 따라 실패를 확인하고, 최소 수정 후 관련 테스트를 다시 돌려라"가 훨씬 안정적으로 작동하는 이유가 여기에 있습니다.

Goal:
- settings 저장 버그를 고쳐라

Context:
- 관련 파일: @app/settings/page.tsx @lib/api/settings.ts
- 재현: 저장 후 새로고침하면 토글 값이 원래대로 돌아감

Constraints:
- API 응답 형식은 바꾸지 말 것
- 수정은 최소화할 것

Done when:
- 재현이 더 이상 되지 않고
- 관련 테스트 또는 최소 검증 명령 결과를 함께 보고할 것

Context를 파일 경로로 구체화해야 추측 기반 수정이 줄어든다

IDE에서는 열린 파일과 선택 코드가 자동으로 붙지만, CLI에서는 관련 파일 경로와 재현 절차를 더 명시적으로 주는 편이 좋습니다. 파일 경로를 첨부하지 않으면 Codex는 관련 파일을 추측해야 하고, 그 과정에서 엉뚱한 파일을 수정하거나 수정 범위가 예상보다 넓어지는 문제가 생깁니다. "이 파일이 관련됐다"가 아니라 "이 파일의 이 함수에서 재현된다"처럼 구체적인 Context가 훨씬 정확한 결과를 만듭니다.

Constraints는 꼭 필요한 금지선만 남겨야 프롬프트가 읽기 쉬워진다

제약이 많을수록 좋은 것이 아닙니다. 꼭 필요한 파일, 재현 절차, 금지선, 완료 기준만 남기고 나머지는 AGENTS.md나 설정으로 옮겨야 프롬프트가 읽기 쉬워집니다. 팀 전체에 적용되는 코드 스타일이나 API 규칙은 AGENTS.md에 한 번 넣어두면 매 프롬프트마다 반복할 필요가 없습니다. 프롬프트가 길어질수록 Codex가 어느 제약에 집중해야 하는지 판단하기 어려워집니다.

Done when이 Codex의 종료 판단 기준을 고정한다

Done when이 없으면 Codex는 테스트를 돌리지 않고 코드 수정만 하고 작업을 끝낼 수 있습니다. "재현이 더 이상 되지 않는다", "관련 테스트를 통과한다", "diff를 함께 보고한다"처럼 검증 가능한 기준을 명시하면, Codex가 스스로 종료 판단을 내릴 때 이 기준을 참조합니다. Done when이 명확할수록 중간 산출물이 최종 결과로 제출되는 실수가 줄어듭니다.

프롬프트 블록을 고르는 기준
- Goal: 무엇을 바꿀지
- Context: 어디서 왜 문제인지
- Constraints: 건드리면 안 되는 선과 선택 기준
- Done when: 어떤 검증 결과가 나오면 끝인지

어떤 블록이 빠졌나

주의할 점

실패 예시
- "버그 고쳐 줘. 테스트도 알아서 하고 최대한 안전하게 잘 해 줘."처럼 Goal과 Done when을 섞어 보냄
- 결과: 관련 파일 추측, 검증 범위 누락, 종료 조건 오해가 한꺼번에 발생
- 대응: Goal / Context / Constraints / Done when을 줄 단위로 분리해 종료 기준까지 명시한다