AI 에이전트로 SDLC 전체를 자동화하는 법: 오케스트레이션 패턴과 실행 명령 모음

이 가이드는 중대형 솔루션 프로젝트의 PM·아키텍트·시니어 개발자를 대상으로, 사람의 개입 없이 AI 에이전트만으로 기획→분석→설계→구현→테스트→배포까지 완성된 솔루션을 만드는 방법을 다룬다. 기준은 2026년 3월이고, 현재 도구는 Claude Code·OpenAI Codex CLI·Gemini CLI, 여기에 오케스트레이션 레이어로 oh-my-claudecode(OMC)와 OpenClaw/NanoClaw를 더한다.

2026년 3월 기준, 도구별로 SDLC 어디를 맡기나

각 도구는 성숙도와 강점이 다르고, 이 차이가 SDLC 단계별 배치를 결정한다.

도구	모델	SWE-Bench	핵심 강점	SDLC 최적 단계
Claude Code	Opus 4.6 / Sonnet 4.6	80.9% (Tier 1)	대형 코드베이스 이해, 멀티파일 편집, 멀티에이전트 오케스트레이션	전 단계 (오케스트레이터 역할)
OpenAI Codex CLI	GPT-5.3-Codex	~75%	독립 태스크 병렬 처리, 격리된 worktree, 클라우드 샌드박스	구현 (병렬 워커)
Gemini CLI	Gemini 2.5 Pro	~70%	1M 토큰 컨텍스트, 오픈소스, Plan Mode, 무료	분석/설계 (초기 탐색)
oh-my-claudecode	라우팅 레이어	-	32개 특화 에이전트, 40+ 스킬, 자동 모델 라우팅	오케스트레이션 레이어
OpenClaw	플랫폼	-	메시징 기반 자율 에이전트 UI (Telegram/Slack)	운영/배포 알림
NanoClaw	Claude Agent SDK	-	컨테이너 격리, 경량, 감사 가능, MIT	보안이 필요한 자율 배포

이걸 SDLC 단계별로 조합하면 다음과 같은 흐름이 나온다.

기획/요구사항  →  Claude Code (analyst/opus)
분석/설계      →  Claude Code (architect/opus) + Gemini CLI (1M 컨텍스트 탐색)
구현           →  Claude Code (executor/sonnet) + Codex CLI (병렬 워커) + Gemini CLI (보조)
테스트         →  Claude Code (test-engineer/sonnet + qa-tester/sonnet)
코드리뷰       →  Claude Code (code-reviewer/opus + security-reviewer/sonnet)
배포           →  Claude Code (executor/sonnet + git-master/sonnet)
운영 알림      →  NanoClaw (Telegram/Slack 연동)

AI 소프트웨어 팩토리: 오케스트레이터와 아티팩트 저장소

전체 시스템은 마스터 오케스트레이터가 페이즈 에이전트를 분기시키고, 그 결과를 공유 아티팩트 저장소에 쌓는 구조로 짜인다.

┌─────────────────────────────────────────────────────────────────┐
│                    MASTER ORCHESTRATOR                           │
│              Claude Code + OMC (ralph/autopilot)                │
└────────────────────────┬────────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  PHASE AGENT │  │  PHASE AGENT │  │  PHASE AGENT │
│  (OMC 특화)  │  │  (OMC 특화)  │  │  (OMC 특화)  │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                     SHARED ARTIFACT STORE                        │
│     .omc/artifacts/{phase}/{id}.{format}                        │
│     .omc/state/sessions/{session-id}/pipeline.json              │
│     .omc/state/sessions/{session-id}/decisions.json             │
└─────────────────────────────────────────────────────────────────┘
       │                 │                 │
       ▼                 ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Codex CLI   │  │  Gemini CLI  │  │   NanoClaw   │
│  (병렬 구현) │  │ (분석 보조)  │  │ (배포 알림)  │
└──────────────┘  └──────────────┘  └──────────────┘

단계별 입출력은 아티팩트 흐름으로 연결된다. CONCEPT.md가 analyst를 거쳐 PRD.md가 되고, architect가 이를 ARCHITECTURE.md·API_SPEC.yaml·DB_SCHEMA.sql로 구체화하며, planner가 TASK_GRAPH.json으로 태스크를 쪼갠 뒤 critic이 승인하면 APPROVED_PLAN.json이 나온다. 여기서부터 executor·codex-cli·gemini-cli가 병렬로 소스 코드를 만들고, test-engineer가 테스트를, qa-tester가 실행 결과를 TEST_REPORT.json으로 남긴다. 이어 code-reviewer와 security-reviewer가 REVIEW_REPORT.md를 작성하고 git-master가 PR을 올려 CI/CD·배포로 이어진다.

[CONCEPT.md]
     │ analyst(opus)
     ▼
[PRD.md]  ← 모든 API 엔드포인트, 데이터 모델, 사용자 흐름 명시
     │ architect(opus)
     ▼
[ARCHITECTURE.md + API_SPEC.yaml + DB_SCHEMA.sql]
     │ planner(opus)
     ▼
[TASK_GRAPH.json]  ← 의존성 있는 순서화된 태스크 목록
     │ critic(opus) → 승인
     ▼
[APPROVED_PLAN.json]
     │ executor(sonnet) × N 병렬
     │ + codex-cli × M 병렬
     │ + gemini-cli × K 병렬
     ▼
[src/**/*.{ts,py,go}]
     │ test-engineer(sonnet)
     ▼
[tests/**/*.spec.{ts,py}]
     │ qa-tester(sonnet) → 테스트 실행
     ▼
[TEST_REPORT.json]  ← pass/fail, 커버리지
     │ code-reviewer(opus) + security-reviewer(sonnet)
     ▼
[REVIEW_REPORT.md]
     │ git-master(sonnet)
     ▼
[PR → CI/CD → 배포]

이 파이프라인은 실패 시 어디로 되돌아갈지가 명확한 상태 머신으로 제어된다. REQUIREMENTS와 ARCHITECTURE 단계가 실패하면 곧바로 사람에게 에스컬레이션하고, PLANNING과 PLAN_REVIEW는 최대 3회까지 이전 단계로 되돌려 재작업하며, IMPLEMENTATION은 executor·codex·gemini가 병렬로 붙었다가 머지된다. SECURITY_REVIEW에서 critical이 나오면 역시 사람에게 넘긴다.

INIT
  │
  ▼
[REQUIREMENTS] ──실패──▶ HUMAN_ESCALATION
  │ 통과
  ▼
[ARCHITECTURE] ──실패──▶ HUMAN_ESCALATION
  │ 통과
  ▼
[PLANNING] ──실패──▶ rework(ARCHITECTURE, max 3회)
  │ 통과
  ▼
[PLAN_REVIEW] ──거절──▶ rework(PLANNING, max 3회)
  │ 승인
  ▼
[IMPLEMENTATION] ── 병렬 ──▶ executor × N + codex + gemini
  │                          ◀── 머지
  ▼
[TESTING] ──실패──▶ rework(IMPLEMENTATION, max 3회)
  │ 통과
  ▼
[CODE_REVIEW] ──거절──▶ rework(IMPLEMENTATION)
  │ 승인
  ▼
[SECURITY_REVIEW] ──critical──▶ HUMAN_ESCALATION
  │ 통과
  ▼
[DOCUMENTATION]
  │
  ▼
[DEPLOYMENT] ──실패──▶ rollback + HUMAN_ESCALATION
  │ 통과
  ▼
DONE

단계별 실무 워크플로우

Phase 1: 요구사항/기획 (완전 자율)

담당 에이전트는 oh-my-claudecode:analyst (opus)이고, 입력은 1~2페이지 분량의 CONCEPT.md다. 최소 구조는 이렇다.

# 프로젝트명

## 목적

무엇을 만드는가 (1-3문장)

## 핵심 기능

- 기능 1
- 기능 2
- 기능 3

## 사용자

누가 사용하는가

## 기술 제약

- 언어/프레임워크 선호도
- 클라우드 플랫폼
- 보안 요구사항

실행 명령은 다음과 같다.

claude -p "
CONCEPT.md를 읽고 다음을 생성해줘:
1. PRD.md - 모든 API 엔드포인트, 데이터 모델, 사용자 흐름이 명시된 완전한 제품 요구사항 문서
2. ACCEPTANCE_CRITERIA.md - 각 기능별 통과/실패 판단 기준
3. TECH_STACK.md - 기술 스택 선택 및 근거

생성 완료 후 .omc/state/pipeline.json에 phase: requirements, status: complete 기록
" --output-format json

품질 게이트는 PRD에 모든 API 엔드포인트가 정의되어 있는지, 데이터 모델 다이어그램이 존재하는지, 사용자 시나리오 커버리지가 확보됐는지를 자동으로 검증한다.

Phase 2: 분석/설계 (완전 자율)

담당은 oh-my-claudecode:architect (opus)와 Gemini CLI(탐색 보조)다. Gemini CLI로 1M 토큰 컨텍스트를 활용해 초기 아키텍처 초안을 잡고, Claude Code architect가 이를 상세 설계로 구체화한다.

# Gemini CLI로 대용량 컨텍스트 초기 탐색 (1M 토큰 활용)
gemini -p "PRD.md, TECH_STACK.md를 읽고 시스템 아키텍처 초안을 작성해줘.
마이크로서비스 분리 기준, API 게이트웨이 패턴, DB 샤딩 전략을 포함해줘"

# Claude Code architect로 상세 설계
claude -p "
PRD.md와 Gemini의 아키텍처 초안을 기반으로 다음을 생성:
1. ARCHITECTURE.md - C4 모델 기반 시스템 설계 (Context/Container/Component)
2. API_SPEC.yaml - OpenAPI 3.0 완전 명세
3. DB_SCHEMA.sql - 정규화된 스키마 + 인덱스 전략
4. ADR/ - 주요 아키텍처 결정 기록 (Architecture Decision Records)

완료 후 .omc/state/pipeline.json 업데이트
"

Phase 3: 계획/태스크 분해 (완전 자율)

담당은 oh-my-claudecode:planner (opus)가 초안을 만들고 oh-my-claudecode:critic (opus)이 검증한다.

claude -p "
ARCHITECTURE.md, API_SPEC.yaml을 읽고 다음을 생성:
1. TASK_GRAPH.json - 의존성이 명시된 구현 태스크 목록
   - 각 태스크: id, description, dependencies[], estimated_files[], agent_tier
   - 병렬 실행 가능한 태스크 그룹 식별
2. IMPLEMENTATION_ORDER.md - 실행 순서 및 병렬화 전략

그 다음 critic 에이전트로 플랜 검토 후 APPROVED_PLAN.json 생성
"

TASK_GRAPH.json은 단계(phase)마다 병렬 실행 가능 여부와 태스크별 의존성·티어를 명시하는 형식을 쓴다.

{
  "phases": [
    {
      "phase": "foundation",
      "parallel": false,
      "tasks": [
        {
          "id": "T001",
          "desc": "프로젝트 구조 초기화",
          "dependencies": [],
          "tier": "sonnet"
        },
        {
          "id": "T002",
          "desc": "DB 연결 설정",
          "dependencies": ["T001"],
          "tier": "sonnet"
        }
      ]
    },
    {
      "phase": "core_implementation",
      "parallel": true,
      "tasks": [
        {
          "id": "T003",
          "desc": "사용자 인증 모듈",
          "dependencies": ["T002"],
          "tier": "sonnet"
        },
        {
          "id": "T004",
          "desc": "상품 관리 API",
          "dependencies": ["T002"],
          "tier": "sonnet"
        },
        {
          "id": "T005",
          "desc": "주문 처리 서비스",
          "dependencies": ["T002"],
          "tier": "opus"
        }
      ]
    }
  ]
}

Phase 4: 구현 (병렬 자율)

핵심 전략은 독립 모듈을 3개 도구에 분산 병렬 실행하는 것이다. Claude Code가 오케스트레이터와 복잡한 비즈니스 로직을, Codex CLI가 독립 파일 구현을, Gemini CLI가 보일러플레이트·유틸리티 코드를 맡는다.

권장 방법은 OMC Agent Teams다. .claude/settings.json에 "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }을 설정한 뒤 다음처럼 팀을 구성한다.

# 방법 1: OMC Agent Teams (권장)
# settings.json에 설정:
# "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }

claude -p "
APPROVED_PLAN.json을 읽고 Agent Teams를 구성해줘:
- 팀 리더: 오케스트레이션 및 통합 담당
- Teammate 1: 백엔드 API 레이어 (T003, T004)
- Teammate 2: 비즈니스 로직 레이어 (T005, T006)
- Teammate 3: 데이터 접근 레이어 (T007, T008)
- Teammate 4: 테스트 작성 (구현과 병렬)

각 팀원이 독립된 파일 영역을 담당하도록 작업 분배
"

# 방법 2: 외부 도구 병렬 실행 (OMC 명령)
# /team 3:codex "T003: 사용자 인증 모듈 구현 - src/auth/ 디렉토리"
# /team 3:gemini "T004: 상품 관리 CRUD API - src/products/ 디렉토리"

구현 품질을 지키려면 CLAUDE.md에 코드 표준, 아키텍처 준수, 자가 검증 항목을 명시해야 한다.

# 구현 규칙

## 코드 표준

- TypeScript strict mode 필수
- 모든 함수에 JSDoc 주석
- 에러 처리: Result<T, E> 패턴 사용
- 로깅: structured JSON 형식

## 아키텍처 준수

- ARCHITECTURE.md의 컴포넌트 경계 준수
- API_SPEC.yaml의 엔드포인트 시그니처 100% 준수
- DB_SCHEMA.sql의 테이블/컬럼명 동일하게 사용

## 자가 검증

- 각 파일 구현 후 즉시 linter 실행
- import 경로 오류 없을 것
- 타입 오류 없을 것

Phase 5: 테스트 (완전 자율)

담당은 oh-my-claudecode:test-engineer (sonnet)와 oh-my-claudecode:qa-tester (sonnet)다.

claude -p "
구현된 코드베이스를 분석하고:
1. 단위 테스트 생성 - 각 함수/메서드별 happy path + edge case
2. 통합 테스트 생성 - API 엔드포인트별 end-to-end 시나리오
3. 테스트 실행 및 실패 분석
4. 실패한 테스트의 원인을 구현 코드에서 수정
5. 80% 이상 커버리지 달성까지 반복 (최대 5회)

테스트 결과를 TEST_REPORT.json으로 저장
커버리지 미달 시 추가 테스트 케이스 자동 생성
"

자가 수정 루프는 hooks로 걸어둔다.

// .claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "test.*fail",
        "hooks": [
          {
            "type": "command",
            "command": "echo '테스트 실패 감지: 자동 수정 루프 시작'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Phase 6: 코드 리뷰 (완전 자율)

담당은 oh-my-claudecode:code-reviewer (opus)와 oh-my-claudecode:security-reviewer (sonnet)로, 두 단계로 나눠 진행한다.

claude -p "
두 단계 코드 리뷰를 수행:

## 1단계: code-reviewer (opus)
- ARCHITECTURE.md 준수 여부
- 비즈니스 로직 정확성
- 성능 패턴 (N+1 쿼리, 메모리 누수)
- 코드 중복 및 복잡도

## 2단계: security-reviewer (sonnet)
- OWASP Top 10 취약점 스캔
- SQL 인젝션, XSS, CSRF 체크
- 시크릿/자격증명 하드코딩 탐지
- 의존성 취약점 (npm audit / pip-audit)

결과: REVIEW_REPORT.md (severity: critical/high/medium/low)
critical 발견 시: 자동으로 구현 단계로 rollback하여 수정
"

Phase 7: 배포 (완전 자율)

담당은 oh-my-claudecode:git-master (sonnet)와 oh-my-claudecode:executor (sonnet)다. PR 생성부터 CI/CD 확인, IaC 생성, 스테이징·프로덕션 배포, 알림까지 한 번에 지시한다.

claude -p "
배포 파이프라인을 실행:

1. git-master:
   - feature 브랜치에서 main으로 PR 생성
   - PR 설명에 변경사항 요약 자동 작성

2. CI/CD 트리거:
   - .github/workflows/deploy.yml 실행 확인
   - 빌드/테스트 통과 대기

3. IaC 생성 (미존재 시):
   - terraform/ 디렉토리에 인프라 코드 생성
   - docker-compose.yml 또는 k8s manifests 생성

4. 배포 실행:
   - 스테이징 환경 배포 → 스모크 테스트
   - 통과 시 프로덕션 배포

5. NanoClaw 알림 (설정된 경우):
   - Telegram/Slack으로 배포 완료 알림 전송
"

완전 자율화 실행 전략

단일 명령 전체 파이프라인 실행

가장 권장되는 방법은 OMC autopilot 모드다. CONCEPT.md만 작성하면 한 줄로 실행된다.

# CONCEPT.md 작성 후 한 줄 실행
/oh-my-claudecode:autopilot

# 또는 CLI에서
claude -p "
/autopilot

CONCEPT.md를 읽고 완성된 솔루션을 빌드해줘.
기획 → 설계 → 구현 → 테스트 → 배포까지 전 단계를 자율적으로 완료해.
각 단계 완료 시 .omc/state/pipeline.json 업데이트.
사람의 개입 없이 완료해.
" --dangerously-skip-permissions

세션이 끊겨도 재시작 가능한 방법은 OMC ralph 모드다.

# ralph = 완료할 때까지 계속 실행 + 검증 루프
/oh-my-claudecode:ralph

# 세션 중단 후 재시작 시
/oh-my-claudecode:resume [session-id]

CI/CD에 통합하려면 쉘 스크립트로 래핑한다.

#!/bin/bash
# ai-factory.sh

PROJECT_DIR=$1
CONCEPT_FILE=$2

cd "$PROJECT_DIR"

# 완전 자율 실행 (--dangerously-skip-permissions: 모든 권한 승인)
claude -p "
$(cat "$CONCEPT_FILE")

위 개념을 바탕으로 완성된 소프트웨어 솔루션을 생성해줘.
단계: 요구사항분석 → 아키텍처설계 → 구현 → 테스트 → 배포준비
각 단계를 자율적으로 완료하고 다음 단계로 진행해.
실패 시 최대 3회 재시도 후 오류 로그를 ERRORS.md에 기록해.
" \
  --dangerously-skip-permissions \
  --output-format stream-json \
  2>&1 | tee logs/ai-factory-$(date +%Y%m%d-%H%M%S).log

완전 자율화를 위한 필수 사전 설정

권한 설정(.claude/settings.json)은 필요한 도구를 명시적으로 허용하고 Agent Teams를 켜두는 형태다.

{
  "permissions": {
    "allow": [
      "Bash(*)",
      "Read(*)",
      "Write(*)",
      "Edit(*)",
      "Glob(*)",
      "WebFetch(*)",
      "WebSearch(*)"
    ]
  },
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

프로젝트 컨텍스트 파일(.claude/agents/project-context.md)에는 기술 스택, 코딩 규칙, 자격증명 취급 원칙을 적어둔다.

# 프로젝트 컨텍스트

## 기술 스택

- 백엔드: Node.js + TypeScript + Express
- DB: PostgreSQL + Redis
- 배포: Docker + AWS ECS

## 코딩 규칙

[프로젝트별 규칙]

## 비밀번호/자격증명

- 절대 하드코딩 금지
- 환경변수 또는 AWS Secrets Manager 사용

품질 게이트 훅(.claude/settings.json)은 태스크 완료 시점에 컴파일·테스트 실패를 잡아 태스크 완료 자체를 막는다.

{
  "hooks": {
    "TaskCompleted": [
      {
        "type": "command",
        "command": "bash .claude/hooks/quality-gate.sh",
        "timeout": 60
      }
    ]
  }
}

# .claude/hooks/quality-gate.sh
#!/bin/bash
# 품질 게이트: 실패 시 exit 2로 태스크 완료 차단

# TypeScript 컴파일 오류 체크
if [ -f "tsconfig.json" ]; then
  npx tsc --noEmit || exit 2
fi

# 테스트 실패 체크
if [ -f "package.json" ]; then
  npm test -- --passWithNoTests || exit 2
fi

echo "품질 게이트 통과"
exit 0

오케스트레이션 패턴: 규모에 따라 무엇을 쓸까

프로젝트 규모와 복잡도에 따라 권장 패턴이 갈린다.

프로젝트 규모	복잡도	권장 패턴
소형 (<20개 파일)	낮음	Single Agent + ultrawork
중형 (20-100개 파일)	중간	Subagent Fan-out
대형 (100-500개 파일)	높음	Agent Teams (3-5명)
초대형 (500+ 파일)	매우 높음	Agent Teams + 멀티 도구 병렬

중형 프로젝트에는 Subagent Fan-out 패턴이 맞는다. 오케스트레이터가 백엔드·프론트엔드·DB 마이그레이션·테스트를 서브에이전트로 나눠 맡기고, 모두 완료된 뒤 통합한다.

오케스트레이터 (Claude Code)
    │
    ├──▶ Subagent A: 백엔드 API 구현
    ├──▶ Subagent B: 프론트엔드 컴포넌트
    ├──▶ Subagent C: 데이터베이스 마이그레이션
    └──▶ Subagent D: 테스트 작성
         │
         └── 모두 완료 후 오케스트레이터가 통합

claude -p "
병렬로 다음 작업을 수행해:
- Task(백엔드 API 구현, src/api/ 디렉토리, executor/sonnet)
- Task(프론트엔드 컴포넌트, src/components/ 디렉토리, executor/sonnet)
- Task(DB 마이그레이션, db/migrations/ 디렉토리, executor/sonnet)
- Task(테스트 작성, tests/ 디렉토리, test-engineer/sonnet)

모두 완료 후 통합 테스트 실행
"

대형 프로젝트는 Agent Teams 패턴으로 팀 리더 아래 백엔드·프론트엔드·QA·DevOps 엔지니어를 배치한다.

# settings.json에 Agent Teams 활성화 후
claude -p "
팀을 구성해:
- 팀 리더: 전체 조율
- 백엔드 엔지니어: 서버, API, DB
- 프론트엔드 엔지니어: UI, 상태관리
- QA 엔지니어: 테스트, 검증
- DevOps 엔지니어: CI/CD, 배포

각 팀원에게 독립적인 파일 영역 할당
공유 태스크 목록으로 진행 상황 동기화
"

멀티 도구를 각각 다른 터미널에서 병렬로 돌리는 패턴도 있다. Claude Code가 오케스트레이터로 핵심 로직을, Codex CLI가 독립 모듈을, Gemini CLI가 보일러플레이트를 맡고 마지막에 Claude Code가 통합한다.

# OMC를 통한 외부 도구 병렬 실행
# Claude Code가 오케스트레이터 역할

# 터미널 1: Claude Code (오케스트레이터 + 복잡한 로직)
claude -p "오케스트레이터: 전체 조율 및 src/core/ 구현"

# 터미널 2: Codex CLI (독립 모듈)
codex "src/auth/ 인증 모듈 구현 - JWT, OAuth2"

# 터미널 3: Gemini CLI (보일러플레이트)
gemini -p "src/utils/ 유틸리티 함수들 구현"

# 완료 후 Claude Code가 통합
claude -p "세 도구가 생성한 코드를 통합하고 충돌 해결해줘"

품질 게이트 설계

단계별 자동 검증 기준

각 단계마다 검증 항목과 실패 시 처리 방식이 다르다.

단계	검증 항목	실패 시 처리
요구사항	PRD 완성도 체크리스트	누락 섹션 자동 보완
설계	OpenAPI 유효성, DB 정규화	자동 수정 후 재검증
구현	컴파일, lint, 타입 체크	즉시 수정 루프
테스트	커버리지 ≥80%, 0 critical fail	추가 테스트 생성
코드리뷰	OWASP, 아키텍처 준수	구현 단계 롤백
배포	스모크 테스트, 헬스체크	자동 롤백

자동 수정 루프 (Self-Healing Loop)

테스트 실패 시 오류 분석 → 수정 사항 생성 → 코드 수정 적용 → 재실행을 반복하되, 5회를 넘기면 사람에게 넘긴다.

구현 완료
    │
    ▼
테스트 실행 ──실패──▶ 오류 분석
    │                     │
    │ 통과                ▼
    │              수정 사항 생성
    │                     │
    │                     ▼
    │              코드 수정 적용
    │                     │
    │              반복 횟수 < 5?
    │                  │        │
    │                 예        아니오
    │                  │        │
    │              테스트       ERRORS.md
    │              재실행       + 로그
    ◀──────────────────          + 알림

컨텍스트 관리 전략

파일 기반 영구 컨텍스트

프로젝트 아티팩트와 상태는 전부 .omc/ 아래 파일로 남는다.

.omc/
├── artifacts/
│   ├── requirements/
│   │   ├── PRD.md
│   │   └── ACCEPTANCE_CRITERIA.md
│   ├── design/
│   │   ├── ARCHITECTURE.md
│   │   ├── API_SPEC.yaml
│   │   └── DB_SCHEMA.sql
│   ├── planning/
│   │   ├── TASK_GRAPH.json
│   │   └── APPROVED_PLAN.json
│   └── reports/
│       ├── TEST_REPORT.json
│       └── REVIEW_REPORT.md
├── state/
│   └── sessions/{session-id}/
│       ├── pipeline.json      ← 현재 단계/상태
│       ├── decisions.json     ← ADR 기록
│       └── rollback-points/   ← Git SHA 스냅샷
├── notepad.md                 ← 세션 간 공유 메모
└── project-memory.json        ← 장기 프로젝트 기억

컨텍스트 압축 전략

대형 프로젝트에서 컨텍스트 윈도우 초과를 막으려면, 각 단계 완료 시 핵심 결정사항을 스냅샷으로 저장하고 다음 에이전트는 그 스냅샷만 읽고 시작하게 한다.

# 각 단계 완료 시 컨텍스트 스냅샷 저장
claude -p "
현재까지의 핵심 결정사항을 요약하여
.omc/state/sessions/{id}/context-snapshot-phase-{N}.md에 저장해줘.
포함: 주요 아키텍처 결정, 구현 패턴, 알려진 제약사항
"

# 다음 에이전트 시작 시 스냅샷만 로드
claude -p "
context-snapshot-phase-3.md를 읽고 이전 결정을 이해한 후
테스트 작성을 시작해줘
"

멀티 에이전트 간 컨텍스트 공유

에이전트끼리는 notepad.md 파일 하나를 공유 메모장처럼 쓴다.

# 에이전트 A가 완료 후 핵심 정보 기록
echo "AUTH_MODULE: JWT RS256 사용, 토큰 만료 1h, 리프레시 토큰 7d" \
  >> .omc/notepad.md

# 에이전트 B가 시작 시 notepad 읽기
cat .omc/notepad.md

바로 쓸 수 있는 실행 명령

신규 프로젝트 전체 파이프라인 (한 줄 실행)

CONCEPT.md를 작성한 뒤 전체 파이프라인을 한 번에 돌린다.

# 1. CONCEPT.md 작성
cat > CONCEPT.md << 'EOF'
# 프로젝트명: [프로젝트명]
## 목적: [목적]
## 핵심기능: [기능1, 기능2, 기능3]
## 기술스택: [선호 스택]
## 배포환경: [AWS/GCP/Azure + Docker/K8s]
EOF

# 2. 전체 파이프라인 실행 (완전 자율)
claude --dangerously-skip-permissions -p "
CONCEPT.md를 읽고 완성된 프로덕션 레디 솔루션을 생성해줘.

실행 순서:
1. PRD.md, ACCEPTANCE_CRITERIA.md 생성
2. ARCHITECTURE.md, API_SPEC.yaml, DB_SCHEMA.sql 생성
3. TASK_GRAPH.json으로 구현 태스크 분해
4. 병렬 에이전트로 코드 구현
5. 테스트 생성 및 실행 (커버리지 80%+ 목표)
6. 코드 리뷰 및 보안 감사
7. CI/CD 파이프라인 및 Docker 설정 생성

각 단계 완료 시 .omc/state/pipeline.json 업데이트.
실패 시 최대 3회 재시도.
모든 단계 완료 후 DONE.md에 최종 결과 요약.
"

단계별 개별 실행

전체를 한 번에 돌리지 않고 단계별로 쪼개 실행할 수도 있다.

# 요구사항 분석만
claude -p "CONCEPT.md → PRD.md 변환. analyst 에이전트 역할로 수행."

# 아키텍처 설계만
claude -p "PRD.md → ARCHITECTURE.md + API_SPEC.yaml + DB_SCHEMA.sql. architect 에이전트 역할."

# 구현만 (Agent Teams 활용)
claude -p "APPROVED_PLAN.json 읽고 Agent Teams로 병렬 구현 시작"

# 테스트만
claude -p "구현된 코드 분석 → 테스트 작성 → 실행 → 실패 수정 루프. 80% 커버리지 달성까지."

# 코드리뷰만
claude -p "전체 코드베이스 code-review + security-review 수행. REVIEW_REPORT.md 생성."

기존 코드베이스에 적용

신규 프로젝트가 아니라 기존 코드베이스를 분석·개선하는 데도 같은 접근을 쓸 수 있다.

# 기존 프로젝트 분석 후 개선
claude -p "
이 코드베이스를 분석하고:
1. 현재 아키텍처 역공학하여 ARCHITECTURE.md 생성
2. 부채 목록 TECH_DEBT.md 생성
3. 리팩토링 우선순위 REFACTOR_PLAN.md 생성
4. 테스트 커버리지 현황 분석
5. 보안 취약점 스캔

완료 후 개선 작업 자동 실행 (승인 필요 없음)
" --dangerously-skip-permissions

OMC 스킬 활용 명령

OMC가 제공하는 스킬 명령으로 실행 모드를 바로 바꿀 수 있다.

# 전체 자율 실행
/oh-my-claudecode:autopilot

# 완료될 때까지 반복 (세션 중단 복구 가능)
/oh-my-claudecode:ralph

# 병렬 고속 실행 (독립 태스크)
/oh-my-claudecode:ultrawork

# 외부 도구 통합
/oh-my-claudecode:ccg  # Claude + Codex + Gemini 동시 실행

# 심층 분석 후 구현
/oh-my-claudecode:deep-interview

비용과 한계

예상 비용 (프로젝트 규모별)

프로젝트 규모가 커질수록 파일 수·토큰·비용이 함께 늘어난다.

프로젝트 규모	예상 파일 수	예상 토큰	예상 비용
소형 REST API	20-50개	2-5M	$10-30
중형 웹앱	50-200개	10-30M	$50-200
대형 마이크로서비스	200-500개	50-200M	$300-1,500
초대형 플랫폼	500+	200M+	$1,500+

비용 최적화의 기본 원칙은 Opus는 아키텍처·설계에만, Sonnet은 구현에, Haiku는 반복 작업에 쓰는 것이다(30~50% 절감).

현재 한계 (2026년 3월 기준)

한계	현황	대응책
컨텍스트 윈도우	500+ 파일 시 성능 저하	컨텍스트 스냅샷 + 단계별 압축
아키텍처 일관성	멀티 에이전트 시 스타일 불일치	CLAUDE.md 코딩 규칙 강제
복잡 비즈니스 로직	도메인 지식 없으면 오류	ADR + 상세 도메인 설명 필수
테스트 원형성	AI가 자신이 짠 코드의 테스트 생성	독립 에이전트로 테스트 작성
프로덕션 배포	자율 배포는 고위험	스테이징까지 자율, 프로덕션은 인간 트리거 권장
세션 재시작	Agent Teams 세션 복구 불가	ralph 모드 + 체크포인트 파일

알려진 함정과 대응책

에이전트 루프 무한 반복 방지

동일한 액션이 반복되는지 감지해 5회를 넘기면 에이전트를 중단시키는 훅을 걸어둔다.

// .claude/settings.json - 최대 반복 횟수 설정
{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "python3 .claude/hooks/loop-guard.py",
        "timeout": 5
      }
    ]
  }
}

# .claude/hooks/loop-guard.py
import json, sys
from pathlib import Path

state_file = Path(".omc/state/loop-guard.json")
state = json.loads(state_file.read_text()) if state_file.exists() else {"count": 0, "last_action": ""}

current_action = sys.stdin.read()
if current_action == state["last_action"]:
    state["count"] += 1
    if state["count"] > 5:
        print("무한 루프 감지: 동일 액션 5회 반복")
        sys.exit(2)  # 에이전트 중단
else:
    state = {"count": 1, "last_action": current_action}

state_file.write_text(json.dumps(state))

멀티 에이전트 동일 파일 충돌 방지

TASK_GRAPH.json에 파일 소유권을 명시해 팀원끼리 같은 파일을 건드리지 않게 한다.

# 파일 소유권 명시 - TASK_GRAPH.json에 포함
{
  "file_ownership": {
    "src/auth/": "teammate-1",
    "src/products/": "teammate-2",
    "src/orders/": "teammate-3",
    "src/shared/": "team-lead-only"  ← 공유 파일은 팀 리더만 수정
  }
}

시크릿/자격증명 보호

.gitignore와 CLAUDE.md에 명시적 금지 규칙을 박아둔다.

# .gitignore에 항상 포함
echo ".env
.env.*
secrets/
*.pem
*.key" >> .gitignore

# CLAUDE.md에 명시적 금지 규칙
echo "
## 보안 규칙 (절대 위반 금지)
- 실제 API 키, 비밀번호, 토큰을 코드에 하드코딩 금지
- 환경변수 또는 시크릿 매니저 사용 필수
- .env.example만 커밋 (실제 값 없이)
" >> CLAUDE.md

배포 전 최종 검증 체크리스트

배포 직전 검증도 자동 실행 가능한 체크리스트로 던져줄 수 있다.

# 자동 실행 가능한 배포 전 검증
claude -p "
배포 전 최종 검증을 수행해줘:
□ 모든 환경변수가 .env.example에 문서화되어 있는가
□ docker build가 성공하는가
□ 모든 테스트가 통과하는가
□ npm audit / pip-audit에서 critical 취약점 없는가
□ API 엔드포인트가 API_SPEC.yaml과 일치하는가
□ DB 마이그레이션이 멱등성(idempotent)인가
□ 헬스체크 엔드포인트 (/health)가 존재하는가

실패 항목 자동 수정 후 재검증
"

완전 자율화 핵심 패턴 (Dark Factory)

5단계 AI 개발 자동화 레벨 (Dan Shapiro, 2026)

AI 개발 자동화는 다섯 단계로 나눠 볼 수 있다.

레벨	설명	현황
Level 1	코드 자동완성 (Copilot)	완전 성숙
Level 2	레포 전체 읽기/쓰기 에이전트 (Cursor, Windsurf)	성숙
Level 3	계획-실행-재시도 자율 에이전트	실용 단계
Level 4	사양 입력 → 배포된 소프트웨어 출력 (Dark Factory)	현재 최전선
Level 5	개념에서 프로덕션까지 제로 휴먼 터치	아직 이론적

2026년 3월 기준 달성 가능한 최고 수준은 Level 4~4.5다. 사람은 의도와 제약을 정의하고, 에이전트가 모든 구현을 처리한다.

Ralph Wiggum 기법 (단일 에이전트 반복 루프)

가장 실용적이고 검증된 완전 자율화 패턴은 다음 여섯 단계를 반복하는 것이다. JSON 태스크 목록에서 다음 태스크를 선택하고, 에이전트가 구현하고, 테스트·타입 체크·린터로 검증하고, 통과하면 커밋하고, 태스크 상태를 갱신하고 교훈을 AGENTS.md에 남긴 뒤, 컨텍스트를 리셋하고 다시 반복한다.

핵심 인사이트는 매 반복마다 컨텍스트를 리셋해 컨텍스트 오버플로우와 누적 혼란을 막는다는 데 있다. 각 실행은 범위가 제한된 새로운 프롬프트로 시작한다.

# 실행 스크립트 예시
while true; do
  NEXT_TASK=$(python3 scripts/get-next-task.py tasks.json)
  if [ "$NEXT_TASK" == "DONE" ]; then break; fi

  claude --dangerously-skip-permissions -p "
  AGENTS.md를 읽고 컨텍스트를 파악해.
  다음 태스크를 구현해: $NEXT_TASK
  완료 후 테스트 실행. 실패 시 최대 3회 수정.
  성공 시 git commit하고 태스크를 complete로 표시.
  교훈이 있으면 AGENTS.md에 추가해.
  "
done

Harness Engineering (OpenAI, 2026)

OpenAI가 3명의 엔지니어로 5개월간 백만 줄 코드베이스를 구현한 방법의 핵심 원칙은 "인간이 방향을 잡고, 에이전트가 실행한다"는 것이다. 하네스(Harness)는 에이전트의 뇌 역할을 하는 AGENTS.md/CLAUDE.md, 의존성 방향과 레이어드 아키텍처를 강제하는 커스텀 린터, 에이전트 결정을 제약 내에서 허용하는 계층화된 도메인 경계, 테스트 없이는 속도가 방향 없는 속도임을 막는 CI/CD 강제 테스트 게이트, 무한 루프를 막는 토큰 예산 한도, 그리고 레포에 없으면 에이전트에게 존재하지 않는 것이나 마찬가지인 아키텍처 문서로 구성된다.

하네스(Harness) 구성 요소:
├── AGENTS.md / CLAUDE.md     ← 에이전트의 뇌 (아키텍처, 규칙, 패턴)
├── 커스텀 린터               ← 의존성 방향, 레이어드 아키텍처 강제
├── 계층화된 도메인 경계       ← 에이전트 결정을 제약 내에서 허용
├── CI/CD 강제 테스트 게이트   ← 테스트 없이는 속도는 방향 없는 속도
├── 토큰 예산 한도             ← 무한 루프 방지
└── 아키텍처 docs (repo 내)    ← repo에 없으면 에이전트에게 존재하지 않음

이 하네스로 나온 실적은 PR 1,500개, 수동으로 작성된 코드 0줄, 코드 리뷰 0건이다.

Holdout Validation (테스트 원형성 해결)

AI가 자신이 짠 코드의 테스트를 생성하는 "원형성 문제"의 해결책은 ML의 train/test 분리와 같은 원리다. 개발 에이전트가 코드를 구현하는 동안 검증 에이전트가 숨겨진 시나리오를 비공개로 준비해두고, 배포가 끝난 뒤 홀드아웃 검증을 실행해 실제 동작을 검증한다.

개발 에이전트                   검증 에이전트
     │                               │
     ▼                               │
코드 구현                            │
     │              숨겨진 시나리오  │
     │         ◄─── (개발 중 비공개) │
     ▼                               ▼
배포 완료 ────────────────► 홀드아웃 검증 실행
                                      │
                              실제 동작 검증
                              (ML train/test 분리와 동일 원리)

Kelos - Kubernetes 네이티브 자율 배포 (2026)

가장 완성된 오픈소스 자율 배포 프레임워크로 Kelos가 꼽힌다. GitHub 이슈가 열리면 TaskSpawner가 자동으로 반응해 에이전트를 붙이는 식이다.

# TaskSpawner 예시 - GitHub 이슈 자동 처리
apiVersion: kelos.dev/v1
kind: TaskSpawner
metadata:
  name: issue-resolver
spec:
  trigger:
    github:
      event: issues.opened
      labels: ["bug", "auto-fix"]
  agentConfig: claude-code-config
  workspace:
    repo: "github.com/myorg/myapp"
  maxIterations: 15
  tokenBudget: 1000000 # 비용 제한

Kelos 자체 개발팀은 이슈 트리아지 에이전트(24/7), 구현 계획 에이전트, 버그 수정 에이전트, PR 피드백 대응 에이전트, DX 테스트 에이전트, 프롬프트 자가 튜닝 에이전트로 운영된다.

무한 루프 방지 실무 코드

모든 자율 에이전트에는 하드 반복 한도, 토큰 예산 초과, 진전 없음 감지 세 가지를 함께 체크하는 가드가 필요하다.

# loop-guard.py - 모든 자율 에이전트에 필수

class AgentLoopGuard:
    MAX_ITERATIONS = 15
    MAX_TOKEN_BUDGET = 1_000_000  # ~$3
    NO_PROGRESS_THRESHOLD = 3

    def __init__(self):
        self.iterations = 0
        self.token_count = 0
        self.previous_outputs = []
        self.consecutive_no_progress = 0

    def check(self, current_output: str, tokens_used: int) -> str:
        self.iterations += 1
        self.token_count += tokens_used

        # 1. 하드 반복 한도
        if self.iterations >= self.MAX_ITERATIONS:
            return "ESCALATE: max iterations reached"

        # 2. 토큰 예산 초과
        if self.token_count >= self.MAX_TOKEN_BUDGET:
            return "ESCALATE: token budget exceeded"

        # 3. 진전 없음 감지 (동일 출력 반복)
        if current_output in self.previous_outputs[-3:]:
            self.consecutive_no_progress += 1
            if self.consecutive_no_progress >= self.NO_PROGRESS_THRESHOLD:
                return "ESCALATE: no progress detected"
        else:
            self.consecutive_no_progress = 0

        self.previous_outputs.append(current_output)
        return "CONTINUE"

실사례 검증 데이터

실제로 완전 자율화 패턴을 적용한 사례들의 결과와 비용은 다음과 같다.

사례	팀 규모	기간	결과	비용
Anthropic C 컴파일러	에이전트 16개	2주	10만 줄 Rust, Linux 6.9 빌드	$20,000
OpenAI 제품 개발	엔지니어 3명	5개월	100만 줄, 1,500 PR	비공개
StrongDM 생산 코드	엔지니어 3명	2025.07~	3.2만 줄 프로덕션	~$1,000/엔지니어/월
Claude Code 자체	-	-	코드베이스의 90%가 Claude Code 작성	-

Level 5(진정한 제로 휴먼)는 아직 이론적이다. 위 사례 모두 사람이 의도·제약을 정의하고 하네스 설계를 담당했다는 점은 변하지 않는다.

빠른 참조

도구별 최적 용도는 이렇게 정리된다.

Claude Code     → 오케스트레이터, 아키텍처, 복잡 로직, 멀티파일 리팩토링
Codex CLI       → 독립 모듈 병렬 구현, 격리된 워크트리 작업
Gemini CLI      → 대용량 코드베이스 탐색 (1M 토큰), 초기 분석, 무료 탐색
OMC autopilot   → 완전 자율 전체 파이프라인
OMC ralph       → 재시작 가능한 장기 실행
OMC ultrawork   → 독립 태스크 병렬 실행
NanoClaw        → 보안 격리된 자율 배포 + 메시징 알림

모델 티어는 작업 성격에 따라 나눠 쓴다.

Haiku   → 반복 작업, 단순 조회, 보일러플레이트
Sonnet  → 표준 구현, 테스트, 문서화 (일반 작업의 80%)
Opus    → 아키텍처 설계, 복잡 분석, 보안 리뷰 (고가 작업의 20%)

긴급 중단은 다음 명령으로 한다.

# 모든 AI 에이전트 중단
/oh-my-claudecode:cancel
# 또는 환경변수로 비활성화
export DISABLE_OMC=1