goal 명령어는 Claude Code와 Codex에게 “이 상태가 될 때까지 계속 확인하고 고쳐 달라”고 맡기는 방법입니다. 한 번 질문하고 답을 받는 용도보다는, 코드 분석, 버그 수정, 테스트 보강, 릴리스 점검처럼 여러 번 보고 고쳐야 끝나는 작업에 잘 맞습니다.
처음에는 아래처럼 아주 짧게 써도 됩니다.
/goal 전체 코드를 정밀 분석하고 발견된 문제를 수정한다. 더 이상 실질적인 이슈가 발견되지 않을 때까지 반복한다.이 문장은 “분석해줘”와 다릅니다. 분석에서 멈추지 않고, 발견한 문제를 고치고, 다시 검사하고, 왜 이제 멈춰도 되는지까지 확인하게 만들기 때문입니다. 다만 좋은 goal 명령어는 길게 돌리는 주문이 아닙니다. 무엇을 끝내야 하는지, 어디까지 봐야 하는지, 무엇으로 검증할지, 언제 멈출지를 적은 작업 계약에 가깝습니다.
이 글에서는 Claude Code와 Codex의 /goal을 초보자 기준으로 정리합니다. 커뮤니티에서 Ralph Loop라고 부르던 반복 패턴, Anthropic과 OpenAI 공식 문서의 설명, 그리고 실제 개발에서 바로 복붙해 볼 수 있는 goal 명령어 예시를 함께 묶었습니다. 반복형 자동화가 낯설다면 먼저 Claude Code /loop로 스킬 점검 자동화하기와 바이브코딩은 구현·리뷰·수정의 반복입니다를 같이 보면 흐름이 더 쉽게 잡힙니다.
goal 명령어가 필요한 순간
AI 코딩 에이전트는 한 번에 꽤 많은 일을 합니다. 그래도 작업이 길어지면 중간에 멈춥니다. “여기까지 분석했습니다”, “몇 가지를 수정했습니다”, “다음으로 테스트하면 좋습니다” 같은 답을 받고 나면 사용자가 다시 “계속해”, “테스트 돌려”, “남은 문제 찾아”를 입력해야 합니다.
/goal은 이 반복 지시를 하나로 묶습니다. 사용자는 목표와 완료 조건을 먼저 적습니다. 에이전트는 한 번 작업한 뒤 바로 끝내지 않고, 조건을 만족했는지 확인합니다. 아직 부족하면 다음 작업을 이어가고, 조건을 만족했다고 판단되면 멈춥니다.
그래서 /goal은 “긴 작업을 알아서 해 줘”가 아니라 “완료 조건을 계속 의식하면서 작업해 줘”에 가깝습니다. 초보자 입장에서는 이 차이가 중요합니다. 목표가 흐리면 오래 돌아도 결과가 흔들리고, 목표가 선명하면 짧게 돌려도 도움이 됩니다.
Claude Code의 /goal은 어떻게 작동하나
Claude Code 공식 문서에 따르면 /goal은 현재 세션에 완료 조건을 설정하는 명령입니다. Claude가 한 턴의 작업을 끝내면 별도의 빠른 평가 모델이 목표 조건과 지금까지의 대화 내용을 보고 끝났는지 판단합니다. 조건이 만족되지 않았으면 Claude가 다음 턴을 이어가고, 만족되면 goal이 자동으로 정리됩니다.
여기서 놓치기 쉬운 점이 있습니다. 평가자는 직접 파일을 읽거나 테스트를 실행하지 않습니다. 그래서 “테스트 통과”를 완료 조건으로 썼다면 Claude가 실제로 테스트를 실행하고 그 결과를 대화에 남겨야 합니다. Claude Code의 goal 문서는 Keep Claude working toward a goal에서 확인할 수 있습니다.
Codex의 /goal은 어떻게 쓰나
Codex도 같은 방향의 Goal mode를 제공합니다. OpenAI 공식 문서에서는 /goal을 검증 가능한 중단 조건을 향해 여러 턴 동안 계속 작업해야 할 때 쓰는 기능으로 설명합니다. Codex CLI, ChatGPT 데스크톱 앱, IDE 확장에서 사용할 수 있고, /goal <objective>로 목표를 설정합니다.
상태 확인과 제어도 명령어로 합니다. /goal은 현재 목표를 보여 주고, /goal edit은 목표를 수정합니다. /goal pause, /goal resume, /goal clear는 각각 일시정지, 재개, 제거에 씁니다. Codex Goal mode의 기본 흐름은 Follow a goal, 명령어 세부 내용은 Developer commands 문서에 정리되어 있습니다.
Ralph Loop와 /goal의 차이
커뮤니티에서는 예전부터 비슷한 방식을 Ralph Loop라고 불렀습니다. 핵심은 단순합니다. 에이전트가 “끝났다”고 말하면 다시 문맥으로 불러와 “정말 끝났는가?”를 묻는 반복 구조입니다. Anthropic의 Long-running Claude for scientific computing 글에서도 Ralph Loop를 장시간 작업에 유용한 반복 오케스트레이션 패턴으로 설명합니다.
차이는 사용 난이도입니다. Ralph Loop는 대개 쉘 스크립트, stop hook, 외부 플러그인처럼 사용자가 직접 반복 장치를 만들어야 합니다. 반면 Claude Code와 Codex의 /goal은 그 반복을 세션 안의 명령어로 제공합니다. 처음 시작한다면 /goal이 더 쉽습니다. 다만 PR을 계속 감시하거나, 외부 이벤트가 생길 때마다 반복 실행해야 한다면 /loop나 hook이 더 어울릴 수 있습니다.
좋은 goal 명령어의 기본 구조
처음에는 한 줄로 시작해도 됩니다. 하지만 실무에서 안정적으로 쓰려면 아래 네 가지를 넣는 편이 좋습니다.
- 목표: 어떤 결과가 만들어져야 하는지 적습니다.
- 범위: 먼저 읽을 파일, 수정해도 되는 영역, 건드리면 안 되는 영역을 적습니다.
- 검증: 어떤 명령, 로그, 스크린샷, 체크리스트로 완료를 증명할지 적습니다.
- 중단 조건: 완료 조건, 최대 턴 수, 막혔을 때 보고 형식을 적습니다.
예를 들어 “전체 코드 정밀 분석 후 문제 수정”이라는 요청은 아래처럼 바꾸면 훨씬 덜 흔들립니다.
/goal 현재 저장소를 정밀 분석하고 실제 문제를 수정한다.
범위: 애플리케이션 코드와 테스트를 우선 확인한다. 공개 API 변경은 먼저 근거를 남긴다.
검증: 수정 후 npm test와 npm run lint가 모두 0으로 종료되어야 한다.
중단: 더 이상 재현 가능한 이슈가 없거나 12턴을 넘기면 현재 상태, 남은 위험, 실패 명령을 요약한다.여기서 핵심은 “이슈가 없을 때까지”만 쓰지 않는 것입니다. 무엇을 검사할지, 무엇을 실행할지, 언제 멈출지를 같이 적어야 합니다. 그래야 에이전트가 같은 종류의 문제만 반복해서 보거나, 검증 없이 “완료”라고 말하는 일을 줄일 수 있습니다.
초보자가 바로 쓰기 좋은 goal 명령어 12가지
1. 정밀 코드 감사 루프
가장 많이 쓰는 형태입니다. 단순히 “문제 찾아 줘”라고 하지 말고, 검사 관점을 나눠 주는 것이 좋습니다. 빌드 오류, 테스트 실패, 런타임 오류, 논리 오류, edge case, 보안, 성능, dead code, 중복 코드, API 오용을 차례로 보게 하면 탐색이 덜 고착됩니다.
/goal 현재 저장소를 코드 리뷰 관점으로 정밀 감사하고 실제 문제를 수정한다. 매 반복마다 빌드 오류, 테스트 실패, 런타임 가능성, 논리 오류, edge case, 보안, 성능, dead code, 중복 코드, API 오용을 순환 점검한다. 수정 후 테스트와 린트를 실행하고, 새로운 실질적 문제가 발견되지 않을 때 종료한다.Code language: JavaScript (javascript)2. 테스트 커버리지 확장 루프
AI에게 버그를 찾게 하는 것보다 더 좋은 방법은 검증 장치를 만들게 하는 것입니다. 핵심 동작과 위험한 edge case를 찾고, 테스트를 추가하고, 실패하면 원인을 분석하게 합니다.
/goal 현재 테스트를 분석하고 중요한 미검증 동작을 찾는다. 위험도가 높은 edge case부터 테스트를 추가한다. 테스트 실패가 실제 코드 버그라면 구현을 고치고, 테스트가 잘못됐으면 테스트를 수정한다. 핵심 기능에 의미 있는 미검증 영역이 더 이상 발견되지 않고 전체 테스트가 통과할 때 종료한다.3. TODO와 placeholder 제거
AI로 만든 프로젝트에는 겉으로는 완성되어 보여도 내부에 임시 구현이 남는 경우가 있습니다. TODO, FIXME, NotImplemented, stub, mock, 빈 callback, 하드코딩된 임시 데이터를 찾게 하면 출시 전 품질 점검에 도움이 됩니다.
/goal repository 전체에서 TODO, FIXME, NotImplemented, placeholder, stub, mock, 임시 구현, 빈 callback, 하드코딩된 임시 데이터를 찾는다. 각 항목이 실제 요구사항인지 판단하고 필요한 구현을 완료한다. 수정할 때마다 테스트를 실행하고, 실질적인 미완성 구현이 남지 않을 때 종료한다.4. ROADMAP 실제 구현 확인
체크박스가 완료되어 있어도 코드는 다를 수 있습니다. ROADMAP이나 PRD를 읽고, 실제 코드와 비교해 완료, 부분 구현, 미구현, 잘못 구현으로 다시 판정하게 하는 방식입니다.
/goal ROADMAP.md를 읽고 실제 코드와 비교한다. 각 요구사항을 완료, 부분 구현, 미구현, 잘못 구현으로 판정한다. 가장 우선순위가 높은 미완료 항목 하나를 구현하고 테스트한다. 검증된 항목만 ROADMAP에 반영하며, 모든 요구사항이 실제 코드에서 검증될 때까지 반복한다.5. Dependency와 deprecated API 점검
Android나 웹 프로젝트처럼 라이브러리 변화가 빠른 환경에서 유용합니다. 단, 최신 버전이나 마이그레이션 방법은 공식 문서를 확인할 수 있는 환경에서 실행하는 편이 안전합니다.
/goal 프로젝트 dependency와 deprecated API 사용을 조사한다. 각 항목의 공식 migration guide, breaking change, SDK 호환성, 라이선스, 알려진 보안 문제를 확인한다. 안전하게 업데이트 가능한 항목부터 하나씩 수정하고, 각 변경 후 build와 test를 실행한다. 합리적인 최신 안정 상태가 되면 종료한다.6. 보안 감사 후 재감사
일반 코드 리뷰와 보안 리뷰는 관점이 다릅니다. 비밀값 노출, 입력 검증, SQL injection, command injection, path traversal, WebView, intent, exported component, TLS, 파일 접근, 로그의 민감정보 같은 항목을 따로 보게 하는 편이 좋습니다.
/goal 공격자의 관점에서 repository를 보안 감사한다. secret 노출, credential 저장, 입력 검증, SQL injection, command injection, path traversal, WebView, intent, exported component, network security, TLS, 파일 접근, 암호화, 로그의 민감정보를 검사한다. 실질적인 취약점을 발견하면 수정하고 동일 공격 벡터를 다시 검사한다. 새로운 실질적 취약점이 발견되지 않을 때 종료한다.7. 성능 최적화 루프
성능 goal은 조심해야 합니다. “빠르게 만들어 줘”라고 하면 근거 없는 미세 최적화가 늘어날 수 있습니다. 측정하거나 코드상 명확히 입증할 수 있는 병목만 수정하게 해야 합니다.
/goal 성능 문제 가능성을 조사한다. 추측만으로 최적화하지 말고 측정 결과나 코드상 명확하게 입증할 수 있는 병목만 수정한다. CPU, memory, allocation, I/O, network, database, rendering 순서로 검사한다. 변경 전후를 검증하고 회귀가 없을 때만 유지한다. 의미 있는 추가 개선이 발견되지 않을 때 종료한다.8. UI 일관성 감사
앱 화면이 많아질수록 spacing, typography, color, loading, empty state, error state가 조금씩 어긋납니다. UI 일관성은 한 번에 전부 고치기보다 화면을 순회하며 작은 단위로 맞추는 편이 안전합니다.
/goal 모든 화면을 조사하여 UI consistency를 검사한다. spacing, typography, color, component, dialog, navigation, loading, empty state, error state, touch target, accessibility, dark mode 관점에서 문제를 찾는다. 공통 component로 통합 가능한 부분은 통합한다. 수정 후 build와 test를 실행하고, 전체 화면에서 새로운 일관성 문제가 발견되지 않을 때 종료한다.Code language: PHP (php)9. 코드 단순화와 기술부채 제거
기능 구현이 끝난 뒤에는 코드가 불필요하게 복잡해져 있는지 따로 봐야 합니다. AI 개발을 오래 하면 작은 기능 위에 wrapper와 abstraction이 계속 쌓이기 쉽습니다.
/goal 동작을 변경하지 않고 코드베이스를 단순화한다. 중복, 불필요한 abstraction, 과도한 wrapper, dead code, 불필요한 state, 복잡한 control flow, 중복 utility를 찾는다. 한 번에 작은 변경만 수행하고 각 변경 후 build와 test를 실행한다. 추가 단순화가 가독성이나 유지보수성을 악화시키는 시점에서 종료한다.10. 릴리스 준비 체크리스트
릴리스 직전에는 구현보다 확인이 중요합니다. 버전, changelog, 빌드 산출물, 마이그레이션 노트, 롤백 절차, 스토어 등록 자산을 체크리스트로 만들고 하나씩 검증하게 합니다.
/goal release-checklist.md의 모든 항목을 완료한다. 버전, changelog, 빌드, 테스트, 마이그레이션 노트, 롤백 절차, 스토어 등록 자산을 확인한다. 완료한 항목은 증거와 함께 체크하고, 자동으로 확인할 수 없는 항목은 사람 확인 필요로 분리한다. 릴리스 후보 빌드가 생성되면 종료한다.11. CI 실패 자동 복구
PR의 CI가 자주 깨지는 프로젝트라면 실패 로그를 읽고, 원인을 찾고, 수정하고, 다시 테스트하는 루프를 만들 수 있습니다. 다만 외부 상태를 계속 감시해야 하는 작업은 /goal보다 /loop가 더 맞을 때가 있습니다.
/goal 현재 PR의 실패한 CI 로그를 분석하고 원인을 수정한다. 한 번에 하나의 실패 원인만 처리한다. 수정 후 로컬에서 같은 테스트 명령을 실행하고, 가능하면 CI와 동일한 명령으로 검증한다. 모든 필수 체크가 통과하거나 권한과 정보 부족으로 더 진행할 수 없을 때 현재 상태와 다음 조치를 요약한다.12. 설계 대안 비교 후 구현
처음 떠오른 설계가 항상 좋은 답은 아닙니다. 큰 기능을 만들기 전에는 해결책 A, B, C를 비교하고 현재 프로젝트에 가장 맞는 방향을 고른 뒤 구현하게 할 수 있습니다.
/goal 요구사항을 분석하고 최소 3개의 설계 대안을 만든다. 각 대안의 장점, 단점, 구현 비용, 회귀 위험, 테스트 방법을 비교한다. 현재 프로젝트에 가장 적합한 방법을 선택하고 작은 단위로 구현한다. 구현 후 build와 test를 실행하고, 선택하지 않은 대안과 남은 위험을 문서화한 뒤 종료한다.Android 개발에서는 goal을 나눠서 돌리는 편이 낫다
하나의 /goal에 모든 것을 넣고 “완벽하게 만들어 줘”라고 하는 방식은 생각보다 약합니다. 모델이 자기가 잘 찾는 문제만 반복해서 볼 수 있고, 긴 문맥이 쌓이면서 초반 목표가 흐려질 수 있습니다. Android 프로젝트라면 관점을 나눠 여러 goal을 순서대로 실행하는 편이 더 안정적입니다.
- ROADMAP 실제 구현 완료
- 전체 기능 정밀 감사와 버그 수정
- 테스트되지 않은 동작 탐색과 테스트 확장
- 보안 정밀 감사
- Deprecated API와 dependency 점검
- 성능 문제 점검
- UI, UX, 접근성 일관성 점검
- Dead code, 중복, 기술부채 제거
- 최종 회귀 테스트와 전체 재감사
이 방식의 장점은 관점이 리셋된다는 점입니다. 첫 goal은 요구사항을 보고, 두 번째 goal은 실제 동작을 보고, 세 번째 goal은 테스트 빈틈을 봅니다. 마지막에는 가능하면 새 리뷰 관점으로 다시 검사하게 하는 것이 좋습니다. 구현한 에이전트 자신에게 “잘했니?”라고 묻는 것보다, 원래 요구사항과 현재 저장소만 보고 다시 검토하게 하는 편이 더 강합니다.
사용할 때의 주의점
/goal은 강력하지만 만능 자동 조종은 아닙니다. 실제 배포, 결제, 삭제, 대량 발송, 운영 데이터 변경처럼 되돌리기 어려운 작업은 사람의 승인 지점을 남겨야 합니다. “끝날 때까지 알아서 해”보다 “이 명령이 통과할 때까지, 이 파일 범위 안에서, 이 위험은 보고하고 멈춰”가 훨씬 안전합니다.
또 하나의 함정은 검증 없는 반복입니다. 테스트, 빌드, 스크린샷, 벤치마크, 체크리스트처럼 에이전트가 대화에 남길 수 있는 증거가 있어야 /goal의 평가가 의미를 갖습니다. 검증할 수 없는 목표는 먼저 /plan이나 일반 대화로 조건을 좁힌 뒤 goal로 넘기는 편이 좋습니다.
무한 반복도 피해야 합니다. 최대 턴 수나 중단 보고 형식을 적어 두면 작업이 막혔을 때 상태를 잃지 않습니다. “15턴 안에 해결하지 못하면 실패 명령, 시도한 수정, 남은 가설을 요약한다”처럼 적어 두면 다음 사람이 이어받기 쉽습니다.
마무리
goal 명령어의 본질은 에이전트에게 긴 시간을 주는 것이 아니라 완료의 기준을 주는 것입니다. Ralph Loop가 보여 준 “완료라고 말한 뒤에도 다시 확인하는 반복”은 이제 Claude Code와 Codex에서 더 간단한 명령어 형태로 사용할 수 있습니다.
처음부터 거창하게 시작할 필요는 없습니다. 작은 저장소에서 “정밀 분석 후 실제 이슈 수정”을 한 번 돌려 보고, 다음부터는 범위와 검증 명령, 최대 턴 수를 붙여 보세요. 그 순간 /goal은 긴 작업을 대신하는 마법 문장이 아니라, 반복 작업을 검증 가능한 흐름으로 바꾸는 운영 도구가 됩니다.
답글 남기기