Quick Reference

좋은 작업 프롬프트는 고정된 양식이 아니라, 결과를 바꾸는 정보만 명확히 줍니다. 작은 수정에는 한두 문장으로 충분하고, 위험하거나 넓은 작업에는 결과, 맥락, 경계, 검증을 보태면 됩니다.

결과: 로그인 timeout을 10초로 고치고 사용자 메시지를 유지해 주세요.
맥락: @src/auth/login.ts의 request 경로에서만 재현됩니다.
경계: API 응답 형식과 retry 횟수는 바꾸지 마세요.
검증: auth test를 실행하고, 실패하면 원인과 실행하지 못한 항목을 보고해 주세요.

결과와 맥락

먼저 해결할 결과를 말합니다. 세세한 구현 순서를 강제하면 안 되는 이유가 없다면, Codex가 repository를 읽고 더 적절한 경로를 찾을 여지를 남깁니다. 출력 형식, 대상 독자, 수정 범위가 결과를 바꾼다면 함께 적습니다.

나쁜 요청: 설정이 이상하니 고쳐 주세요.

더 나은 요청:
- 저장 뒤 새로고침하면 알림 설정이 되돌아갑니다.
- @app/settings/page.tsx와 @lib/api/settings.ts를 먼저 확인해 주세요.
- 공개 API 형식은 유지하고, 관련 test 결과를 함께 알려 주세요.

맥락은 많이 넣는 것이 아니라 판단을 바꾸는 것만 넣습니다. 재현 명령, 실제 오류, 관련 파일, 설계 결정, 최신 외부 정보가 필요한지 여부가 대표적입니다. 코드베이스 전체 규칙이나 반복되는 금지선은 매 prompt에 길게 붙이지 말고 AGENTS.md나 repository 설정으로 관리합니다.

경계와 검증

경계는 잘못 바꾸면 결과를 쓸 수 없게 되는 한두 가지를 우선합니다. "API는 유지", "migration은 만들지 말고 먼저 물어보기", "외부 service에 보내지 않기"처럼 실제 위험을 막는 문장입니다. 모든 구현 단계를 지시하면 agent가 탐색·검증할 판단 여지가 줄어듭니다.

수정 후에는 다음을 확인해 주세요.
- npm test -- auth
- 저장 후 새로고침 재현 절차
- 변경한 파일과 남은 위험 한 줄 요약

검증은 Done when의 역할을 하지만 반드시 그 제목을 쓸 필요는 없습니다. 실행할 명령, 성공 판정, 실행하지 못했을 때 보고할 내용 중 task에 맞는 것을 고릅니다. build가 너무 오래 걸리거나 환경이 없으면 "실행하지 않았다"는 사실과 이유를 남기는 것도 완료 판단의 일부입니다.

보낸 뒤의 운영

첫 prompt가 완벽할 필요는 없습니다. 결과를 읽고 빠진 source·경계·검증을 후속 메시지로 보탭니다. Codex가 실행 중일 때는 현재 방향을 바꾸는 정보는 steer, 다음 작업으로 미룰 정보는 queue로 보냅니다.

• "다른 파일도 수정해"보다 @로 파일을 지정하거나 영향 범위를 명시합니다.
• "안전하게 해"보다 보존해야 할 API, 승인 전 확인할 작업, 금지한 외부 변경을 적습니다.
• "테스트해"보다 실행할 test와 기대 결과를 적습니다.
• result와 diff는 사람이 다시 읽습니다. prompt가 명확해도 검토 책임이 agent에게 완전히 넘어가지는 않습니다.

완료 조건을 장기 작업으로 유지해야 하면 계획과 완료 정의, 프로젝트 전체 규칙은 AGENTS.md 작성에서 이어서 확인할 수 있습니다.