Codex /goal로 보는 목표 기반 개발

AI Agent · 2026-05-06 · 4분 읽기

Markdown약 1641 tokens

AI에게 “이 작업 해줘”라고 말하면 모델은 다음 한 턴의 답을 만듭니다. 하지만 “이 목표를 끝낼 때까지 맡아줘”라고 말하면 이야기가 달라집니다. 목표가 오래 유지되는 만큼, 잘못된 목표도 오래 실행될 수 있습니다.

그래서 목표 기반 개발의 핵심은 /goal 명령어 자체가 아닙니다. 중요한 것은 목표를 어떤 계약으로 표현하고, 무엇을 완료로 보며, 어디서 사람에게 되물어야 하는지입니다.

1편에서는 코딩 에이전트를 런타임으로 봐야 하는 이유를 정리했습니다. 이번 2편에서는 그중에서도 Goal Contract를 다룹니다.

핵심 요약

Prompt는 요청이고, Goal은 실행 상태를 가진 목표입니다.
Plan Mode는 “어떻게 할 것인가”에 가깝고, Goal Runtime은 “무엇을 끝낼 것인가”에 가깝습니다.
장시간 작업에는 Objective, Done Criteria, Stop Conditions, Out of Scope, Artifact Contract가 필요합니다.
Goal이 오래 유지될수록 잘못된 목표도 오래 실행될 수 있으므로 중단 조건이 중요합니다.
개발 하네스에서는 goal.md를 1급 runtime state로 다루는 것이 좋습니다.

Prompt, Task, Goal은 다르다

AI 코딩 도구를 사용할 때 가장 흔한 단위는 prompt입니다.

1이 컴포넌트 리팩터링해줘.

조금 더 발전하면 task가 됩니다.

1프로필 수정 폼의 validation을 추가하고 테스트까지 작성해줘.

하지만 goal은 다릅니다.

1사용자 프로필 수정 기능을 안정적으로 제품에 추가한다.

세 문장은 비슷해 보이지만 범위가 다릅니다.

구분	의미	예시
Prompt	지금 모델에게 전달하는 요청	“이 함수 고쳐줘”
Task	수행 가능한 하위 작업	“validation 테스트 작성”
Goal	여러 task를 묶는 완료 목표	“프로필 수정 기능 출시 가능 상태 만들기”

Goal은 단순 문장이 아니라 상태를 가져야 합니다.

1현재 어디까지 진행됐는가?2무엇을 완료로 볼 것인가?3어디서 멈춰야 하는가?4무엇을 결과물로 남길 것인가?

그래서 goal은 프롬프트보다 작업 티켓에 가깝습니다.

Codex /goal이 보여주는 신호

OpenAI Codex CLI 0.128.0 릴리스는 persisted /goal workflow, app-server API, model tool, runtime continuation, TUI의 create/pause/resume/clear 제어를 포함합니다.

이 변화는 단일 요청 처리에서 장시간 목표 실행과 재개를 고려하는 방향을 보여줍니다. OpenAI의 Codex harness 글 역시 Codex core를 agent loop와 thread persistence를 관리하는 runtime으로 설명합니다.

하네스 관점으로 바꾸면 goal은 생성, 실행, 중단, 재개, 검증을 거치는 상태 흐름이 됩니다.

Goal 생성
Plan 생성
Task 분해
실행
중단
승인 요청
재개
검증
산출물 정리

여기서 goal이 단순 텍스트라면 재개가 어렵습니다. 반대로 goal이 구조화되어 있으면 에이전트가 멈췄다가 다시 시작해도 무엇을 끝내야 하는지 복구할 수 있습니다.

1{2  "goalId": "profile-update-20260506",3  "objective": "사용자 프로필 수정 기능을 안정적으로 추가한다",4  "status": "in_progress",5  "doneCriteria": [6    "이름과 소개를 수정할 수 있다",7    "unit test와 e2e test를 통과한다",8    "실패 케이스를 사용자에게 표시한다"9  ],10  "stopConditions": [11    "DB schema 변경 필요 시 승인 요청",12    "인증 로직 변경 필요 시 계획만 제시"13  ],14  "artifacts": [15    "changed-files",16    "test-result",17    "risk-summary"18  ]19}

Plan Mode와 Goal Runtime의 차이

Plan Mode는 유용합니다. 하지만 Plan Mode와 Goal Runtime은 같지 않습니다.

구분	Plan Mode	Goal Runtime
핵심 질문	어떻게 할 것인가?	무엇을 끝낼 것인가?
산출물	계획	지속 상태
실패 대응	계획 수정	상태 복구, 재시도, 승인 요청
완료 기준	단계 수행	Done Criteria 충족
저장 필요성	낮음 또는 중간	높음
하네스 반영	선택 사항	핵심

Plan은 지도입니다. Goal은 작업 티켓입니다.

지도는 길을 보여줍니다. 티켓은 무엇을 완료해야 하는지, 어디까지 했는지, 누가 승인해야 하는지, 어떤 산출물이 필요한지를 남깁니다.

Goal Contract의 기본 구조

실무에서 바로 쓸 수 있는 goal.md 기본형은 heading 문법보다 필드 계약으로 쓰는 편이 안전합니다.

1Goal:2  Objective:3    사용자 프로필 수정 기능을 안정적으로 추가한다.4 5  Context:6    현재 settings/profile 페이지는 조회만 가능하다.7    사용자는 이름과 소개를 수정할 수 있어야 한다.8 9  Done Criteria:10    - 이름과 소개를 수정할 수 있다.11    - 기존 API contract를 깨지 않는다.12    - unit test와 e2e test를 통과한다.13    - 실패 케이스는 toast로 표시한다.14    - 마지막에 변경 파일과 검증 명령을 요약한다.15 16  Stop Conditions:17    - DB schema 변경이 필요하면 먼저 승인 요청한다.18    - 인증 로직 변경이 필요하면 구현 전 계획만 제시한다.19    - 외부 API 비용이 발생하면 중단 후 확인한다.20 21  Out of Scope:22    - 디자인 시스템 전체 변경23    - 인증 플로우 재설계24    - production data 직접 접근25 26  Artifact Contract:27    - 변경 파일 목록28    - 핵심 변경 내용29    - 실행한 검증 명령30    - 실패한 검증과 이유31    - 남은 리스크

이 문서는 길어 보이지만 에이전트에게 매우 중요한 경계입니다. 특히 Stop Conditions가 중요합니다. 목표가 오래 유지될수록 잘못된 판단도 오래 실행될 수 있기 때문입니다.

Done Criteria 작성법

Done Criteria는 완료를 정의하는 문장입니다.

나쁜 예시는 이렇습니다.

1프로필 기능을 잘 구현한다.

좋은 예시는 이렇게 바뀝니다.

1settings/profile에서 이름과 소개를 수정할 수 있다.2저장 실패 시 사용자에게 에러 메시지를 표시한다.3pnpm test profile 명령이 통과한다.4변경 파일과 검증 결과를 마지막에 요약한다.

Done Criteria는 가능하면 관찰 가능해야 합니다.

나쁜 기준	좋은 기준
안정적으로 동작한다	테스트 명령이 통과한다
UX를 개선한다	loading, error, empty state를 표시한다
코드 품질을 높인다	중복 로직을 shared validation으로 분리한다
문서화한다	docs/profile-update.md를 추가한다

완료 기준이 명확하면 에이전트의 종료 조건도 명확해집니다.

Stop Conditions 작성법

Stop Conditions는 에이전트가 멈춰야 하는 조건입니다. 이것은 보안과 운영 안정성에 직접 연결됩니다.

1Stop Conditions:2  - DB migration 파일 생성이 필요하면 먼저 승인 요청3  - auth/session 로직 수정이 필요하면 구현 전 계획만 제시4  - env 파일 접근이 필요하면 중단5  - 외부 유료 API 호출이 필요하면 중단6  - production 배포 명령은 실행 금지

GitHub의 Copilot coding agent 문서는 자율 에이전트가 코드 접근과 push 권한을 가질 때의 리스크와 완화책을 설명합니다. 예를 들어 권한 제한, branch 제한, workflow 승인, human review 같은 계층이 필요합니다.

즉, “프롬프트에 하지 말라고 쓰기”만으로는 충분하지 않습니다. Stop Conditions는 instruction이면서 동시에 permission layer와 연결되어야 합니다.

개발 하네스에 반영하는 방법

개발 하네스에서는 goal을 단순 파일이 아니라 runtime state로 다루는 것이 좋습니다.

가벼운 MVP 구조는 다음과 같습니다.

1.agent-runtime/2  goals/3    profile-update/4      goal.md5      plan.md6      run-ledger.md7      artifacts/8        changed-files.md9        test-result.md10        risk-summary.md

조금 더 발전시키면 SQLite나 JSON state를 함께 사용할 수 있습니다.

1runtime-state.sqlite2- goals3- tasks4- attempts5- artifacts6- approvals7- memory_candidates

처음부터 복잡한 DB가 필요하지는 않습니다. 하지만 최소한 goal과 run ledger는 분리해야 합니다.

파일	역할
`goal.md`	무엇을 끝낼 것인가
`run-ledger.md`	실제로 무엇을 했는가

이 구분이 없으면 에이전트의 계획, 실행, 실패, 결과가 모두 대화에 섞입니다.

체크리스트

Goal을 파일이나 런타임 상태로 만들기 전에 아래 항목을 먼저 확인하면 됩니다.

1[ ] Objective가 한 문장으로 명확한가?2[ ] Done Criteria가 관찰 가능한가?3[ ] Stop Conditions가 위험 작업을 포함하는가?4[ ] Out of Scope가 명확한가?5[ ] 마지막에 남길 Artifact가 정의되어 있는가?6[ ] 재개 시 현재 상태를 복구할 수 있는가?7[ ] 사람이 승인해야 할 작업이 분리되어 있는가?

이번 편에서 가져갈 기준

Goal은 긴 프롬프트가 아니라 작업 티켓입니다. 에이전트에게 목표를 맡기기 전에는 Objective, Done Criteria, Stop Conditions, Artifact Contract를 먼저 분리해야 합니다. 이 네 가지가 없으면 목표 기반 실행은 자동화가 아니라 방치에 가까워집니다.

다음 편

3편에서는 여러 에이전트가 함께 일하는 구조로 넘어갑니다. 주제는 A2A와 MCP입니다. MCP는 도구 접근의 축이고, A2A는 에이전트 간 작업 위임의 축입니다.

시리즈 이어 읽기

1편: 코딩 에이전트는 왜 런타임이 되는가
2편: Codex /goal로 보는 목표 기반 개발
3편: A2A와 MCP로 보는 멀티 에이전트 개발 워크플로우
4편: AI Memory는 RAG가 아니다
5편: 개발 하네스에 적용하는 AI 코딩 에이전트 문서 세트

참고자료

GitHub 계정으로 로그인하면 댓글을 남길 수 있습니다. 댓글은 GitHub Discussions를 통해 운영됩니다.