Codex Agent를 안정적으로 활용하기 위한 AGENTS.md 기반 작업 흐름

핵심 개념

Codex 같은 coding agent를 안정적으로 활용하려면 단순히 “코드를 잘 작성해줘”라고 지시하는 방식보다, agent가 따라야 할 작업 프로토콜을 명확하게 정의하는 것이 중요하다.

핵심은 다음과 같다.

사람 = 제품 방향, 아키텍처 판단, 승인, 책임
Agent = 구조 조사, 계획 작성, 반복 구현, 검증, 요약

agent에게 처음부터 구현을 맡기면 코드가 빠르게 생성되지만, 다음 문제가 생기기 쉽다.

• 기존 architecture를 무시한 변경
• 불필요한 abstraction 추가
• dependency 남발
• 임시 error handling
• debug print, TODO, dead code 누적
• unrelated file 변경
• 검증되지 않은 performance optimization
• 큰 diff로 인한 rollback 난이도 증가

따라서 agent 활용의 목표는 “한 번에 많은 코드를 생성하는 것”이 아니라, 작은 단위로 이해하고, 계획하고, 검증하면서 프로젝트 방향을 유지하는 것이다.

---

기본 mental model

agent는 독립적인 개발자라기보다는, 규칙을 잘 주면 빠르게 움직이는 작업자에 가깝다.

역할	사람이 담당	Agent가 담당
방향성	기능 우선순위, architecture 방향, trade-off 결정	기존 구조 조사, 선택지 정리
설계	plan 승인, dependency/API/schema 변경 승인	research.md, plan.md 초안 작성
구현	범위 통제, diff review	승인된 최소 기능 단위 구현
검증	결과 판단, merge 여부 결정	test/typecheck/lint/build 실행
rollback	되돌릴 기준 결정	변경 파일 요약, 복구 제안

중요한 기준은 다음 한 문장으로 요약된다.

Agent에게 코드를 잘 쓰게 시키려 하지 말고, 무엇을 쓸지 먼저 문서로 확정하게 만든 뒤 승인된 최소 단위만 구현하게 해야 한다.

---

바로 구현시키면 생기는 문제

나쁜 흐름은 다음과 같다.

사용자: 이 기능 만들어줘
Agent: 여러 파일을 한꺼번에 수정
사용자: 에러남
Agent: 임시 패치
사용자: 또 다른 에러남
Agent: validation이나 test를 우회
결과: 돌아가긴 하지만 구조가 망가짐

이 패턴의 진짜 문제는 syntax error가 아니라 기술부채가 조용히 쌓이는 것이다.

주의할 점은 다음과 같다.

• agent는 “작동하게 만들기”에 집중하다가 구조적 일관성을 깨뜨릴 수 있다.
• 큰 요청을 주면 agent가 기능 구현, refactor, cleanup, formatting을 섞을 수 있다.
• 실패한 diff 위에 계속 patch하면 코드가 점점 불안정해질 수 있다.
• 테스트가 없는 프로젝트에서는 agent가 “검증 완료”라고 착각할 수 있다.
• performance 개선 요청은 근거 없는 cache, concurrency, batching 추가로 이어질 수 있다.

---

권장 전체 workflow

agent 작업은 다음 흐름으로 운영하는 것이 안전하다.

0. 프로젝트 방향성 문서화
1. Agent에게 코드베이스 research만 시킴
2. Agent에게 plan.md만 작성시킴
3. 사람이 plan.md 검토 및 수정 지시
4. Agent가 plan.md 수정
5. 사람이 구현 승인
6. Agent가 최소 기능 단위로 구현
7. Agent가 가장 좁은 검증 실행
8. Agent가 local commit 생성
9. 사람이 diff review
10. 다음 ticket으로 이동

이때 가장 중요한 제약은 다음이다.

계획이 승인되기 전까지 코드를 수정하지 않는다.

---

AGENTS.md의 역할

AGENTS.md는 Codex에게 프로젝트에서 따라야 할 작업 방식, coding convention, test command, 금지 사항을 알려주는 instruction file이다.

권장 구조는 다음과 같다.

~/.codex/AGENTS.md
  → 모든 프로젝트에 적용되는 전역 작업 원칙

repo/AGENTS.md
  → 특정 프로젝트의 구조, 명령어, architecture boundary, 금지 패턴

repo/docs/agent/research.md
  → agent가 조사한 현재 코드 구조와 흐름

repo/docs/agent/plan.md
  → 구현 전 승인받아야 하는 작업 계획

repo/docs/agent/verification.md
  → 실행한 test, lint, typecheck, build, dry-run 결과

전역 AGENTS.md에는 공통 원칙만 두는 것이 좋다.

• 구조 파악 후 수정
• 최소 기능 단위로 작업
• spec-first workflow
• TDD when practical
• speculative optimization 금지
• broad refactor 금지
• 위험 명령 금지
• local commit 정책
• 보안 정보 노출 금지

프로젝트별 AGENTS.md에는 해당 repo에만 적용되는 내용을 둔다.

• package manager
• test/lint/typecheck/build command
• 주요 directory 구조
• architecture boundary
• 수정하면 안 되는 public API
• deployment 주의사항
• 금지 dependency
• project direction

---

Spec-first와 TDD의 관계

agent에게 “항상 TDD로 해라”라고 강제하는 것은 현실적으로 좋지 않다.

더 안정적인 원칙은 다음이다.

Spec-first by default.
Test-first when practical.
Do not invent fake tests.
Use the narrowest meaningful verification.

즉, 모든 작업은 먼저 작은 spec을 작성하고, 테스트가 유효한 경우에만 TDD를 우선 적용한다.

방식	적용 기준	주의할 점
Spec-first	거의 모든 non-trivial 작업	구현 전에 expected behavior를 먼저 정의
TDD	business logic, API, parser, data transformation, bug fix	test infrastructure가 있을 때 효과적
Typecheck/Lint	TypeScript, Python, frontend, backend 작업	test가 없을 때 최소 검증으로 유용
Build	integration 영향이 있을 때	모든 작은 수정마다 full build부터 돌릴 필요는 없음
Dry-run/Diff	Kubernetes, Docker, Helm, CI/CD, infra 작업	mutation 전 read-only 검증 우선
Static inspection	매우 작은 변경 또는 실행 환경 없음	검증하지 못한 부분을 명시해야 함

작은 spec 예시

## Expected behavior

- 로그인 실패 시 기존 API response 구조는 유지한다.
- UI에는 사용자 친화적인 error message를 표시한다.
- network error와 invalid credential error를 구분한다.
- auth/session layer는 수정하지 않는다.
- 변경 범위는 login form message mapping으로 제한한다.

이런 spec이 있으면 agent가 불필요하게 server authentication layer까지 건드리는 일을 줄일 수 있다.

---

최소 기능 단위로 쪼개기

agent에게 큰 요청을 줄 때는 반드시 phase를 나누는 것이 좋다.

좋은 최소 기능 단위는 다음과 같다.

• one bug fix
• one UI behavior
• one endpoint
• one component
• one command
• one testable path
• one documentation correction
• one isolated refactor explicitly requested by the user

나쁜 작업 단위는 다음과 같다.

• “전체 구조 개선”
• “코드 품질 전반적으로 향상”
• “성능 최적화 전부 해줘”
• “UI를 깔끔하게 다시 정리”
• “테스트도 추가하고 리팩토링도 해줘”
• “일단 되는 방향으로 고쳐줘”

큰 작업은 다음처럼 쪼개는 것이 안전하다.

Phase 1: 현재 구조 research
Phase 2: plan.md 작성
Phase 3: 실패 재현 test 추가
Phase 4: 최소 수정으로 bug fix
Phase 5: 관련 verification 실행
Phase 6: 필요한 경우에만 local cleanup

---

research.md와 plan.md 중심 운영

긴 chat context에 의존하는 것보다 repo 안에 문서로 남기는 것이 더 안정적이다.

권장 directory는 다음과 같다.

docs/agent/
  research.md
  plan.md
  implementation-log.md
  verification.md

research.md

research.md는 구현 전 코드베이스를 조사한 결과다.

# Research

## Project structure

## Relevant files

## Current flow

## Existing patterns

## Constraints

## Risks

## Open questions

plan.md

plan.md는 사람이 승인해야 하는 구현 계획이다.

# Implementation Plan

## Goal

## Expected behavior

## Non-goals

## Files to change

## Step-by-step plan

## Tests / verification

## Risks

## Rollback plan

verification.md

verification.md는 작업 후 실행한 검증 결과다.

# Verification

## Commands run

## Results

## Manual checks

## Unverified parts

이 방식의 장점은 다음과 같다.

• session이 끊겨도 맥락이 보존된다.
• 다른 agent가 이어받기 쉽다.
• 계획 승인 전 구현을 막기 쉽다.
• 변경 범위가 명확해진다.
• rollback 기준을 잡기 쉽다.

---

성능 개선은 측정 기반으로만

performance improvement는 agent가 과하게 코드를 바꾸기 쉬운 영역이다.

성능 작업은 다음 순서로 제한하는 것이 좋다.

1. suspected bottleneck 식별
2. benchmark/profile/log/reproduction path 확보
3. baseline 기록
4. one focused change
5. baseline과 비교
6. trade-off 요약

agent에게 금지해야 할 speculative optimization은 다음과 같다.

• 근거 없는 caching
• 불필요한 concurrency
• 과한 memoization
• premature batching
• background job 도입
• queue 도입
• lazy loading 남발
• database index 임의 추가
• rendering behavior 변경
• algorithm 변경 후 검증 생략

성능 개선 요청은 다음처럼 주는 것이 좋다.

먼저 현재 병목 후보를 조사해줘.
아직 코드는 수정하지 마.
측정 가능한 baseline을 만들 수 있는지 확인하고,
가능한 경우 benchmark 또는 log 기반 plan.md를 작성해줘.

---

cleanup과 dead code 제거 기준

“쓰레기 코드 정리”는 좋은 목표지만, agent에게 broad cleanup을 맡기면 정상 코드까지 삭제될 수 있다.

삭제 전에는 최소 하나를 확인해야 한다.

삭제 후보	확인 기준
unreachable code	실제 call path에서 도달 불가
unused code	reference search 결과 사용처 없음
duplicated logic	기존 helper로 대체 가능
commented-out code	현재 동작에 영향 없음
debug print	임시 출력임이 명확함
obsolete docs	현재 코드와 모순됨
generated artifact	commit 대상이 아님

주의할 점:

• public API, exported function, migration, script, test는 함부로 삭제하지 않는다.
• feature work와 broad cleanup을 섞지 않는다.
• cleanup은 behavior-preserving이어야 한다.
• 삭제한 이유와 안전성을 마지막에 요약한다.

---

위험 명령은 rules 또는 명시적 확인으로 막기

AGENTS.md에 금지 사항을 쓰는 것도 중요하지만, destructive command는 별도 rules나 명시적 확인 절차로 막는 것이 안전하다.

위험 명령 예시는 다음과 같다.

rm -rf
git reset --hard
git clean
git push
git push --force
docker system prune
docker volume prune
kubectl delete
kubectl apply
helm uninstall
helm upgrade
database drop
database truncate
destructive migration

기본 원칙은 다음이다.

inspection before mutation

즉, Kubernetes, Docker, Helm, database, CI/CD, registry 작업은 먼저 다음과 같은 명령을 우선한다.

영역	mutation 전 우선 명령
Kubernetes	kubectl get, kubectl describe, kubectl logs, kubectl diff, --dry-run
Helm	helm template, helm diff, helm lint
Docker	docker ps, docker images, docker compose config, docker logs
Database	SELECT, EXPLAIN, migration dry-run
Git	git status, git diff, git log --oneline

---

local commit 기반 rollback 전략

매 작업마다 commit을 남기면 rollback이 쉬워진다.

다만 “무조건 commit”보다는 다음 정책이 좋다.

검증이 끝난 최소 기능 단위마다 local commit을 남긴다.
push는 하지 않는다.

권장 흐름은 다음과 같다.

git checkout -b agent/task-name

이후 agent에게 다음처럼 요청한다.

작업은 최소 기능 단위로 진행해줘.
계획 승인 전에는 구현하지 마.
구현 후 관련 검증을 실행하고,
검증이 통과하면 local commit을 만들어줘.
push는 절대 하지 마.

좋은 commit 단위는 다음과 같다.

- 로그인 에러 메시지 개선
- 검색 API timeout 처리 추가
- ProductCard hover 스타일 수정
- Nexus upload 중복 GAV 처리 로직 추가
- Kubernetes manifest dry-run 검증 스크립트 추가

나쁜 commit 단위는 다음과 같다.

- fix
- update
- 이것저것 수정
- 리팩토링 + 기능 변경 + 포맷팅 혼합

rollback 방식

작업 branch를 쓰면 reset --hard보다 안전하게 되돌릴 수 있다.

git checkout main
git branch -D agent/task-name

이미 main에 commit이 들어갔다면 다음 방식 중 하나를 선택한다.

git revert <commit>

또는 아직 push 전이고 local에서만 되돌릴 때:

git reset --hard <good_commit>

git reset --hard는 user change를 날릴 수 있으므로, agent가 임의로 실행하지 않도록 해야 한다.

---

agent에게 줄 수 있는 실전 prompt 패턴

1. research 전용

이 repo의 구조를 먼저 깊게 조사해줘.

아직 코드는 수정하지 마.
관련 파일을 읽고 다음 내용을 docs/agent/research.md에 정리해줘.

- 프로젝트 구조
- 주요 entry point
- 이 기능과 관련된 파일
- 현재 데이터 흐름
- 기존 패턴
- 테스트/빌드/실행 명령
- 위험 요소
- 아직 불확실한 점

구현 계획은 아직 작성하지 말고, research만 해줘.

2. plan 작성

research.md를 기반으로 plan.md를 작성해줘.

아직 코드는 수정하지 마.

plan.md에는 다음을 포함해줘.

- 목표
- 기대 동작
- 바꾸지 않을 것
- 변경 파일 목록
- 단계별 구현 계획
- 테스트 또는 검증 방법
- 위험 요소
- rollback 방법

작업은 최소 기능 단위로 쪼개고, Phase 1만 구현 가능한 수준으로 계획해줘.

3. plan 수정

plan.md에 내가 남긴 피드백을 반영해서 계획을 수정해줘.

아직 구현하지 마.
범위를 더 줄이고, 기존 구조를 최대한 유지하는 방향으로 다시 작성해줘.

4. 구현 승인

plan.md의 Phase 1 구현을 승인한다.

Phase 1만 구현해줘.
계획에 없는 파일은 수정하지 마.
구현 후 가장 좁은 관련 테스트/typecheck/lint를 실행해줘.
검증이 통과하면 local commit을 만들어줘.
push는 하지 마.
마지막에 변경 파일, 변경 이유, 검증 결과, 남은 리스크를 요약해줘.

5. 실패한 방향 중단

지금 방향이 잘못된 것 같다.

추가 구현하지 마.
현재 변경된 파일과 문제점을 먼저 요약해줘.
그다음 되돌릴 부분과 유지할 부분을 제안해줘.
내 승인 전에는 git reset, 삭제, 강제 변경을 실행하지 마.

---

전역 AGENTS.md에 들어갈 핵심 정책

전역 ~/.codex/AGENTS.md에는 다음 원칙을 넣는 것이 좋다.

# Global Codex Instructions

## Primary objective

You are working inside existing codebases.

Your job is to make the smallest correct change that satisfies the user's request while preserving the existing architecture, style, behavior, and intent.

Prefer safe, boring, maintainable code over clever code.

Do not optimize, refactor, rename, reformat, reorganize, modernize, or redesign unrelated code unless the user explicitly asks for it.

Improve the project by making small, verified, directionally consistent changes.

Do not create new architecture, abstractions, dependencies, or performance mechanisms unless the need is proven.

추가로 다음 정책을 넣는다.

정책	목적
First-run repository workflow	처음 보는 repo에서 바로 수정하지 않게 함
Project direction files	README, ARCHITECTURE, ROADMAP, AGENTS.md 우선 확인
Minimal functional units	큰 작업을 작은 phase로 쪼갬
Spec-first and test-aware development	구현 전 expected behavior 정의
Performance improvement policy	측정 없는 optimization 방지
Cleanup policy	정상 코드 삭제 방지
Commit policy	검증된 최소 기능 단위마다 local commit
Dangerous command policy	destructive command 차단
Security and privacy	secret, token, private hostname 노출 방지
Self-review checklist	diff 품질 점검

---

프로젝트별 AGENTS.md 예시

전역 지침과 별도로 repo root에는 프로젝트별 지침을 둔다.

# Project Instructions

## Project direction

This project should evolve incrementally.
Do not replace the current architecture.
Do not introduce new frameworks or major dependencies without approval.

## Required workflow

For non-trivial work:

1. create or update docs/agent/research.md
2. create or update docs/agent/plan.md
3. wait for user approval before implementation
4. implement only the approved phase
5. update docs/agent/verification.md
6. create a local commit after successful verification if the user requested commit-based workflow

## Commands

Use the existing package manager.

Before finishing, run the narrowest relevant command among:

- lint:
- typecheck:
- test:
- build:

If a command is unknown, inspect package scripts, Makefile, task files, or CI configuration first.

## Architecture boundaries

Keep UI, API, persistence, and infrastructure concerns separated according to the existing project structure.

Do not move code across layers unless explicitly requested.

Do not add global state, background workers, queues, caches, or new services unless the need is clear and approved.

## Performance policy

Performance changes require a baseline and comparison when practical.

Do not add caching or concurrency speculatively.

## Cleanup policy

Cleanup must be behavior-preserving.
Do not mix broad cleanup with feature work.

---

UI 작업에서의 활용 방식

UI 작업은 설명만으로는 오해가 생기기 쉽다.

가능하면 다음 정보를 함께 제공한다.

• 현재 screenshot
• 원하는 screenshot 또는 reference
• 바꾸어야 할 부분
• 유지해야 할 부분
• responsive behavior
• hover/focus/active state
• 색상, spacing, typography constraint
• 수정 금지 파일 또는 layer

좋은 요청 예시는 다음과 같다.

현재 화면 스크린샷은 A이고, 원하는 화면은 B다.

수정 목표:
- 검색창은 상단 중앙 유지
- 버튼 높이는 그대로
- hover 색상만 변경
- layout 구조는 변경하지 말 것

먼저 관련 component를 찾아서 plan.md를 작성해줘.
아직 구현하지 마.

UI 작업에서도 핵심은 같다.

구조 파악 → plan → 승인 → 최소 수정 → visual/behavior 검증

---

잘못된 방향으로 갔을 때의 처리

agent가 잘못된 방향으로 수정했다면, 그 위에 계속 patch를 쌓지 않는 것이 좋다.

권장 절차는 다음과 같다.

1. 추가 구현 중단
2. 변경 파일 목록 확인
3. diff 문제점 요약
4. 되돌릴 부분과 유지할 부분 분리
5. 사람 승인 후 rollback
6. plan.md를 더 작은 범위로 재작성

잘못된 방향에서 사용할 prompt는 다음과 같다.

현재 변경 방향이 잘못됐다.
이 diff를 기준으로 추가 patch하지 마.

먼저 변경된 파일과 문제점을 요약해줘.
그다음 안전하게 되돌릴 수 있는 범위를 제안해줘.
내 승인 전에는 reset이나 삭제 명령을 실행하지 마.

---

최종 운영 전략

실전에서는 다음 조합이 가장 안정적이다.

~/.codex/AGENTS.md
  → 전역 작업 원칙

repo/AGENTS.md
  → 프로젝트 구조, 명령어, architecture boundary

docs/agent/research.md
  → 현재 코드베이스 조사 결과

docs/agent/plan.md
  → 구현 전 승인 문서

docs/agent/verification.md
  → 검증 결과

local commit
  → 검증된 최소 기능 단위 checkpoint

branch
  → 실패 시 쉬운 폐기 단위

권장 작업 흐름은 다음이다.

git checkout -b agent/task-name
→ research.md 작성
→ plan.md 작성
→ 사람 검토
→ plan.md 수정
→ Phase 1 승인
→ 최소 구현
→ test/typecheck/lint/build/dry-run
→ self-review
→ local commit
→ diff review
→ merge 또는 branch 폐기

---

요약

agent 활용의 핵심은 속도가 아니라 통제 가능한 반복성이다.

정리하면 다음과 같다.

• agent에게 바로 구현을 맡기지 않는다.
• 처음 보는 repo에서는 구조 파악부터 시킨다.
• non-trivial 작업은 research.md와 plan.md를 먼저 만든다.
• plan.md 승인 전에는 코드를 수정하지 않는다.
• 작업은 최소 기능 단위로 쪼갠다.
• 기본은 spec-first, 가능한 경우 TDD를 적용한다.
• performance 개선은 측정 기반으로만 한다.
• cleanup은 behavior-preserving으로 제한한다.
• 위험 명령은 confirmation 또는 rules로 막는다.
• 검증된 최소 기능 단위마다 local commit을 남긴다.
• push는 agent에게 맡기지 않는다.
• 실패한 diff 위에 계속 patch하지 말고, 되돌린 뒤 더 작은 계획으로 재시작한다.

가장 중요한 문장은 다음이다.

작은 spec, 작은 plan, 작은 patch, 작은 verification, 작은 commit.