AI 코딩 에이전트가 복잡한 작업에서 반복 실패하는 문제를, 역할 분리와 게이트 시스템으로 해결한 실전 프레임워크.
문제 인식: AI는 왜 같은 실수를 반복하는가
Claude Code 같은 AI 코딩 에이전트에게 복잡한 작업을 맡기면 특유의 실패 패턴이 나타난다:
- "이미 알고 있다"는 과신 — 리서치를 건너뛰고 기억에 의존해 코드를 작성
- 증상 패치의 반복 — 근본 원인을 분석하지 않고 보이는 에러만 수정
- 범위의 무한 확장 — 한 파일 수정이 다른 파일로 번지고, 원래 의도와 동떨어진 변경이 쌓임
실제로 한 게임 프로젝트에서 UI 전환 시스템을 구현할 때, AI에게 직접 코딩을 맡긴 결과 7회 연속 실패했다. 매번 다른 증상이 나타났지만, 근본 원인은 동일했다 — 분석 없이 코딩부터 시작하는 구조적 문제.
바뀌어야 할 건 AI의 코딩 실력이 아니라, AI를 운용하는 프로세스였다.
핵심 아이디어: 역할 분리
CAOF의 핵심은 단순하다. "분석하는 AI"와 "구현하는 AI"를 분리한다.
| 역할 | 책임 | 하지 않는 것 |
|---|---|---|
| Researcher | 모르는 것을 찾음 (웹 검색 등) | 판단, 구현 |
| Designer | 원인 분석 + 수정 방향 + 성공 기준 정의 | 코드 작성 |
| Implementer | Designer의 방향대로만 구현 | 독자 판단으로 범위 확장 |
| Reviewer | 성공 기준 대비 결과 검증 + 반박 의무 | 무조건 통과 |
왜 이게 작동하는가?
- Designer가 코드를 쓰지 않으므로 분석에 집중할 수 있다
- Implementer가 분석하지 않으므로 계획서 범위 안에서만 움직인다
- Reviewer에게 반박 의무가 있으므로 "돌아가니까 통과"가 불가능하다
이것은 소프트웨어 공학의 오래된 원칙 — 관심사의 분리(Separation of Concerns) — 을 AI 에이전트 운용에 적용한 것이다.
모든 작업에 적용하지 않는다: 트랙 시스템
CAOF의 실용성은 "언제 적용하고 언제 건너뛰는가"에 있다.
| 트랙 | 기준 | 파이프라인 | 예시 |
|---|---|---|---|
| Trivial | 단일 파일, 기존 동작 변경 없음, 되돌리기 < 5분 | Implementer 직행 | 오타 수정, 로그 추가, 상수값 변경 |
| Standard | 2~3 파일 또는 기존 동작 변경, 되돌리기 < 1시간 | Designer 분석 → Implementer | 버그 수정, 기존 기능 수정 |
| Critical | 4+ 파일, 새 시스템, 외부 의존성 | 풀 GATE (7단계) | 새 기능, 아키텍처 변경 |
판단 기준은 코드 줄 수가 아니라 "실패 시 되돌리기 비용"이다.
1줄 변경이라도 물리 엔진 파라미터나 DB 스키마 변경이면 Standard 이상. 100줄 변경이라도 새 유틸 함수 추가면 Trivial일 수 있다.
GATE 파이프라인: Critical 트랙의 7단계
Critical 트랙은 다음 7개 게이트를 순서대로 통과해야 한다. 이전 단계의 산출물이 없으면 다음 단계를 시작할 수 없다.
GATE 0 — 필요성 검증
산출물: "왜 필요한가" 1문장
- "이걸 왜 만들어야 하는가?"
- "기존 시스템으로 해결 가능하지 않은가?"
- 가장 자주 스킵되지만, 가장 비용을 아끼는 단계
GATE 1 — 리서치
산출물: 리서치 요약
- 기술적 불확실성을 웹 검색 등으로 조사
- "이미 알고 있다"는 스킵 사유가 아님 — 목적은 "모르는 것을 모르는 상태" 방지
- 프로젝트 내 검증된 패턴은 코드베이스 탐색으로 대체 가능
GATE 2 — 설계
산출물: 구현 계획서 + 성공 기준
Designer가 파일/함수 수준의 구체적인 계획서를 작성한다:
- 수정 파일: 경로
- 수정 함수: 이름
- 근본 원인: (1줄)
- 수정 전 동작 / 수정 후 기대 동작
- 건드리지 않는 것: (명시)
- 성공 기준: (체크리스트)"건드리지 않는 것"을 명시하는 게 핵심이다. Implementer의 범위 확장을 사전에 차단한다.
GATE 3 — 승인
산출물: 사용자 "승인"
계획 요약을 사용자에게 제시하고, 승인 후에만 구현을 시작한다.
GATE 4 — 구현
산출물: 수정된 코드
- 반드시 Implementer 에이전트가 구현 (Designer가 직접 코딩하지 않음)
- GATE 1 리서치 + GATE 2 계획서를 컨텍스트로 전달
- 구현 중 "모르는 동작" 발견 시 즉시 중단, GATE 1로 복귀
GATE 5 — 검수
산출물: 검수 보고서
- GATE 2의 성공 기준 대비 결과를 대조
- 교차 모델 검수 권장 — 같은 모델의 자기 검수는 자기 동의 편향(self-agreement bias) 위험
- Reviewer는 반박 의무가 있음
GATE 6 — 테스트
산출물: 사용자 테스트 결과
- 사용자가 직접 테스트
- 버그 발견 시 버그 수정 파이프라인(Standard 트랙) 적용
버그 수정: Designer를 거치는 이유
Implementer에게 직접 버그를 넘기지 않는다.
버그 증상 + 로그
↓
Designer: 근본 원인 분석 + 수정 방향 + 영향 범위
↓
Implementer: 수정 방향대로만 구현
↓
검수 + 테스트Implementer는 코딩 전문이지 진단 전문이 아니다. 원인 분석 없이 넘기면 증상만 패치하게 된다. 이것이 "7회 연속 실패"의 직접적 원인이었다.
실패 에스컬레이션: 3회면 멈춘다
1회 실패: Implementer가 원인 분석 후 재시도
2회 실패: Designer가 원인 재분석
→ 구현 문제: 다른 접근법으로 재구현
→ 설계 문제: GATE 2로 롤백
3회 실패: 즉시 중단 + 사용자에게 보고
→ 기능 범위 축소 또는 대안 기능으로 전환"접근 전환"의 구체적 행동:
- 추가 리서치 (새 키워드, 다른 기술 스택)
- Designer 교체 (다른 모델에 위임)
- 기능 범위를 MVP로 축소
- 최소 재현 테스트로 가설 검증
중요한 건 "빨리 해", "바로 구현해"는 게이트 스킵 승인이 아니라는 점이다. "N단계 스킵 승인"이라는 명시적 문구만 허용한다.
에이전트 설계: 극단적 페르소나가 역할 분리를 만든다
Claude Code의 커스텀 에이전트(.claude/agents/)를 활용해 역할을 구현한다.
에이전트 카드 구조
---
name: [에이전트 이름]
description: [한 줄 설명]
model: [opus/sonnet — Designer는 opus, Implementer는 sonnet 권장]
tools: [사용 가능한 도구]
---
# 페르소나
[2~3줄로 사고방식과 가치관. 극단적일수록 좋다.]
## 사고 원칙
1. [최우선 원칙]
2. [두 번째 원칙]
## 범위 제약
- 이 에이전트가 하는 것
- 이 에이전트가 하지 않는 것 ← 이게 더 중요
## 과거 교훈
- [실패에서 학습한 내용 — 날짜와 함께]4가지 설계 원칙
- 페르소나가 극단적이어야 역할 분리가 작동한다 — "꼼꼼한 개발자"는 약하다. "버그를 못 찾으면 잠을 못 자는 15년차 시니어"는 강하다.
- "하지 않는 것"이 "하는 것"보다 중요하다 — Designer가 코드를 쓰기 시작하면 역할 분리가 무너진다.
- 모델 선택: Designer = Opus, Implementer = Sonnet — Designer는 깊은 분석이 필요하고, Implementer는 빠른 실행이 필요하다.
- 교훈 섹션이 에이전트를 성장시킨다 — 프로젝트에서 발견한 실수를 에이전트 카드에 축적하면, 같은 실수를 반복하지 않는 구조가 된다.
모델 선택과 교차 검증
Designer = Opus, Implementer = Sonnet
| 모델 | 강점 | CAOF 역할 |
|---|---|---|
| Opus | 깊은 분석, 복잡한 추론 | Designer, Reviewer |
| Sonnet | 빠른 코드 생성, 실행력 | Implementer |
| Haiku | 초고속, 저비용 | 보조 검수 |
교차 모델 검수의 필요성
같은 모델이 자기 코드를 검수하면 자기 동의 편향(self-agreement bias)이 발생한다. 자신이 작성한 로직을 "합리적"으로 판단하는 경향이 있어, 실제 결함을 놓친다.
CAOF에서는 구현과 검수에 서로 다른 모델을 사용하는 교차 검증을 권장한다:
- Sonnet이 구현 → Opus + Gemini가 검수
- 4모델 병렬 검수 (Gemini + Opus + Sonnet + Haiku)로 다각도 리뷰
실전 검증 데이터
| Phase | 프레임워크 | 시도 횟수 | 결과 |
|---|---|---|---|
| Phase 0 | 없음 (AI 직접 코딩) | 7회 | 반복 실패 후 프레임워크 도입 |
| Phase 1 | CAOF 적용 | 2회 | 성공 (1회 버그 → Designer 분석 → 수정) |
| Phase 2 | CAOF 적용 | 1회 | 즉시 성공 |
| Phase 3 | CAOF 적용 | 1회 | 즉시 성공 |
| Phase 4 | CAOF 적용 | 1회 | 즉시 성공 |
Phase 0에서 7회 실패하던 작업이, CAOF 도입 후 Phase 1~4에서 각각 1~2회만에 성공했다. 변한 건 AI 모델이 아니라 프로세스다.
새 프로젝트에 적용하는 법
Step 1: 프로젝트의 실패 비용 분석
- 이 프로젝트에서 가장 비싼 실수는 무엇인가?
- 실수 후 되돌리기에 얼마나 걸리는가?
- 과거에 같은 실수를 반복한 적이 있는가?
Step 2: Designer/Implementer 역할 결정
| 질문 | Designer | Implementer |
|---|---|---|
| "왜 이렇게 해야 하는가?" | ○ | × |
| "이 코드를 어떻게 작성하는가?" | × | ○ |
| "이 버그의 원인은?" | ○ | × |
| "계획서대로 코드를 작성하라" | × | ○ |
Step 3: 에이전트 카드 작성
.claude/agents/ 디렉토리에 Designer와 Implementer 에이전트를 생성한다.
Step 4: CLAUDE.md에 CAOF 규칙 삽입
트랙 분류 기준, 라우팅 트리, 실패 에스컬레이션 규칙을 프로젝트 설정에 추가한다.
Step 5: 첫 기능으로 캘리브레이션
첫 Critical 기능을 풀 GATE로 실행하면서 병목을 측정하고, 5개 기능 완료 후 회고로 프레임워크를 조정한다.
프로젝트 유형별 적용 예시
| 프로젝트 유형 | Designer | Implementer | 비고 |
|---|---|---|---|
| 게임 (Unity/Godot) | 게임 설계 에이전트 (Opus) | 엔진 코더 에이전트 (Sonnet) | 전용 에이전트 쌍 |
| 웹앱 (React/Next.js) | 메인 Claude 또는 아키텍트 에이전트 | 프론트엔드 코더 에이전트 | Designer 겸임 가능 |
| 모바일 앱 (Flutter) | 설계 에이전트 공유 가능 | Flutter 코더 에이전트 | Designer 재사용 |
| 데이터 파이프라인 | 데이터 분석 에이전트 | 데이터 엔지니어 에이전트 | 도메인별 분리 |
| 인프라/DevOps | 인프라 플래너 | 인프라 실행자 | 되돌리기 비용 높음 → Critical 비율 높음 |
Designer가 없으면 메인 Claude가 겸임하되, 교차 검증으로 자기 동의 편향을 보완한다.
핵심 교훈
- AI의 코딩 실력은 충분하다. 부족한 건 프로세스다. — 같은 모델이 프로세스만 바꿔도 성공률이 극적으로 올라간다.
- 역할 분리의 핵심은 "하지 않는 것"을 정의하는 것이다. — Designer가 코드를 쓰는 순간 프레임워크가 무너진다.
- 되돌리기 비용이 트랙을 결정한다. — 줄 수, 파일 수는 보조 지표일 뿐이다.
- "빨리 해"는 게이트 스킵이 아니다. — 급할수록 프로세스를 지켜야 한다. 7회 실패와 1회 성공 중 어느 쪽이 더 빠른가.
- 에이전트는 경험으로 성장한다. — 실패 교훈을 에이전트 카드에 축적하면, 프로젝트가 진행될수록 에이전트가 똑똑해진다.
- 자기 동의 편향은 실재한다. — 반드시 교차 모델 검수를 적용해야 한다.
CAOF는 Claude Code의 커스텀 에이전트 시스템 위에 구축된 실전 프레임워크입니다. 2026년 3월, 실제 프로젝트에서의 반복 실패를 계기로 설계되었으며, 도입 후 구현 성공률이 극적으로 개선되었습니다.
