2026. 9. 1. 19:13ㆍDEV/A.I.
[AI Architecture] 나름대로 AI 에이전트 하네스 & 거버넌스 PoC
최근 AI 기반 코딩 도구(Cursor, Claude Code, Copilot 등)를 개발 워크플로우에 도입하면서 느끼는 공통적인 고민이 있습니다.
초반에는 분명 생산성이 비약적으로 상승하지만, 프로젝트 규모가 커질수록 컨텍스트 오염으로 인한 환각, 기존 정상 코드를 덮어쓰는 회귀(Regression) 버그, 그리고 린트 및 테스트 실패를 잡기 위해 토큰을 끝없이 낭비하는 무한 루프 현상을 마주하게 됩니다.
개발자마다 선호하는 작업 환경(IDE 화면, CLI 에이전트, 백엔드 파이프라인 등)이 다르고, AI 엔지니어링 트렌드 역시 하루가 다르게 급변하고 있습니다. 완벽한 단 하나의 정답을 정의할 수는 없겠지만, 어떤 프로젝트에서든 베이스라인으로 가져갈 수 있는 '상태 그래프 기반 AI 에이전트 하네스(Harness) 공통 거버넌스 PoC'를 직접 설계해 보았습니다.
1. 왜 "하네스(Harness)"와 "상태 그래프"인가?
AI에게 단순히 *"이 기능 구현해줘"_라고 지시하는 단발성 프롬프트 방식은 프로젝트 규모가 커질수록 실패할 확률이 높습니다. AI가 자의적으로 행동하지 못하도록 환경을 통제하는 *_하네스(Harness)와 정해진 규칙에 따라서만 다음 단계로 넘어가는 **상태 머신(State Machine)이 필요합니다.
📌 핵심 설계 철학
- Reasoning Before Action: 코드를 작성하기 전에 상황 분석과 제약 조건 도출을 강제합니다.
- Deterministic TDD Anchor: AI의 "완성했다"는 말 대신
pytest/jest의 통과 여부로만 완료를 판단합니다. - Least Privilege Tooling: 분석 단계에서는 '읽기'만, 구현 단계에서는 '패치'만 가능하도록 도구 권한을 엄격히 격리합니다.
- Context Compaction: 이전 페이즈의 대화 찌꺼기를 날리고, 승인된 표준 산출물(Artifact)만 다음 단계로 넘겨 컨텍스트 오염을 막습니다.
2. 초기 런타임 & 모델 거버넌스 (Phase 0: Layered Setup)
프로젝트마다 요구하는 자동화 수준과 비용 예산이 다릅니다. 따라서 파이프라인 기동 시 2단계 계층형 질문을 통해 거버넌스 정책을 확정하도록 설계했습니다.
================================================================================
[Phase 0: Interactive Governance Setup]
================================================================================
[Step 1] 작업 런타임 환경 선택 (Runtime Environment)
(1) Autonomous Pipeline Native (오케스트레이터가 전면 자동 제어)
(2) IDE / Assistant Integration (IDE 에디터 화면 내 보조 모드)
[Step 2] 모델 라우팅 및 거버넌스 정책 선택 (Model & Cost Governance)
(1) Full Auto Cascading [권장]
- 분석/설계/테스트: High-Tier 추론 모델 자동 배정
- 린트 수정/단순 복구: Light-Tier 모델 자동 스위칭 (비용 최적화)
(2) Fixed High-Performance
- 전 페이즈 High-Tier 모델 고정 운용
(3) Custom Granular Control
- 페이즈별 모델을 사용자가 직접 수동 매핑
================================================================================3. 전체 파이프라인 아키텍처 (State-Graph Workflow)
전체 워크플로우는 분석 → 계획(HITL 승인) → TDD 루프(Red-Green-Refactor) → 검증의 단계로 흐릅니다.
[Task Request]
│
▼
[Phase 0: Layered Setup] ──────────▶ (환경/모델 정책 확정)
│
▼
[Phase 1: Analysis & Spec] ────────▶ (Read-Only AST/검색으로 제약조건 도출)
│
▼
[Phase 2: Planning] ───────────────▶ [HITL: 사용자 설계 승인]
│
▼
┌────────────────── [ Deterministic TDD Loop ] ──────────────────┐
│ │
│ [Phase 3A: Red Test] │
│ │ ──▶ (Fail 검증: 실패하지 않는 가짜 테스트 반려) │
│ ▼ │
│ [Phase 3B: Green Code] │
│ │ ──▶ 신규 파일: create_file / 기존 파일: apply_patch │
│ ▼ │
│ [Phase 3C: Linter & Type Check] │
│ │ ──▶ Lint 실패 시: Light-Tier 모델로 즉시 자가 수정 │
│ ▼ │
│ [Run Test in Docker Sandbox] │
│ │ ──▶ 3회 실패/예산 초과 시: Git Worktree 롤백 & HITL │
│ ▼ (Test Pass) │
│ [Phase 3D: Refactor] │
│ │ ──▶ 코드 클린업 후 회귀(Regression) 테스트 100% 검증 │
│ │
└────────────────────────────────────────────────────────────────┘
│
▼
[Phase 4: Summary & PR] ───────────▶ (Git Diff 요약 및 최종 완료)| 단계 | 역할 및 실행 내용 | 완료 조건 (Exit Gate) |
|---|---|---|
| Phase 0. Setup | 런타임 환경 및 모델 정책 확정 | 설정 파일 생성 완료 |
| Phase 1. Analysis | Read-Only 도구로 영향도 및 제약조건 분석 | analysis.md 산출물 생성 |
| Phase 2. Plan | 세부 태스크 분해 및 TDD 계획 수립 | 사람의 승인 (HITL Gate) |
| Phase 3A. Red Test | 실패하는 테스트 케이스 작성 | 반드시 테스트 실패 (Fail 확인) |
| Phase 3B. Green Code | 신규 파일은 생성, 기존 파일은 Diff 패치 적용 | 린트 통과 및 테스트 100% Pass |
| Phase 3C. Lint Loop | 경량(Light-Tier) 모델로 문법/린트 자가 수정 | 린터/타입체커 0 Error |
| Phase 3D. Refactor | 코드 컨벤션 적용 및 최적화 | 기존 테스트 100% Pass 유지 |
| Phase 4. Summary | 최종 Git Diff 분석 및 PR 산출물 정리 | 리뷰 및 머지 준비 완료 |
4. 실무 안정성을 위한 세부 엔지니어링 기법
1) 조건부 코드 수정 도구 (Full Overwrite 차단)
AI에게 파일 전체를 다시 쓰게 하면 토큰 낭비가 심하고 정상 코드가 날아가는 사고가 빈번합니다.
- 신규 파일:
create_file허용 - 기존 파일:
apply_patch(Git Unified Diff 형식) 강제
2) TDD Red 검증 (가짜 테스트 방지)
AI가 작성한 테스트가 실제 비즈니스 로직 없이도 통과해 버리는 '빈 껍데기 테스트'를 방지하기 위해, 코드를 구현하기 전 테스트 러너 실행 시 반드시 실패(Fail)하는지 기계적으로 확인합니다.
3) 샌드박스 격리 및 Git Worktree 롤백
- Docker 격리: 패키지 충돌이나 포트 점유 등 호스트 머신 오염을 원천 차단하기 위해 테스트는 Docker 컨테이너 내부에서 실행합니다.
- Git Worktree: 복구 루프가 3회 이상 실패하거나 토큰 예산이 초과될 경우, 임시 Worktree를 즉시 폐기하여 1초 만에 초기 정상 상태로 롤백합니다.
5. 마치며 (Next Step)
AI 도구를 단순한 '채팅 상대'로 두면 매번 사람이 수동으로 검증하고 모델을 바꿔줘야 하는 피로감이 남습니다. 하지만 이를 하네스 기반의 상태 그래프로 감싸면, 사람은 핵심 설계 검토(HITL)에만 집중하고 나머지 반복 작업은 파이프라인이 안전하게 처리하게 만들 수 있습니다.
앞으로 실제 백엔드/분산 시스템 프로젝트에 본 PoC 거버넌스를 적용해 보면서 발생하는 트러블슈팅과 비용 최적화 수치도 차근차근 공유해 보겠습니다.