Codex /goal 완전정복 — '오래 시키는 명령'이 아니라 '완료 계약'을 쓰는 법

한 줄 요약 — Codex의 /goal은 "오래 돌리는 명령"이 아니라 작업을 결과·검증·제약·정지 조건이 박힌 '완료 계약'으로 바꾸는 방식이다. 끝점은 분명하되 경로가 불확실한 작업에 강하고, 완료는 느낌이 아니라 테스트·벤치마크·diff 같은 증거로 판단한다. 다만 현실에선 토큰 소진·승인 프롬프트 반복 같은 함정도 보고된다 — 그래서 '잘 쓰는 법'이 곧 '안전하게 멈추게 쓰는 법'이다.

/goal이란 무엇인가

/goal은 Codex의 목표 모드 진입점이다(앱·IDE 확장·CLI에서 시작). 일반 프롬프트가 한 번의 요청-답변으로 끝난다면, /goal은 스레드를 하나의 지속적 목표에 묶고 Codex가 계획 → 실행 → 검증 → 수정을 반복하게 한다. 그리고 목표가 증거로 완료되거나, 막히거나, 예산·사용 한도에 도달하면 멈춘다.

OpenAI 쪽 인사들은 Codex를 "가상의 동료(virtual coworker)"(Josh Tobin), 내부에선 "아침 할 일 목록"처럼 병렬로 돌린다(Alexander Embiricos)고 The Verge에 설명했다. 다만 OpenAI는 생성 코드를 통합·실행 전 사람의 검토가 여전히 필수라고 못 박는다 — 이 균형이 /goal 사용의 핵심이다.

한 문장 판단법 — 이 작업은 Codex가 여러 턴에 걸쳐 다음 행동을 스스로 골라야 하고, 테스트·감사 가능하며 멈출 수 있는 완료 조건이 있는가? 그렇다면 /goal을, "설명만/한 줄만"이면 일반 프롬프트가 낫다.

어떻게 작동하나 (실제 메커니즘)

문서로 확인되는 동작은 이렇다.

• 명령: /goal <목표> 로 시작하고 /goal pause·/goal resume·/goal clear로 제어한다. 목표 문구는 시작 프롬프트이자 완료 기준으로 쓰인다.
• 켜기: slash 목록에 없으면 config.toml의 [features] goals = true 또는 codex features enable goals로 활성화.
• 길이 제한: 목표는 비어 있으면 안 되고 최대 4,000자. 긴 지시는 파일에 넣고 목표에서 참조하라고 CLI 문서가 안내한다.
• 정지 상태: openai/codex의 실제 PR에는 complete(완료)·blocked(막힘)·usageLimited(사용 한도)·budgetLimited(예산 한도) 같은 상태와 계속 진행을 멈추는 로직이 들어 있다. 즉 "끝까지"는 무한이 아니라 증거/한도까지다.
• 샌드박스·승인은 별개 층: Codex는 격리 환경에서 돌고, 네트워크·외부 파일·위험 작업 전에는 승인 정책에 따라 묻는다. /goal이 이 안전층을 무시하지 않는다.

좋은 goal vs 나쁜 goal

가장 중요한 차이는 끝점과 증거다.

OpenAI 문서가 든 실제 좋은 예시도 "TypeScript strict 마이그레이션", "홈페이지 TTI < 1초"처럼 상태로 적은 목표다(코드 PR에는 "p95 지연 120ms 미만" 예시도 등장).

좋은 goal의 여섯 요소

1. Outcome(결과) — "분석해줘"보다 "p95 120ms 미만이고 회귀 테스트 통과 상태".
2. Verification(검증면) — 완료를 증명할 명령·스크립트·보고서·데이터·UI 확인.
3. Constraints(제약) — 공개 API·스키마 변경 금지, 테스트 비활성화 금지, 새 의존성 금지.
4. Boundaries(경계) — 건드릴 경로 / 건드리면 안 되는 경로.
5. Iteration(반복 정책) — 한 번에 하나의 가설, 작은 테스트부터, 결과 기록 후 확대.
6. Stop(정지 조건) — 같은 실패 반복·권한/판단 필요 시 추측을 멈추고 보고.

언제 쓰고, 언제 쓰지 말까

실제로 이렇게 쓴다 (OpenAI 공식 예시)

• 버그 트리아지 자동화: Sentry·Slack·Linear·GitHub·로그를 훑어 P0~P3 우선순위를 만들되, "관측 증거와 추측을 분리"하고 "수정·라벨·rerun 금지" 같은 가드레일을 건다.
• 데이터셋 분석 → 리포트: 원자료 보존, join key·null 비율·커버리지 점검, 재현 가능한 스크립트·산출물까지 만들게 한다(예: "고속도로 인접 주택 가치가 낮은가").
• 어려운 문제 반복: 결정적 체크 + LLM-judge 점수를 함께 둬, 두 점수가 모두 임계값(예: 90%)을 넘을 때까지 반복.
• 장시간 작업: /goal Complete [objective] without stopping until [검증 가능한 종료 상태]. 코드 마이그레이션·대규모 리팩터·배포 재시도·실험에 적합하되, "서로 무관한 잡일 목록"은 피하라고 명시한다.

복사해서 쓰는 최소 템플릿

/goal [달성할 최종 상태]를 만든다.

검증:
- [검증 명령 또는 보고서]
- [성공 기준과 숫자 임계값]

제약:
- [바꾸면 안 되는 API, 데이터, 권한, 외부 시스템]
- [금지 작업]

경계:
- 허용 쓰기: [경로]
- 금지 경로: [경로]

반복 정책:
- 한 번에 하나의 가설만 바꾼다.
- 각 시도 뒤 결과와 증거를 기록한다.
- 같은 실패가 3회 반복되면 blocked로 멈추고 보고한다.

완료 조건:
- [모든 검증 통과]
- [산출물 경로]
- [남은 위험과 수동 확인 항목 기록]

현실의 함정 (커뮤니티·GitHub가 말하는 것)

여기가 "전문가처럼" 쓰려면 꼭 알아야 할 부분이다. openai/codex 이슈·PR과 사용자 보고에 따르면:

• 토큰·한도 소진: 한 사용자는 "두 번의 5시간 세션으로 주간 한도를 다 썼다 — 경고도 없이"라고 했다(Reddit). 실제로 PR #23094는 /goal 연속 진행이 한도·차단 상황에서도 토큰을 태우는 문제를 다루며 blocked·usageLimited 상태를 추가했다.
• 컴팩션 실패 → "Goal blocked": 약 1시간 실행 중 자동 컴팩션이 실패하고 재개 시 승인 프롬프트가 반복됐다는 이슈(#28177).
• 승인 프롬프트 반복: 5시간 사용량 창 이후 다음날 재개 시 "Full Access" 표시에도 승인 요청이 반복된다는 보고(#28574). 단, 단일 사용자 보고로 재현률은 미확인.
• 완료 goal이 안 지워짐: Windows CLI에서 완료된 goal을 정리 못 해 새 goal 생성이 막힌다는 보고(#24978), "/Goal Always Fails" 보고(#24269)도 있다.

종합하면 — /goal은 강력하지만 장시간 자율 실행에는 비용·중단·승인 리스크가 따른다. 그래서 정지 조건과 예산 임계값을 목표 안에 명시하는 게 옵션이 아니라 필수다.

커뮤니티는 이렇게 본다

(해외 댓글은 의역. 표본이 제한적이라 전체 여론은 아니다.)

호평 — "이제 진짜 일을 한다"

갑자기 시간 절약 임계점을 넘은 느낌이다. 예전엔 개념 증명 수준이었는데, 이제 진짜 작업을 한다. (r/OpenAI)

비용·한도 불만

두 번의 5시간 세션으로 주간 한도를 다 썼다. 경고도 없이. (r/OpenAI)

예산을 아껴야 한다면, 지금은 Claude가 낫다고 본다. (r/OpenAI)

신뢰성·코드 품질 경고

속도에 중독돼서 생성된 코드를 확인조차 안 하게 됐다. (r/OpenAI)

게으른 프롬프트를 주고 출력을 안 보면, 코드 품질은 순식간에 무너진다. (r/OpenAI)

이 경고들은 OpenAI 공식 입장("통합·실행 전 사람의 검토 필수")과 정확히 같은 방향이다.

운영 매뉴얼

• 시작 전 — 기능 활성화 확인, clean branch/worktree에서 시작. 빠른 검증/전체 검증을 나눠 적고, 허용·금지 경로를 명확히. 긴 작업은 GOAL_PROGRESS.md·PLAN.md·BLOCKERS.md 기록 파일을 쓰면 안정적이다.
• 실행 중 — 모든 줄에 끼어들지 말고 목표대로 가는지 / 올바른 명령인지 / 금지 파일을 건드리는지 / 실패를 반복하는지 / 멈춰야 할 때 멈추는지만 본다.
• 완료 후 — diff 전체 리뷰, 핵심 명령 재실행, 새 의존성·권한 변화 확인. 고위험 코드는 사람이 리뷰하고 병합 전 CI 재확인.

빠른 점검표

• 목표가 흐릿한 행동이 아니라 최종 상태인가? 검증 명령·정량 임계값이 있는가?
• 비즈니스/보안 제약과 허용/금지 경로를 적었는가?
• 반복 방식·정지 조건(특히 "같은 실패 3회 → blocked", "토큰 N 초과 → 정지")을 넣었는가?
• 진행 로그 보존을 요구했는가? clean branch/worktree인가?

이렇게는 쓰지 말자 — "성능 최적화해줘 / 코드 정리해줘 / 프로젝트 좋게 / 이 backlog 알아서 처리해줘." 모두 경계·증거·정지 조건이 없다.

정리

좋은 /goal은 "많이 시키는 말"이 아니라 멈출 수 있고 검증할 수 있는 완료 기준이다. 끝점·증거·제약·경계·반복·정지를 적으면 에이전트는 더 멀리 가면서도 감사 가능하게 일한다. 반대로 이 요소가 빠지면 — 커뮤니티가 증언하듯 — 토큰만 태우고 코드 품질은 무너진다. /goal을 잘 쓴다는 건 결국 '알아서 다 해줘'를 '여기까지, 이렇게 증명하고, 막히면 멈춰'로 번역하는 일이다.

※ 이 글의 삽화는 AI로 생성한 개념 이미지입니다. 가격·한도·기능 세부는 시점·플랜·OS에 따라 다를 수 있으니 공식 문서를 확인하세요.

참고

• OpenAI, Introducing Codex: https://openai.com/index/introducing-codex/
• OpenAI Developers, Prompting(목표 모드): https://developers.openai.com/codex/prompting
• OpenAI Developers, CLI Slash Commands: https://developers.openai.com/codex/cli/slash-commands
• OpenAI Developers, Follow a goal: https://developers.openai.com/codex/use-cases/follow-goals
• OpenAI Developers, Bug triage / Datasets / Iterate: https://developers.openai.com/codex/use-cases/automation-bug-triage
• GitHub openai/codex PR #23094(정지 상태): https://github.com/openai/codex/pull/23094
• GitHub 이슈 #24269·#24978·#28177·#28574(함정 보고): https://github.com/openai/codex/issues/28177
• The Verge(Codex 'virtual coworker'): https://www.theverge.com/command-line-newsletter/668251/chatgpt-is-getting-an-ai-coding-agent
• Reddit r/OpenAI(호평·비용·코드품질): https://www.reddit.com/r/OpenAI/comments/1snakqv/codex_for_almost_everything/