Codex를 사용하다 보면 간단한 수정은 한 번의 요청으로 끝나지만, 규모가 있는 작업은 그렇지 않은 경우가 많다.
예를 들어 다음과 같은 작업은 한 번의 요청만으로 안정적으로 끝내기 어렵다.
- 여러 파일에 걸친 기능 구현
- 기존 구조를 유지해야 하는 리팩토링
- 테스트 실패 원인 분석 후 수정 반복
- 마이그레이션 작업과 검증
- 빌드 오류를 해결하면서 최종 통과까지 진행
이런 작업에서는 단순히 코드를 작성하는 것보다 어떤 상태가 되면 작업이 끝난 것인지 정의하는 것이 중요하다.
Codex에는 이러한 장시간 작업을 목표 단위로 수행할 수 있도록 /goal 명령어가 제공된다.
이번 글에서는 Codex의 /goal이 무엇인지, 그리고 함께 이해하면 좋은 Ralph Loop 개념을 정리한다.
Ralph Loop란?
Ralph Loop는 AI 코딩 에이전트에게 목표를 주고, 구현 결과를 검증한 뒤, 실패 결과를 다시 다음 수정의 입력으로 사용하면서 완료 조건에 도달할 때까지 반복하는 방식이다.
일반적인 AI 요청은 다음처럼 사용할 수 있다.
로그인 기능을 구현해줘.이 요청은 로그인 관련 코드가 생성되면 일단 작업이 끝났다고 볼 수 있다.
하지만 실제 개발에서는 코드가 생성되었다고 해서 기능이 완성된 것은 아니다.
- 빌드가 성공하는지
- 테스트가 통과하는지
- 기존 기능이 깨지지 않았는지
- 예외 상황도 처리되는지
까지 확인해야 한다.
Ralph Loop 방식에서는 요청에 완료 조건을 함께 포함한다.
로그인 기능을 구현하고,
관련 테스트가 모두 통과하며,
잘못된 인증 요청에 대한 예외 처리까지 확인될 때까지
수정과 검증을 반복해줘.즉, Ralph Loop의 핵심은 실패를 종료 신호로 보는 것이 아니라, 다음 수정 작업을 위한 입력으로 사용하는 것이다.
목표 설정
↓
코드 구현
↓
테스트 또는 빌드 실행
↓
실패 결과 확인
↓
코드 수정
↓
다시 검증
↓
완료 조건을 만족할 때까지 반복Ralph Wiggum Loop는 Geoffrey Huntley가 소개한 AI 코딩 에이전트 반복 실행 방식으로 알려져 있다. OpenAI 역시 Codex를 활용하는 개발 방식에 관한 글에서, Codex가 피드백에 대응하고 모든 검토 조건이 충족될 때까지 반복하는 구조를 “Ralph Wiggum Loop”라고 설명한다.
Codex의 /goal이란?
/goal은 Codex에 지속적인 목표와 검증 가능한 종료 조건을 설정하는 명령어다.
일반적인 요청이 하나의 응답 단위로 처리되는 것과 달리, /goal은 Codex가 여러 단계에 걸쳐 같은 목표를 유지하면서 작업하도록 한다.
OpenAI 공식 문서에서는 /goal을 다음과 같은 작업에 적합하다고 설명한다.
- 명확한 성공 조건과 검증 루프가 있는 장시간 작업
- 코드 마이그레이션
- 대규모 리팩토링
- 배포 재시도 루프
- 반복적으로 개선할 수 있는 실험이나 프로토타입
예를 들어 단순히 필드 하나를 추가하는 작업이라면 일반 요청으로도 충분하다.
CustomActionRequestV2 클래스에 requesterName 필드를 추가해줘.반면 액션 파이프라인처럼 여러 파일 수정과 검증이 필요한 기능은 /goal에 더 잘 맞는다.
/goal 액션 파이프라인 실행 기능을 구현한다.
완료 조건:
- 기존 단일 액션 실행 기능은 그대로 동작해야 한다.
- 파이프라인 step은 정의된 순서대로 실행되어야 한다.
- 각 step의 실행 이력과 최종 상태가 저장되어야 한다.
- 관련 테스트를 추가한다.
- 전체 빌드가 성공할 때까지 수정과 검증을 반복한다.이처럼 /goal은 단순히 “오래 실행되는 요청”이 아니라, Codex가 무엇을 완료로 판단해야 하는지 알려주는 작업 계약에 가깝다.
일반 요청과 /goal의 차이
| 구분 | 일반 요청 | /goal |
|---|---|---|
| 작업 범위 | 단일 수정이나 질문 | 여러 단계가 필요한 작업 |
| 진행 방식 | 한 번의 응답 중심 | 목표를 유지하며 반복 진행 |
| 완료 기준 | 요청 결과 생성 | 정의한 종료 조건 충족 |
| 검증 | 사용자가 추가로 요청 | 테스트·빌드 등 검증 루프 포함 가능 |
| 적합한 예 | 메서드 설명, 문구 수정, 작은 코드 변경 | 기능 구현, 리팩토링, 마이그레이션, 반복 오류 수정 |
작업이 크다고 무조건 /goal을 사용하는 것은 아니다.
중요한 기준은 다음 두 가지다.
- 여러 번의 구현과 검증이 필요한가?
- “완료”를 판단할 수 있는 조건을 작성할 수 있는가?
두 조건에 모두 해당한다면 /goal을 사용하는 것이 적절하다.
/goal 사용 방법
Codex에서 목표는 다음과 같이 설정할 수 있다.
/goal <수행할 목표와 완료 조건>OpenAI 공식 문서에서 제시하는 기본 형태는 다음과 같다.
/goal Complete [objective] without stopping until [verifiable end state].이를 실제 프로젝트 작업에 맞게 작성하면 다음과 같다.
/goal 액션 파이프라인 실행 기능을 구현한다.
먼저 확인할 내용:
- 기존 단일 액션 실행 흐름
- 관련 엔티티와 Repository
- 현재 테스트 구조
- DB migration 작성 규칙
제약 조건:
- 기존 단일 액션 실행 API의 응답 형식은 변경하지 않는다.
- 기존 Flyway migration 파일은 수정하지 않는다.
- 운영 배포나 데이터 삭제 작업은 수행하지 않는다.
완료 조건:
- pipeline과 step 실행 구조가 구현되어야 한다.
- step별 실행 이력이 저장되어야 한다.
- 관련 테스트가 추가되어야 한다.
- 전체 테스트와 빌드가 성공해야 한다.좋은 /goal에는 다음 내용이 포함되는 것이 좋다.
- 무엇을 변경할 것인지
- Codex가 먼저 확인해야 할 자료나 파일
- 변경하면 안 되는 범위
- 실행할 테스트 또는 검증 명령어
- 어떤 상태가 되면 작업을 종료할지
/goal 관련 명령어
목표를 설정하거나 관리할 때는 다음 명령어를 사용할 수 있다.
/goal <objective>새로운 목표를 설정한다.
/goal현재 목표와 진행 상태를 확인한다.
/goal pause진행 중인 목표를 일시 중지한다.
/goal resume중지된 목표를 다시 진행한다.
/goal clear설정된 목표를 제거한다.
Codex app에서는 목표가 활성화되면 입력창 위에 진행 상태가 표시되며, 화면의 버튼으로 목표를 일시 중지하거나 재개하고, 수정하거나 제거할 수도 있다.
/goal이 보이지 않는 경우
/goal이 slash command 목록에 나타나지 않는다면 goals 기능을 활성화해야 할 수 있다.
config.toml에 다음 설정을 추가한다.
[features]
goals = trueCLI에서는 다음 명령어로 활성화할 수도 있다.
codex features enable goals공식 문서 기준으로 Goal mode는 Codex app, Codex IDE extension, Codex CLI에서 사용할 수 있다.
/plan과 함께 사용하는 방법
규모가 있는 작업에서는 바로 구현을 시작하는 것보다 먼저 변경 범위와 완료 조건을 정리하는 것이 안전하다.
Codex 공식 문서에서도 목표를 처음부터 명확하게 정의하기 어렵다면 /plan으로 먼저 목표를 구체화한 뒤 구현을 시작하는 방식을 안내한다.
예를 들어 기존 서버 등록 기능을 Custom Action 기반으로 변경한다고 가정해보자.
처음부터 다음처럼 요청하면 범위가 모호할 수 있다.
/goal 서버 등록 기능을 Custom Action 구조로 변경해줘.어떤 기존 동작을 유지해야 하는지, 실행 이력은 어디에 저장해야 하는지, 화면까지 변경해야 하는지 알기 어렵다.
이럴 때는 먼저 /plan으로 구현 방향을 정리한다.
/plan 기존 서버 등록 기능을 Custom Action 기반 실행 구조로 변경하기 위한 계획을 작성해줘.
다음을 포함해줘.
- 현재 실행 흐름에서 변경되는 부분
- 변경 대상 클래스와 테이블
- 기존 화면 재사용 가능 여부
- 실행 이력 저장 방식
- 회귀 테스트와 검증 방법계획을 확인한 뒤 구체적인 완료 조건을 포함해 /goal을 설정한다.
/goal 작성한 계획을 기준으로 서버 등록 기능을 Custom Action 실행 구조로 변경한다.
제약 조건:
- 기존 화면의 요청 형식은 가능한 한 유지한다.
- 기존 migration 파일은 수정하지 않는다.
- 운영 배포는 수행하지 않는다.
완료 조건:
- 서버 등록 요청이 CustomAction 기반 이벤트로 실행되어야 한다.
- 실행 이력이 task 테이블에 저장되어야 한다.
- 배포 관리 화면에서 실행 결과를 조회할 수 있어야 한다.
- 관련 테스트와 전체 빌드가 성공해야 한다.정리하면 /plan은 작업의 방향과 영향 범위를 정리하는 역할이고, /goal은 실제 구현과 검증을 반복하며 완료 상태까지 진행하는 역할이다.
Ralph Loop와 /goal의 관계
Ralph Loop와 Codex /goal은 완전히 같은 기능을 의미하는 것은 아니다.
Ralph Loop는 AI 에이전트가 결과와 오류를 다시 입력으로 사용하면서 반복적으로 개선하는 작업 방식이다.
반면 /goal은 Codex에서 지속적인 목표와 종료 조건을 설정해 장시간 작업을 수행하도록 하는 명령어이자 기능이다.
| 구분 | Ralph Loop | Codex /goal |
|---|---|---|
| 형태 | 에이전트 반복 실행 방식 | Codex의 Goal mode 명령어 |
| 핵심 | 실패 결과를 다음 수정에 반영 | 목표와 완료 조건을 계속 유지 |
| 활용 | 스크립트나 에이전트 실행 흐름으로 구성 | Codex app, IDE extension, CLI에서 사용 |
| 목적 | 반복적인 구현·검증 자동화 | 장시간 작업을 종료 조건까지 진행 |
즉, Ralph Loop가 “구현하고, 실패를 확인하고, 다시 수정하는 반복 구조”를 설명한다면, /goal은 Codex에서 그러한 방식의 작업을 목표 중심으로 실행하기 쉽게 만들어주는 기능이라고 이해할 수 있다.
좋은 /goal 작성 방법
다음과 같은 목표는 좋지 않다.
/goal 프로젝트를 개선해줘.“개선”의 범위가 너무 넓고, 무엇이 완료인지 판단할 수 없기 때문이다.
반면 다음 목표는 Codex가 완료 상태를 판단하기 쉽다.
/goal 사용자 조회 API의 잘못된 전체 조회 가능성을 제거한다.
확인 대상:
- UserFinder
- UserMapper.xml
- 사용자 검색 API 테스트
제약 조건:
- 기존 응답 DTO 형식은 변경하지 않는다.
- 조회 조건이 있는 정상 요청 동작은 유지한다.
완료 조건:
- 조회 조건이 비어 있는 경우 전체 데이터가 반환되지 않아야 한다.
- 관련 테스트를 추가한다.
- 전체 테스트가 통과해야 한다.1. 완료 조건을 검증 가능하게 작성한다
관련 테스트를 추가하고 ./gradlew test가 성공해야 한다.처럼 실행 결과로 확인할 수 있는 기준을 적는 것이 좋다.
2. 변경하지 않을 범위를 함께 적는다
기존 API 응답 형식은 변경하지 않는다.
기존 migration 파일은 수정하지 않는다.같은 제약 조건을 적으면 불필요하게 변경 범위가 커지는 것을 막을 수 있다.
3. 위험한 작업은 제외한다
장시간 반복 작업이라고 해도 운영 배포, 운영 데이터 삭제, 되돌리기 어려운 외부 시스템 변경까지 자동으로 맡기는 것은 위험하다.
운영 배포는 수행하지 않는다.
DB 데이터 삭제는 수행하지 않는다.
DDL 변경이 필요하면 신규 migration 파일 작성까지만 진행한다.4. 서로 관련 없는 목표를 한 번에 넣지 않는다
다음과 같은 목표는 범위가 너무 넓다.
/goal 로그인 기능 수정, 배포 파이프라인 개선, 관리자 UI 리뉴얼,
로그 저장 구조 변경까지 모두 처리해줘.하나의 목적 단위로 목표를 나누는 편이 검증과 리뷰가 쉽다.
활용 예시
테스트 실패 수정
/goal 현재 실패 중인 테스트의 원인을 분석하고 수정한다.
제약 조건:
- 테스트를 삭제하거나 skip 처리해서 통과시키지 않는다.
- 기존 정상 동작을 임의로 변경하지 않는다.
완료 조건:
- 실패 원인이 코드 또는 테스트 기준으로 정리되어야 한다.
- 수정 후 전체 테스트가 통과해야 한다.리팩토링
/goal Custom Action 실행 로직에서 조회 책임과 상태 변경 책임을 분리한다.
제약 조건:
- 기존 API 동작은 유지한다.
- Finder는 조회만 담당한다.
- 상태 변경과 저장은 Service가 담당한다.
완료 조건:
- 관련 클래스 구조가 책임에 맞게 분리되어야 한다.
- 기존 테스트와 신규 테스트가 모두 통과해야 한다.
- 전체 빌드가 성공해야 한다.DB 마이그레이션
/goal 액션 파이프라인 저장 구조를 추가한다.
제약 조건:
- 기존 Custom Action 테이블은 변경하지 않는다.
- 기존 Flyway migration 파일은 수정하지 않는다.
- 신규 migration 파일만 추가한다.
완료 조건:
- pipeline과 step 관계를 저장할 수 있어야 한다.
- 엔티티와 Repository가 신규 구조를 지원해야 한다.
- 애플리케이션 빌드와 관련 테스트가 성공해야 한다.마무리
Codex의 /goal은 단순히 작업을 오래 실행시키는 명령어가 아니다.
목표와 완료 조건을 정의하고, Codex가 구현과 검증을 반복하면서 실제 완료 상태에 도달하도록 만드는 기능이다.
간단한 코드 수정이나 설명 요청은 일반 요청으로 충분하다.
하지만 다음과 같은 작업이라면 /goal을 활용해볼 수 있다.
- 여러 파일에 걸친 기능 구현
- 테스트 실패 수정 반복
- 대규모 리팩토링
- 코드 마이그레이션
- 빌드와 검증 조건이 명확한 장시간 작업
특히 작업 범위가 크다면 /plan으로 먼저 방향을 정리하고, 검증 가능한 완료 조건을 포함한 /goal을 설정하는 방식이 안정적이다.
Ralph Loop가 반복적인 구현과 검증의 개념을 설명한다면, Codex의 /goal은 이를 실제 작업 흐름에서 목표 중심으로 사용할 수 있게 해주는 기능이라고 볼 수 있다.
참고 자료
