Codex Goals 사용법: 완료 조건·검증·템플릿

세 줄 요약

Goal은 여러 턴에 걸쳐 유지되는 완료 계약이다.
좋은 Goal은 결과·검증 표면·제약·범위·반복 정책·중단 조건 여섯 가지를 정의한다.
한 줄 수정이나 완료 기준 없는 “더 좋게”에는 Goal보다 일반 프롬프트가 낫다.

“계속해”, “다음 방법도 해봐”, “테스트 다시 돌려”를 여러 번 보내고 있다면 문제는 프롬프트 길이가 아니라 목표의 지속성일 수 있다. Codex Goal은 현재 스레드에 끝나는 조건을 붙여 중간 결과 뒤에도 다음 유용한 행동을 선택하게 한다.

그러나 Goal은 무제한 자율 실행이 아니다. 사용자가 결과와 경계를 정하고, Codex는 스레드에 쌓인 테스트·벤치마크·파일·보고서 같은 증거로 완료 여부를 판단한다. 목표가 모호하면 오래 일해도 끝을 증명할 수 없다.

Goal이 맞는 작업은 경로가 아니라 끝이 분명하다

성능 최적화, 간헐 테스트 재현, 의존성 마이그레이션, 여러 번의 측정이 필요한 버그 조사처럼 다음 행동이 직전 결과에 따라 달라지는 작업에 맞는다.

반대로 오탈자 수정, 짧은 설명, 한 번의 코드 리뷰는 일반 요청이 빠르다. Goal은 큰 작업을 위한 장식이 아니라 “결과는 정의됐지만 도달 경로가 불확실한” 문제를 위한 상태다.

/goal 명령과 수명주기

공식 가이드 기준 Goals는 Codex 0.128.0부터 제공된다. /goal 뒤에 목표를 적어 시작하고, 인수 없이 입력하면 현재 Goal을 볼 수 있다. pause, resume, clear로 사용자가 상태를 통제한다.

Goal은 전역 기억이나 프로젝트 규칙이 아니라 스레드 상태다. 같은 스레드의 파일 조사, 명령 출력, diff와 실패 기록을 바탕으로 다음 행동과 완료 여부를 판단한다.

/goal Reduce p95 checkout latency below 120 ms without regressing correctness tests
/goal          # 현재 Goal 보기
/goal pause    # 일시정지
/goal resume   # 재개
/goal clear    # 제거

강한 Goal의 여섯 가지 구성요소

결과는 끝났을 때 참이어야 할 상태다. 검증 표면은 그것을 증명할 테스트·벤치마크·보고서·산출물이다. 제약은 작업 중 망가지면 안 되는 조건, 범위는 사용 가능한 파일·도구·데이터다.

반복 정책은 각 시도 뒤 다음 행동을 고르는 기준이다. 마지막 중단 조건은 유효한 경로가 없거나 외부 입력이 필요할 때 무엇을 근거로 멈추고 무엇을 요청할지 정한다.

Outcome
Verification surface
Constraints
Boundaries
Iteration policy
Blocked stop condition

약한 Goal과 강한 Goal의 차이

“결제 속도를 개선해”는 정도와 증거가 없다. “p95 120ms 미만”만 붙여도 정확성이나 측정 환경이 빠져 있다.

좋은 Goal은 길기 때문이 아니라 완료·실패·불확실성을 구분할 수 있기 때문에 강하다.

/goal 결제 벤치마크 기준 p95를 120ms 아래로 낮추고 정확성 테스트를 모두 유지한다.
checkout 서비스와 관련 fixture·테스트만 사용한다.
각 반복에서 변경, 측정 결과, 다음 실험을 기록한다.
벤치마크를 실행할 수 없거나 유효한 경로가 없으면 시도한 방법, 증거, 막힌 이유와 필요한 입력을 보고하고 멈춘다.

완료는 서술이 아니라 증거로 판정한다

코드가 그럴듯해 보인다는 말은 완료 증거가 아니다. 목표가 성능이면 같은 조건의 전후 벤치마크, 회귀 방지라면 테스트 결과, 문서라면 빌드와 명령 정확성이 필요하다.

연구 Goal은 더 엄격해야 한다. 확인된 결과, 근사 재현, 보조 근거, 막힌 주장과 남은 불확실성을 분리하도록 처음부터 요구해야 모델이 불완전한 증거를 성공으로 포장하지 않는다.

Goal이 오래 돌아도 실패하는 세 가지 이유

첫째, “전체 시스템 개선”처럼 감사할 표면이 없다. 둘째, 예산이나 외부 권한이 부족한데 중단 조건이 없다. 셋째, 측정값을 개선하려고 제품 정확성을 희생해도 막을 제약이 없다.

Goal을 시작하기 전 마지막 문장을 읽어보라. 누가 어떤 결과를 보고 성공과 실패를 구분할 수 없다면 Goal도 구분할 수 없다. 목표를 더 크게 쓰지 말고 판정 가능한 표면을 더 구체적으로 써야 한다.

핵심 구분

프롬프트는 이번 일, AGENTS.md는 저장소 규칙, Skill은 반복 절차, Goal은 지속 목표다

서브에이전트는 독립 작업을 나누고 MCP는 외부 도구와 정보를 연결한다. 역할을 섞지 않을수록 지시는 짧아지고 결과는 더 예측 가능해진다.

자주 묻는 질문

Codex Goal은 일반 프롬프트와 무엇이 다른가?

프롬프트는 다음 행동을 요청하고 결과 뒤 기다린다. Goal은 스레드에 완료 조건을 유지해 증거를 확인하고 완료·계속·중단을 판단한다.

Goal을 쓰면 Codex가 무제한으로 실행되나?

아니다. Goal은 사용자 경계, 승인 정책, 예산과 중단 조건 안에서만 유지된다.

좋은 완료 조건은 무엇인가?

테스트, 벤치마크, 빌드된 페이지, 재현 보고서처럼 외부에서 확인 가능한 결과다.

언제 Goal을 쓰지 말아야 하나?

한 줄 수정, 짧은 설명, 단발성 리뷰, 완료 기준이 없는 “더 좋게 만들어”에는 일반 프롬프트가 낫다.