Codex CLI /goal 기능으로 AI 에이전트 루프 자동화하기 — 반복 실행 기반 목표 달성 구현 가이드 (id.news.hada.io)

한줄 요약

Codex CLI 0.128.0의 /goal 기능 — AI 에이전트가 목표 완료까지 루프를 자동 반복한다.

어떤 상황에서 필요한가?

AI 에이전트를 실무에 투입하다 보면 반드시 맞닥뜨리는 문제가 있다. 단일 프롬프트 한 번으로 끝나지 않는 작업이다. 코드 리팩토링, 테스트 자동화, 다단계 데이터 처리처럼 "조건이 충족될 때까지 반복"이 필요한 태스크에서 기존 CLI 도구는 매번 사람이 개입해서 다음 스텝을 지시해야 했다.

이 문제를 해결하려면 에이전트 스스로 "아직 목표가 달성되지 않았다"는 판단을 내리고, 다음 이터레이션을 자율적으로 실행하는 루프 구조가 필요하다. Codex CLI는 버전 0.128.0에서 /goal 기능을 도입해 이 흐름을 CLI 레벨에서 공식 지원하기 시작했다.

에이전트가 목표를 향해 스스로 반복 실행하는 패턴은 Ralph loop라는 개념으로 불린다. 단순히 프롬프트를 반복 호출하는 것이 아니라, 매 턴마다 목표 달성 여부를 자체 평가하고 계속 여부를 결정하는 구조다. 이 방식은 LLM 에이전트 설계에서 점점 표준에 가까워지고 있는 패턴이기도 하다.

핵심 구현 방법

/goal 기능의 실제 구현은 놀랍도록 단순하다. 두 개의 프롬프트 템플릿을 매 턴 말미에 자동 주입하는 방식으로 동작한다.

goals/continuation.md — 현재 상태를 보고 목표가 달성됐는지, 아니면 루프를 계속해야 하는지 판단하도록 유도하는 프롬프트다. 에이전트는 이 템플릿을 기반으로 "계속할지 멈출지"를 스스로 결정한다.

goals/budget_limit.md — 토큰 예산이 소진됐을 때 처리를 담당한다. 목표 달성 여부와 관계없이 예산 한도에 도달하면 루프를 종료시키는 안전장치 역할을 한다.

이 두 템플릿이 루프의 핵심 제어 로직을 담당하고, Codex CLI는 매 턴 종료 시점에 이를 자동으로 삽입한다. 개발자 입장에서는 별도 오케스트레이션 코드 없이 목표만 정의하면 에이전트가 알아서 반복 실행한다.

기능 활성화 방법은 간단하다. 0.128.0으로 업데이트 후에도 기능이 보이지 않는다면 config.toml에 다음을 추가한다.

[features]
goals = true

현재 데스크탑 버전은 개발 중이며, CLI 버전에서 먼저 사용 가능하다.

실전에서 주의할 점

토큰 예산 설계가 핵심이다. 루프가 자동으로 반복되는 구조인 만큼 예산 설정 없이 실행하면 의도치 않게 많은 토큰을 소비할 수 있다. 처음에는 보수적으로 예산을 잡고, 실제 태스크 완료에 필요한 이터레이션 수를 파악한 뒤 점진적으로 조정하는 것이 좋다.

목표 정의의 구체성이 루프 품질을 결정한다. 에이전트가 "목표 달성 여부"를 스스로 판단하는 구조이기 때문에, 목표가 모호하면 루프가 잘못된 조건에서 종료되거나 불필요하게 반복될 수 있다. "특정 테스트가 전부 통과할 때까지", "파일 구조가 이 형태가 될 때까지"처럼 측정 가능한 형태로 목표를 작성해야 한다.

루프 중간 상태 모니터링이 필요하다. 완전 자율 반복이라는 편리함의 이면에는 예상치 못한 방향으로 에이전트가 진행할 가능성이 있다. 특히 파일 시스템이나 외부 API를 건드리는 태스크라면 초기에는 각 이터레이션 결과를 확인하는 습관을 들이는 것이 안전하다.

continuation.md와 budget_limit.md 템플릿은 커스터마이징 여지가 있다. 내부적으로 프롬프트 템플릿 주입 방식으로 구현됐다는 점은, 이 파일을 수정하거나 프로젝트별로 조정할 수 있음을 시사한다. 현재 공식 문서가 충분하지 않은 만큼 소스 코드 수준에서 파악해두는 것이 실전 활용에 유리하다.

이 패턴은 단순 CLI 도구를 넘어 자율 에이전트 설계의 기본 원리를 직접 구현으로 보여준다는 점에서 의미 있다. 목표 기반 루프, 자체 평가, 예산 제어 — 이 세 요소의 조합은 앞으로 더 많은 AI 도구에서 표준 패턴으로 자리잡을 가능성이 높다.