Codex /goal, AI 코딩 에이전트 자동화 방안!

"이 리팩토링, Codex한테 맡겨두고 퇴근하면 안 되나?" 한 번쯤 해본 생각이잖아요. 2026년 5월 2일 출시된 Codex CLI 0.128.0의 /goal 기능이 바로 그걸 가능하게 해줘요. /goal은 하나의 목표를 설정하면 Codex가 plan → act → test → review 루프를 스스로 반복하면서 측정 가능한 종료 조건을 만족할 때까지 자율적으로 작업하는 실험적(experimental) 기능이에요(OpenAI 공식 문서).

Codex /goal, 어떻게 설정하나요?

아직 실험 기능이라 기본 비활성화 상태예요. 활성화까지 세 단계면 충분합니다.

먼저 codex --version으로 버전을 확인하세요. 0.128.0 이상이어야 해요. 이전 버전이라면 npm install -g @openai/codex@latest로 업그레이드하면 돼요(Codex 체인지로그, 2026-05-02).

그 다음 ~/.codex/config.toml 파일을 열어서 아래 두 줄을 추가하세요.

[features]
goals = true

저장 후 Codex CLI를 재시작하면 끝이에요. Claude Code에서 MCP로 Codex를 연동 중이라면 Claude Code도 같이 재시작해야 합니다. 안 그러면 이전 바이너리의 프로토콜을 그대로 감싸서 플래그 에러가 나거든요(J.D. Hodges, 2026-05-08).

사용 가능한 서브커맨드는 딱 다섯 개예요.

커맨드	기능
/goal <objective>	목표 설정 및 실행 시작
/goal	현재 목표 상태 확인
/goal pause	일시정지
/goal resume	재개
/goal clear	목표 제거

일부 SEO 블로그에서 /goal budget이나 /goal status 같은 커맨드를 소개하는데, 2026년 5월 10일 현재 공식 문서에는 존재하지 않아요. 상태 확인은 /goal만 입력하면 됩니다.

"계약(Contract)" 사고방식이 핵심인 이유

/goal을 잘 쓰는 사람과 못 쓰는 사람의 차이는 종료 조건을 측정 가능하게 정의했느냐에 있어요. 일반 프롬프트는 보통 2~3턴이면 끝나지만, /goal은 계약이 충족될 때까지 수십 턴을 자율 실행해요. 종료 조건이 모호하면 Codex가 몇 시간 동안 토큰만 태우거나, 반대로 절반만 하고 "완료"를 선언해버리거든요.

좋은 /goal이 갖춰야 할 다섯 가지 요소가 있어요. 측정 가능한 산출물(어떤 파일이 완료를 증명하는가), 검증 커맨드(종료 코드 0으로 증명할 한 줄 명령), 쓰기 허용 범위(이 디렉토리만 수정 가능), 명확한 종료 신호(리터럴 문장이나 임계값), 일시정지 조건(N회 실패 시, X분 초과 시)이에요.

비교하면 차이가 확연합니다.

나쁜 예	좋은 예
/goal improve auth module	/goal Raise src/auth/ test coverage from 38% to 75%. Only edit files under src/auth/ and tests/auth/. Stop when npm test && npm run coverage shows >= 75% on src/auth/. Pause if 3 consecutive test runs fail with the same error.

OpenAI 공식 문서도 같은 맥락이에요. "Codex should know what done means before it starts." 완료의 정의를 GPS 좌표처럼 찍어줘야 autopilot이 의미 있는 거예요.

실전 예시 1 — 코드 마이그레이션 (Node 14 → 20)

/goal이 가장 빛나는 시나리오는 마이그레이션이에요. 작업이 반복적이고, 테스트 스위트로 검증 가능하기 때문이죠. 새 브랜치를 만들고 Codex에서 아래처럼 목표를 설정하면 됩니다.

/goal Migrate this codebase from Node 14 to Node 20.

Read first:
- package.json, .nvmrc, docs/ARCHITECTURE.md

Required steps:
1. Update .nvmrc and engines field to Node 20.
2. Upgrade dependencies to Node 20 compatible versions.
3. Replace deprecated APIs (url.parse, Buffer(), domain module).
4. Fix breaking changes surfaced by tests.

Validation command:
  npm ci && npm test && npm run lint

Constraints:
- Do not modify business logic in src/services/
- Do not bump major versions of React or Express
- Keep a checkpoint log in MIGRATION_LOG.md

Stop condition: All three validation commands exit 0,
AND MIGRATION_LOG.md ends with "Migration complete;
all tests green on Node 20."

Pause if: same test fails 5 times in a row.

이렇게 설정해두면 Codex가 의존성 하나 올리고 → 테스트 돌리고 → 깨지면 고치고 → 다시 돌리는 루프를 자동으로 반복해요. r/codex 커뮤니티에서 한 사용자가 210개 백로그 태스크를 포함한 트레이딩 앱 리팩토링을 6.5시간 만에 처리했다는 사례가 공유됐어요. $100 플랜 주간 쿼터의 약 20%를 소모했다고 하고요(J.D. Hodges, 2026-05-08).

실전 예시 2 — PLAN.md 기반 프로토타입 개발

새 앱을 처음부터 만들 때 추천하는 패턴은 PLAN.md 파일을 진실의 원천(source of truth)으로 쓰는 거예요. 마일스톤별로 TDD 방식(테스트 먼저 작성 → 구현 → 검증)을 적용하면 Codex가 방향을 잃지 않아요.

/goal Implement PLAN.md milestone by milestone.

Workflow per milestone:
1. Read the milestone section in PLAN.md.
2. Write the acceptance test FIRST (TDD).
3. Implement code until the test passes.
4. Append checkpoint to PROGRESS.md with: milestone id,
   timestamp, files changed, test result.
5. Move to next milestone only when acceptance exits 0.

Constraints:
- Do not skip or merge milestones.
- Do not add features not in PLAN.md.
- All commits prefixed with "M1:", "M2:", etc.

Stop condition: PROGRESS.md contains "complete" for M5,
AND npm run build && npm test && npx playwright test pass.

Pause if: milestone needs an API key I haven't provided.

방향이 달라져야 할 때는 /goal pause 후 PLAN.md만 수정하고 /goal resume하면 돼요. 별도의 프롬프트 재작성 없이 문서 하나로 Codex의 행동을 제어하는 구조가 핵심이에요.

실전 예시 3 — 테스트 커버리지 끌어올리기

기존 코드베이스에 테스트가 부족할 때 가장 가성비 높은 사용법이에요. 여기서 핵심 제약은 "src/ 수정 금지"를 반드시 명시하는 거예요. 안 걸면 Codex가 테스트하기 어려운 코드를 만나면 프로덕션 코드를 멋대로 리팩토링해버리거든요.

/goal Raise test coverage of src/utils/ from 42% to >= 80%.

Read first:
- coverage/coverage-summary.json
- src/utils/*.ts, tests/utils/

Workflow:
1. Identify uncovered lines from coverage report.
2. Write tests in tests/utils/ (AAA pattern).
3. Run npm test -- --coverage after each file.
4. Log progress in COVERAGE_LOG.md.

Constraints:
- DO NOT modify any file under src/.
- Each test must have a meaningful assertion.
- Skip pure type definitions (.d.ts).

Stop condition: npm test -- --coverage reports >= 80%
statements, branches, functions, lines for src/utils/.

Pause if: unclear behavior that requires a product decision
(log to QUESTIONS.md and pause).

실행 중 모니터링과 자주 하는 실수

목표를 설정하면 Codex는 백그라운드 태스크처럼 자율 실행돼요. /goal을 입력해서 현재 체크포인트와 검증 결과를 확인할 수 있고, 방향이 이상하면 /goal pause로 멈추고 지시를 추가한 뒤 /goal resume으로 재개하면 돼요. 완전히 다른 방향이 필요하면 /goal clear로 지우고 새 목표를 설정하면 됩니다.

실무에서 자주 보이는 실수 네 가지를 정리해볼게요.

실수	결과	회피 방법
종료 조건을 자연어로 작성	Codex가 검증 불가, 절반만 하고 완료 선언	반드시 명령어 종료 코드나 파일 검사로 환원
샌드박스를 너무 넓게 개방	무한 루프 시 시스템 파일까지 수정 가능	--sandbox workspace-write로 시작, 필요 시만 확대
할당량(quota) 관리 무시	18시간 실행 시 $100 플랜 주간 쿼터 10% 이상 소모	처음에는 Hard cap 60 minutes wall-clock. 추가
모호한 목표로 "완료" 오판	거짓 양성으로 조기 종료	외부 검증 도구(테스트, 빌드, 린트) 종료 코드로 정의

J.D. Hodges의 실사용 리뷰에서도 같은 점을 강조해요. 60분 제한을 건 폰트 매칭 작업에서 Codex가 DNS가 차단된 샌드박스 안에서 외부 서비스에 접근할 수 없자, 결과를 조작하지 않고 "외부 매처 업로드를 수행하지 못했다"고 솔직하게 보고했다고 해요. 종료 조건에 리터럴 문장을 지정한 덕분에 계약대로 동작한 거예요(J.D. Hodges, 2026-05-08).

/goal을 쓰지 말아야 할 작업은?

OpenAI 공식 문서가 직접 명시한 부적합 영역이 있어요. 탐색적 설계, 아키텍처 결정, 이해관계자 판단이 필요한 작업, "더 좋게 만들어" 같은 모호한 종료 조건이 해당돼요. 이런 건 일반 Codex 프롬프트나 /plan 모드로 대화하며 진행하는 게 맞아요(OpenAI Docs).

/goal을 한 문장으로 요약하면 이거예요. "Codex가 자기 진척도를 증거로 검증할 수 있는가?" 이 질문에 "예"면 /goal이 강력하고, "아니오"면 일반 프롬프트가 낫습니다. 처음 시도한다면 테스트 커버리지 한 디렉토리 올리기 같은 작은 작업에 60분 제한을 걸고 시작해보세요. AI 코딩 에이전트 자동화의 최신 트렌드와 실무 인사이트는 휴미즈에서 확인할 수 있어요.

자주 묻는 질문 (FAQ)

이 글은 기업 데이터 관리 및 AI 트렌드 전문 기업 휴미즈가 OpenAI 공식 문서와 공개된 외부 리뷰를 기반으로 작성했습니다. /goal은 실험적 기능으로 향후 변경되거나 제거될 수 있으며, 인용된 비용·사례는 각 출처 기준입니다.