개발 단위를 크게 가져가기: 래칫과 결정론적 가드레일 종합

Date: 2026-03-17
Author: reode-team (Claude Code Opus 4.6, mangowhoiscloud)

목차

1. 도입: 개발 단위의 딜레마
2. 이코에코: CI + Observability 재귀개선루프
3. GEODE: Self-Correcting Pipeline과 Confidence Gate
4. REODE: 3계층 래칫으로 대단위 자율 실행
5. Karpathy의 autoresearch: 밤새 100+ 실험이 가능한 구조
6. 결정론적 가드레일의 설계 원칙
7. 마무리

---

1. 도입: 개발 단위의 딜레마

소프트웨어 개발에서 "한 번에 얼마나 큰 단위를 위임할 수 있는가"는 생산성을 결정하는 핵심 변수입니다.
인간 사이 협업에도 이 문제는 존재합니다. 주니어에게 "이 함수 고쳐줘"라고 하면 안전하지만 느립니다.
"이 모듈 전체를 리팩토링해줘"라고 하면 빠르지만 위험합니다. 코드 리뷰라는 사후 검증(post-hoc verification)이 이 간극을 메워왔습니다. 자율 코딩 에이전트에게 작업을 위임할 때도 동일한 딜레마가 존재합니다. 다만 규모가 다릅니다.

작은 단위 (마이크로스텝)
  "이 import 문을 javax.servlet에서 jakarta.servlet으로 바꿔줘"
  → 안전. 검증 쉬움. 하지만 200개 파일이면 200번 반복.

큰 단위 (매크로스텝)
  "이 Java 프로젝트를 Spring Framework에서 Spring Boot로 마이그레이션해줘"
  → 빠름. 하지만 중간에 무엇이 깨졌는지 모를 수 있음.

이 글에서는 세 개의 프로젝트(이코에코(Eco²), GEODE, REODE)에서 각각 개발 단위를 어떤 방식으로 제어했는지를 다룹니다.
각 프로젝트는 서로 다른 도메인에서 각각 어떤 접근 방식을 택했고, 그 차이를 돌아보며 래칫(Ratchet)과 결정론적 가드레일(Deterministic Guardrail)이라는 공통 설계 원칙을 회고할 수 있습니다.

이코에코	2025.10 ~ 2026.01	도메인 API 1개	CI Quality Gate (Black+Ruff+Pytest) + KB
GEODE	2025.03 ~ 2025.10	파이프라인 노드 1개	Self-Correcting Loop (confidence gate)
REODE	2026.03 ~	모듈 단위 마이그레이션	3계층 래칫 (GT → Build → CI)
autoresearch	2026.03 (Karpathy)	밤새 100+ 실험	program.md + git ratchet

표의 오른쪽으로 갈수록 검증이 결정론적이 됩니다.
그리고 검증이 결정론적이 될수록, 에이전트에게 위임할 수 있는 단위가 커집니다.
이 상관관계가 이 글의 핵심 주장입니다.

---

2. 이코에코: CI + Observability 재귀개선루프

2.1 프로젝트 개요

이코에코(Eco²)는 2025 AI 새싹톤에서 우수상을 수상한 분리배출 도우미 AI 챗봇입니다. 24개 클러스터 노드, 8개 도메인 API, 6개 비동기 Worker, 3개 인프라 피쳐(ext-authz, SSE Gateway, Event Router)로 구성된 마이크로서비스 아키텍처입니다.

이코에코 백엔드 규모
├── 도메인 API: Auth, Chat, Scan, Character, Location, Users, Images, Info
├── Worker: Auth, Character, Chat, Scan, Users, Info
├── 인프라: ext-authz (Go), SSE Gateway, Event Router
├── 스택: FastAPI, LangGraph, gRPC, RabbitMQ, Redis Streams, K8s, Istio
└── 성능: ext-authz 1,477 RPS | Scan API 1000 VU 97.8% · 373 RPM

이 규모의 시스템을 약 3개월 만에 구축할 수 있었던 배경에는 Agent-Driven Development 방법론이 있습니다.

2.2 에이전트 플릿 운용과 Knowledge Base

이코에코에서 Claude Code로 전환한 시점(2026.01.15)부터, 개발 방식이 근본적으로 바뀌었습니다.

Cursor 시대 (2025.10 ~ 2026.01):
  Sidebar 병렬 세션 + Worktree 분기
  → Human-in-the-Loop: 매 변경을 개발자가 검토

Claude Code 시대 (2026.01.15 ~):
  Task 도구 기반 Agent Fleet 자율 운용
  → 27개 커스텀 Skills + KB(76편) 주입
  → Sub agent에 Skills 주입, 7,500+ Task 도구 호출 관측

Cursor에서 Claude Code로의 전환은 도구의 변경이 아니라 개발 단위의 전환이었습니다. Sidebar에서는 한 번에 하나의 파일을 수정하는 것이 자연스러운 단위였지만, Claude Code의 Task 도구와 Sub agent 시스템은 "도메인 하나를 통째로 구현해줘"라는 위임을 가능하게 했습니다.

2.3 CI Quality Gate: 서비스별 결정론적 가드레일

이코에코의 특징적인 점은, 코드 품질에 대한 결정론적 CI 가드레일이 프로젝트 초기부터 구축되어 있었다는 것입니다.
이코에코의 CI는 9개 워크플로우로 구성되며, 서비스별 매트릭스 전략으로 변경된 서비스만 선택적으로 검증합니다.

ci-services.yml       8개 API (auth, users, character, location, scan, images, info, chat)
ci-workers.yml        6개 Worker (auth, users, scan, character, info, chat)
ci-ext-authz.yml      ext-authz (Go: go test)
ci-sse-components.yml SSE Gateway + Event Router
ci-canary.yml         Canary 배포 (label-based)
ci-sonarcloud.yml     정적 분석 (SonarCloud)

각 서비스의 Quality Gate는 동일한 3단계 결정론적 검증을 실행합니다.

Commit Filter (conventional commit type → docs skip)
   │
   ▼
Path-based Change Detection (matrix strategy)
   │
   ▼
┌──────────────────────────────────────────────────────────┐
│  Quality Gate (서비스당 독립 실행)                          │
│                                                          │
│  1. Black --check     (포맷 검증, 결정론적)               │
│  2. Ruff check        (린트, 결정론적)                    │
│  3. Pytest            (유닛 테스트, 결정론적)              │
│                                                          │
│  → 전부 pass → Build & Push (Docker + Kustomize 태그 갱신) │
│  → 하나라도 fail → 빌드 차단                              │
└──────────────────────────────────────────────────────────┘
   │
   ▼
ArgoCD Sync (Kustomize manifest 변경 감지 → 자동 배포)

핵심은 Quality Gate가 Build & Push의 전제조건이라는 점입니다. Black/Ruff/Pytest를 통과하지 못한 코드는 Docker 이미지로 빌드되지 않으며, 따라서 클러스터에 배포될 수 없습니다. 이것은 REODE의 L1 CI 래칫과 동일한 원리입니다.

Worker 파이프라인은 여기에 Manifest Validation을 추가합니다.

# ci-workers.yml — manifest-validation job
- name: Validate all worker manifests
  run: |
    for worker in auth-worker users-worker character-worker ...; do
      kustomize build "workloads/domains/${worker}/dev" > /dev/null || exit 1
    done

Kustomize 빌드가 실패하면 워커 Quality Gate 자체가 실행되지 않습니다.
인프라 매니페스트의 정합성까지 결정론적으로 검증하는 구조입니다.

2.4 그럼에도 남았던 확률적 영역

CI Quality Gate가 결정론적이었음에도, 에이전트에게 위임하기 어려운 영역이 남아 있었습니다.

코드 포맷 (Black)	O	O	O
린트 (Ruff)	O	O	O
유닛 테스트 (Pytest)	O	O	O
매니페스트 정합성 (kustomize)	O	O	O
부하 테스트 (k6)	O	수동 트리거	부분적
LLM 응답 품질 (Chat Agent)	X	X	X (핵심 한계)
Vision AI 분류 정확도 (Scan)	X	X	X
프론트엔드 연동	X	X	X

 

코드 품질의 "바닥"은 CI가 보장했지만, LLM 기반 서비스의 응답 품질은 여전히 확률적이었습니다. Chat Agent가 사용자의 분리배출 질문에 정확한 답변을 하는지, Vision AI가 폐기물을 올바르게 분류하는지는 exit code 0으로 판정할 수 없는 영역이었습니다.

이는 이후 Swiss-cheese Model을 베이스로 한 Eval Pipeline으로 품질 평가 지표를 수립했으나, 이 역시 완전 무결한 가드레일이라 보긴 어렵습니다.

2.5 Observability 기반 재귀개선루프

이코에코의 또 하나의 특징은 Observability 데이터를 기반으로 한 재귀개선루프입니다.
단순히 CI로 코드를 검증하는 것에 그치지 않고, 배포 후의 E2E 운영 데이터를 수집하여 다음 개발 사이클의 컨택스트로 활용했습니다.

Observability 스택
├── Metrics:    Prometheus + Grafana (리소스 사용량, 응답 시간, RPS)
├── Logging:    ECK 기반 EFK (Elasticsearch + Fluent Bit + Kibana)
├── Tracing:    OpenTelemetry + Jaeger (분산 트레이싱)
├── Mesh:       Kiali (Istio 서비스 메시 시각화)
├── LLM:        LangSmith (에이전트 트레이스, 비용, 토큰 사용량)
└── Load Test:  k6 (VU 시나리오 부하 테스트)

이 스택이 형성하는 루프는 다음과 같습니다.

┌──────────────────────────────────────────────────────────┐
│  1. 배포 (ArgoCD Sync)                                    │
│     │                                                    │
│     ▼                                                    │
│  2. 관측 (Grafana 대시보드, k6 부하 테스트)                │
│     │                                                    │
│     ▼                                                    │
│  3. 병목 식별 (정량 데이터 기반)                           │
│     │                                                    │
│     ▼                                                    │
│  4. 개선 논의 + 구현                                      │
│     │                                                    │
│     ▼                                                    │
│  5. CI Quality Gate 통과 → 재배포 → 1번으로               │
└──────────────────────────────────────────────────────────┘

실제로 이 루프가 작동한 사례가 있습니다.

1차 (12월)	k6 500 VU	SSE Gateway 연결 O(N) 팬아웃	Redis Pub/Sub 도입	500 VU SLA 확보
2차 (12월)	k6 600 VU	포화 지점 도달	Event Relay 3-Tier 아키텍처 (Streams + Pub/Sub + State KV)	600 VU 포화 지점 확인
3차 (1월)	k6 1000 VU	SSE Gateway Pub/Sub 채널 구독 O(N)	Shard 최적화 O(N)→O(4)	1000 VU 97.8% 완료율, 373 RPM

이 루프의 핵심은 관측 데이터가 정량적이라는 점입니다. "느린 것 같다"가 아니라 "p95 응답시간 173s, 완료율 97.8%"라는 수치가 다음 사이클의 입력이 됩니다. Grafana 스냅샷이 공유되고, 수치를 기반으로 병목을 논의하고, 개선 후 동일 부하를 다시 걸어 정량적으로 비교합니다. 확률적 판단이 아니라 계측 데이터에 기반한 루프입니다.

2.6 이코에코의 접근 방식 정리

이코에코의 구조를 정리하면, CI 래칫(결정론적) + Observability 재귀루프(정량적) + Knowledge Base(확률적)의 3중 구조입니다.

결정론적 계층:  CI Quality Gate (Black + Ruff + Pytest + kustomize)
               → 코드 품질의 바닥을 보장

정량적 계층:    Observability (Prometheus/Grafana/k6/LangSmith)
               → 배포 후 성능 병목을 수치로 식별, 재귀개선루프 구동

확률적 계층:    Knowledge Base (76편) + 27 Skills + Sub agent 주입
               → 에이전트의 평균 판단 품질을 높임

이 구조에서 KB는 에이전트에게 "이렇게 하는 것이 좋다"고 알려주지만, "이것을 어기면 커밋을 차단한다"고 강제하지는 않습니다. CI는 강제하지만 LLM 응답 품질까지 커버하지는 못합니다. Observability는 커버하지만 실시간 차단이 아닌 사후 분석입니다. 세 계층이 각각 다른 시점과 범위를 담당합니다.

---

3. GEODE: Self-Correcting Pipeline과 Confidence Gate

3.1 파이프라인 토폴로지

GEODE는 저평가 IP(Intellectual Property)를 발굴하는 자율 분석 에이전트입니다. 6-Layer Architecture 위에 Self-Correcting Pipeline을 구현했습니다.

START → Router → Signals → Analysts ×4 (Send API, Fan-out)
     → Evaluators ×3 → Scoring (PSM Engine)
     → Verification (G1-G4 + BiasBuster)
     → [confidence >= 0.7?] → Synthesizer → END
                              → Gather (loopback, max 5 iter)

핵심은 Verification → confidence gate → loopback 구조입니다.

파이프라인이 스스로 자신의 출력을 검증하고, 기준 미달이면 다시 데이터를 수집합니다.

3.2 Guardrails G1-G4: 결정론적 검문소

GEODE의 Verification 노드는 4개의 가드레일을 순서대로 실행합니다.

G1 Schema	출력 JSON이 Pydantic 모델에 적합한가	O (스키마 검증)
G2 Range	점수가 유효 범위(0-100) 내인가	O (수치 비교)
G3 Grounding	근거 문장이 입력 데이터에 존재하는가	부분적 (문자열 매칭)
G4 Consistency	분석가 간 점수 편차가 2σ 이내인가	O (통계 계산)

# core/verification/guardrails.py (GEODE)
def verify_output(state: GeodeState) -> dict:
    errors = []
    # G1: Schema — Pydantic 검증
    try:
        EvaluationResult.model_validate(state["evaluation"])
    except ValidationError as e:
        errors.append(f"G1_SCHEMA: {e}")

    # G2: Range — 수치 범위
    for score in state["scores"]:
        if not (0 <= score <= 100):
            errors.append(f"G2_RANGE: {score} out of bounds")

    # G4: Consistency — 2σ 편차
    if np.std(state["analyst_scores"]) > 2 * np.mean(state["analyst_scores"]):
        errors.append("G4_CONSISTENCY: analyst variance exceeds 2σ")

    confidence = 1.0 - (len(errors) / 10)
    return {"errors": errors, "confidence": confidence}

G1과 G2는 완전히 결정론적입니다. 같은 입력에 대해 항상 같은 판정을 내립니다. G3는 부분적으로 결정론적입니다(문자열 매칭은 결정론적이지만, "의미적으로 근거가 있는가"는 LLM 판단이 필요합니다). G4는 통계적이지만 결정론적입니다(표준편차 계산은 동일 입력에 동일 결과).

3.3 Confidence Gate: Self-Correcting의 핵심

confidence = base × (0.7 + 0.3 × confidence / 100)

confidence >= 0.7 → 다음 단계(Synthesizer)로 전진
confidence <  0.7 → GATHER로 loopback (max 5 iterations)

이 구조가 GEODE에서의 "래칫"입니다. 품질이 기준 미만이면 전진할 수 없습니다. 하지만 아직 완전한 래칫은 아니었습니다. 왜냐하면:

1. loopback에 상한이 있습니다 (max 5 iterations). 5회를 넘기면 현재 상태로 진행합니다.
2. 검증 대상이 LLM 출력입니다. LLM 출력의 품질은 확률적이므로, loopback해도 반드시 개선되는 보장은 없습니다.
3. 불변 기준선(invariant baseline)이 없습니다. Karpathy의 prepare.py처럼 "절대 변하지 않는 평가 기준"이 코드화되어 있지 않습니다.

GEODE의 Self-Correcting Pipeline은 래칫의 정신을 구현했지만, 결정론적 강제력은 부족했습니다. GEODE의 접근 방식은 "LLM 출력의 품질을 LLM이 판단한다"는 구조이며, 이 특성이 GEODE를 GEODE답게 만드는 동시에 한계이기도 합니다.

3.4 GEODE에서 배운 것

결정론적 검증 = 위임의 전제조건	G1/G2/G4처럼 결정론적인 검증만이 에이전트 자율 실행을 보장
LLM 판단은 가드레일이 아니다	"코드가 좋아 보인다"는 exit code 0이 아니다
Bounded loop > Unbounded loop	max 5 iterations 같은 상한이 없으면 무한 루프 위험
Port/Adapter = 검증 교체 가능성	Protocol 기반 DI 덕분에 검증 로직을 교체할 수 있었음

---

4. REODE: 3계층 래칫으로 대단위 자율 실행

4.1 REODE의 도메인: 코드 마이그레이션

REODE는 GEODE의 R&D 포크로 범용 에이전트는 공유하나, 마이그레이션 포팅 DAG(Plug-in)으로 설계 및 구현 중입니다.

GEODE: DomainPort Protocol → 게임 IP 파이프라인 (도메인 특화)
REODE: PipelineTemplate + LanguageAdapter Protocol → 범용 (도메인 무관)

PipelineTemplate (L1): workflow topology
  ├── MigrationPipeline: ASSESS → PLAN → TRANSFORM → VALIDATE → MEASURE
  ├── PortingPipeline: ANALYZE → MAP_TYPES → GENERATE → VERIFY
  └── ReviewPipeline: SCAN → ANALYZE → REPORT → FIX

LanguageAdapter (L2): language-specific knowledge + tools
  ├── JavaAdapter: OpenRewrite, mvn, jdeps, Spring/MyBatis skills
  ├── GoAdapter: go build/test/vet, Go idiom skills
  └── PythonAdapter: ruff, pytest, FastAPI skills

REODE의 특성은 검증 대상이 코드의 빌드와 테스트 결과라는 점입니다. GEODE는 LLM 출력(분석 텍스트, 점수)을 검증하지만, REODE는 mvn compile의 종료 코드를 검증합니다. 도메인이 다르기 때문에 결정론적 검증이 가능한 범위도 다릅니다.

4.2 3계층 래칫 아키텍처

REODE는 세 계층의 래칫을 직렬로 중첩합니다.

┌─────────────────────────────────────────────────────────┐
│  L3: Ground Truth 래칫                                   │
│  "변환 전에 무엇이 바뀌는지 알고 있는가?"                 │
│  → javaalmanac.io API diff + OpenRewrite 레시피 확인       │
│  → 통과해야 코드 변환 시작 가능                           │
├─────────────────────────────────────────────────────────┤
│  L2: 코드 변환 래칫                                      │
│  "변환 후에 빌드와 테스트가 통과하는가?"                  │
│  → mvn compile + mvn test + coverage 확인                │
│  → 통과해야 git commit 가능                              │
├─────────────────────────────────────────────────────────┤
│  L1: CI 래칫                                             │
│  "GitHub Actions가 통과했는가?"                           │
│  → gh pr checks --watch                                  │
│  → 통과해야 gh pr merge 가능                             │
└─────────────────────────────────────────────────────────┘

각 계층의 검증은 온전히 결정론적입니다.

L3 Ground Truth	API diff 존재 + 레시피 확인	O (외부 API 조회 결과)	수 초
L2 코드 변환	exit code 0 (빌드) + 테스트 통과	O (바이너리 판정)	수 분
L1 CI	gh pr checks 전부 pass	O (GitHub API 응답)	수 분 ~ 수십 분

4.3 시스템 프롬프트 레벨 강제

래칫 규칙은 에이전트의 시스템 프롬프트(router.md)와 스킬 파일에 하드코딩됩니다.

## Ratchet-based completion for coding tasks

When performing code transformations:
1. After each modification → run build (mvn compile / go build / ruff check)
2. Build pass → run tests (mvn test / pytest / go test)
3. Tests pass → commit and report success
4. Any failure → rollback change, report the failure, suggest next action
5. Never skip validation steps.

4.4 가드레일 상세: G1-G4

래칫 검증의 구체적인 기준입니다.

가드레일	검증 내용	실패 시	왜 필요한가
G1 Build	mvn compile 성공	롤백	컴파일 불가 코드는 이후 모든 단계를 무의미하게 만듦
G2 Test	mvn test 통과	롤백	기능 회귀 방지
G3 Coverage	커버리지 5% 이상 하락 금지	롤백	에이전트가 테스트 없이 코드만 추가하는 것 방지
G4 No-Delete	테스트 파일 삭제 금지	롤백 + 경고	Reward Hacking 방지

G4는 특별한 주의가 필요합니다. 에이전트는 "목표를 달성하기 위한 최단 경로"를 찾습니다. 그리고 "실패하는 테스트를 삭제하면 테스트가 통과한다"는 것은 논리적으로 옳은 최단 경로입니다. 이것이 Reward Hacking이며, G4가 이를 원천 차단합니다.

에이전트의 안티패턴 목록 (실제 관측):

1. 테스트 파일 삭제    → G4 차단
2. @Ignore 어노테이션  → G4 확장: 비활성화 감지
3. surefire exclude    → G4 확장: exclude 추가 감지
4. coverage 임계값 하향 → pyproject.toml 변경 감지
5. CI 미확인 merge     → L1 래칫: gh pr checks --watch 필수

안티패턴 목록은 개발 중 발견된 것입니다. 래칫 설계의 가장 어려운 부분은 에이전트가 래칫을 우회하는 창의적인 방법을 예측하는 것입니다. 매번 새로운 안티패턴이 발견될 때마다 가드레일을 추가합니다. 한 번 발견된 우회 경로는 다시는 열리지 않도록 강제합니다.

4.5 세 프로젝트의 접근 방식 비교

세 프로젝트의 검증 방식을 나란히 놓으면 각각의 특성이 드러납니다.

이코에코: CI Quality Gate (Black+Ruff+Pytest) → 코드 품질 바닥 보장
          + KB/Skills (확률적) → LLM 판단 평균 품질 향상
          ┗━ 에이전트 개발 단위: 도메인 API 1개

GEODE:    Confidence Gate → confidence >= 0.7 → 전진
          ┗━ 에이전트 개발 단위: 파이프라인 노드 1개

REODE:    3-Layer Ratchet → exit code 0 → commit → CI pass → merge
          ┗━ 에이전트 개발 단위: 모듈 단위 마이그레이션

회고하면, 세 프로젝트는 "무엇을 결정론적으로 검증할 수 있는가"의 범위가 다릅니다. 이코에코는 코드 품질과 인프라 성능을 결정론적으로 잡되 LLM 응답은 Observability로 사후 추적합니다. GEODE는 LLM 출력 자체에 정량적 게이트를 걸지만, 그 게이트의 판정이 확률적입니다. REODE는 검증 대상을 "빌드/테스트 결과"라는 결정론적 영역으로 옮겨서 전체 행동 루프를 제어합니다. 각각의 도메인이 허용하는 결정론적 검증의 범위가 곧 에이전트 위임 단위의 크기를 결정합니다.

---

5. Karpathy의 autoresearch: 밤새 100+ 실험이 가능한 구조

5.1 autoresearch의 접근 방식

2026년 3월, Andrej Karpathy가 공개한 autoresearch는 개발 단위의 다른 극단을 보여줍니다.
파일 3개, train.py 약 630줄. 단일 H100 GPU에서 에이전트가 밤새 100+ ML 실험을 자율 수행합니다.

autoresearch/
├── prepare.py      # 데이터 + 평가 (불변)
├── train.py        # 모델 + 학습 (~630줄, 에이전트가 수정)
├── program.md      # 에이전트 지시서 (인간이 작성)
├── run.log         # 학습 출력 리다이렉트
└── .git/           # 실험 기록 저장소

여기서 주목해야 할 것은 prepare.py가 불변이라는 점입니다.

5.2 불변 영역과 가변 영역의 분리

┌─────────────────────────────────────────────────────┐
│ 불변 영역 (prepare.py)                                │
│   데이터 전처리 + 토크나이저 + 검증 셋                │
│   → 평가의 공정성 보장                                │
│   → 모든 실험이 동일 조건에서 평가됨                  │
│   → val_bpb 비교가 의미를 가짐                        │
├─────────────────────────────────────────────────────┤
│ 가변 영역 (train.py)                                  │
│   모델 아키텍처 + 하이퍼파라미터 + 옵티마이저          │
│   → 에이전트의 유일한 탐색 대상                       │
│   → ~630줄 = LLM 컨텍스트에 전체가 들어감             │
├─────────────────────────────────────────────────────┤
│ 제어 영역 (program.md)                                │
│   실험 프로토콜 + 판정 기준 + 래칫 규칙               │
│   → 인간이 관리                                       │
│   → "단일 진실의 원천(Single Source of Identity)"       │
└─────────────────────────────────────────────────────┘

prepare.py의 불변성이 래칫을 가능하게 합니다. "이 변경이 정말 개선인가?"를 판정하려면, 판정 기준 자체가 바뀌지 않아야 합니다. 축구에서 골대가 경기 중에 움직이면 득점 판정이 불가능한 것과 같습니다.

5.3 Git = 실험 트래커

autoresearch에서 Git은 버전 관리 도구가 아니라 실험 트래커입니다.

1. 가설 수립 (program.md 참조)
2. train.py 수정
3. python train.py > run.log 2>&1
4. val_bpb 확인 (grep "val_bpb" run.log)
5. val_bpb 개선 → git commit → 다음 가설
   val_bpb 악화 → git checkout -- train.py → 1번으로

이것은 REODE의 L2 코드 변환 래칫과 동형(isomorphic)입니다.

가변 대상	train.py	target_project/*.java
불변 기준	prepare.py (val_bpb)	기존 테스트 스위트
성공 판정	val_bpb 개선	exit code 0 (빌드 + 테스트)
실패 시	git checkout -- train.py	git checkout -- .
기록	git commit	git commit
제어	program.md	router.md (시스템 프롬프트)

5.4 Karpathy 10대 설계 원칙에서 추출한 교훈

autoresearch와 AgentHub에서 추출한 원칙 중, REODE에 직접 적용한 것들을 정리합니다.

P1 단일 파일 제약	에이전트가 수정하는 파일은 하나	PipelineTemplate 단위 격리
P2 program.md = 정체성	프롬프트 품질 = 에이전트 품질	router.md에 래칫 규칙 하드코딩
P3 고정 시간 예산	8시간 자율 실행 후 결과 확인	subagent_max_rounds=10, timeout_s=120
P4 래칫	품질은 절대 후퇴 불가	3계층 래칫
P5 Dumb Platform	인프라는 단순하게	Git = 실험 트래커, CI = 머지 게이트
P7 Context Budget	stdout 리다이렉트 + grep 추출	Token Guard (4096 tokens)

P5 "Dumb Platform" 원칙은 중요한 시사점을 제공합니다. MLflow, Weights & Biases 같은 전용 실험 트래커 대신 Git을 가드레일로 사용하는 이유는 에이전트가 이미 Git을 알고 있기 때문입니다. 에이전트에게 새로운 API를 가르치는 비용보다, 이미 아는 도구를 활용하는 것이 Context Budget 관점에서 효율적입니다.

---

6. 결정론적 가드레일의 설계 원칙

세 프로젝트를 회고하며 정리한 가드레일 설계 원칙입니다.

원칙 1: 검증은 결정론적이어야 한다

결정론적: mvn compile → exit code 0 or 1 (항상 동일 입력 → 동일 결과)
확률적:   "이 코드가 좋아 보이나요?" → LLM에 따라 다름

에이전트의 자율 실행 범위는 결정론적 검증의 범위와 정비례합니다.

원칙 2: 불변 기준선(Invariant Baseline)을 확보하라

autoresearch: prepare.py (불변) vs train.py (가변)
REODE:        기존 테스트 스위트 (불변) vs 변환 코드 (가변)
GEODE:        Pydantic 스키마 (불변) vs LLM 출력 (가변)

무엇이 바뀌고 무엇이 바뀌지 않는지를 명확히 분리해야 합니다. 기준선이 흔들리면 래칫이 무의미합니다.

원칙 3: 시스템 프롬프트에 규칙을 하드코딩하라

에이전트의 행동 규칙은 코드가 아니라 프롬프트에 있습니다. 따라서 래칫 규칙도 프롬프트에 명시해야 합니다. 코드에만 래칫을 구현하면, 에이전트가 "그 코드를 수정"하는 것으로 래칫을 우회할 수 있습니다.

규칙의 강제력 계층:

1. 인프라 강제 (CI gate job)      → 우회 불가
2. 시스템 프롬프트 명시           → 우회 매우 어려움
3. Skills 파일 참조               → 우회 가능 (참조 안 할 수 있음)
4. 구두 지시                      → 우회 쉬움 (맥락에서 사라짐)

원칙 4: 안티패턴 카탈로그를 유지하라

에이전트가 래칫을 우회하는 방법은 창의적입니다. 발견된 우회 경로를 카탈로그로 유지하고, 각 항목에 대응하는 가드레일을 추가합니다.

테스트 삭제	실패 테스트가 없으면 통과	G4: 테스트 파일 삭제 감지
@Ignore 추가	비활성화하면 실패 안 함	G4 확장: 어노테이션 감지
커버리지 임계값 하향	기준을 낮추면 통과	설정 파일 변경 감지
CI 스킵 (--no-verify)	검증을 건너뛰면 빠름	CI gate job 필수
LLM 지식만으로 판단	"Java 17에서 X 제거됨"	Ground Truth Gate 필수

이 카탈로그 자체가 래칫입니다. 한 번 발견된 우회 경로는 영구적으로 차단됩니다. 카탈로그가 커질수록 에이전트의 행동 공간은 좁아지지만, 그 좁아진 공간 안에서의 자유도는 커집니다. 역설적이지만, 제약이 자유를 만듭니다.

원칙 5: 개발 단위 = f(검증 신뢰도, 롤백 비용)

에이전트에게 위임할 수 있는 개발 단위의 크기는 두 변수의 함수입니다.

위임 단위 크기 ∝ 검증 신뢰도 / 롤백 비용

검증 신뢰도: 결정론적 검증일수록 높음
롤백 비용:   git checkout이면 낮음, DB 스키마 변경이면 높음

코드 변환 + 테스트 존재	높음	낮음 (git)	모듈 단위
DB 마이그레이션	중간	높음	테이블 1개
프론트엔드 UI 변경	낮음 (시각적)	낮음 (git)	컴포넌트 1개
인프라 변경 (Terraform)	높음 (plan)	높음	리소스 1개

---

7. 마무리

핵심 정리

핵심 주장	결정론적 검증이 강할수록 에이전트에게 큰 단위를 위임할 수 있다
이코에코의 특성	CI Quality Gate + Observability 재귀루프 + KB. 코드 바닥과 성능은 정량적으로 제어, LLM 응답은 확률적 보완
GEODE의 특성	Self-Correcting Pipeline + Confidence Gate. LLM 출력에 정량적 게이트를 걸되, 판정 자체는 확률적
REODE의 특성	3계층 래칫 (Ground Truth → Build+Test → CI). 검증 대상을 빌드/테스트로 옮겨 전체 루프 결정론적 제어
autoresearch의 특성	불변 기준선(prepare.py) + 단일 파일 제약 + Git 래칫. 밤새 자율 실험 가능
가드레일 핵심	검증은 결정론적, 기준선은 불변, 규칙은 프롬프트에 하드코딩
역설	제약이 자유를 만든다. 안티패턴 차단이 안전한 자율 범위를 확장한다

세 프로젝트 비교

이코에코 (2025)            GEODE (2025)           REODE (2026)
  24 클러스터 노드            142 모듈               127 모듈
  8 도메인 API                2520+ 테스트            1696 테스트
  9 CI 워크플로우              Self-Correcting         3계층 래칫
  7500+ 도구 호출              Pipeline

  CI Quality Gate           Confidence Gate        Deterministic Ratchet
  + Observability 재귀루프  "confidence >= 0.7"    "exit code 0"
  + KB (확률적 보완)
                            LLM 출력에              빌드/테스트 결과에
  코드/인프라 품질에         정량적 게이트            결정론적 게이트
  결정론적 게이트

체크리스트

• 시스템 프롬프트에 래칫 완료 기준이 명시되어 있는가
• 불변 기준선(테스트 스위트, 스키마, prepare.py)이 확보되어 있는가
• 가드레일이 결정론적 판정(exit code, 스키마 검증, 수치 비교)을 사용하는가
• 안티패턴 카탈로그가 운영 경험을 반영하여 업데이트되고 있는가
• CI gate job이 모든 check의 성공을 요구하는가
• 에이전트의 위임 단위가 검증 신뢰도와 롤백 비용에 비례하여 설정되어 있는가
• Ground Truth Gate가 LLM 지식 단독 판단을 차단하는가

참고 자료

• Karpathy, "autoresearch" (2026) — P4 Ratchet 원칙, 3-file structure
• Karpathy, "AgentHub" — Agent-native Git DAG, Branchless workflow
• 이코에코 Backend Portfolio — Agent-Driven Development, 27 Skills, 7500+ Task 호출
• GEODE Portfolio — 6-Layer Architecture, Self-Correcting Pipeline, Guardrails G1-G4
• REODE CLAUDE.md — 3-Layer Hybrid Architecture, PipelineTemplate + LanguageAdapter
• SWE-bench Pro (Scale AI) — 멀티파일 리팩토링 성공률 45.9%