구현 수준별 로드맵

왜 단계적 도입이 중요한가?

Agent Harness를 처음 도입할 때 가장 흔한 실수는 처음부터 완벽한 시스템을 만들려는 것입니다. 5인 스타트업에 대기업 수준의 거버넌스를 적용하면 오히려 속도가 저하됩니다. 반대로 100명 조직이 개인 수준의 비공식 설정만 유지하면 일관성과 안전성 모두를 잃습니다.

조직 규모와 성숙도에 따른 3단계 구현 로드맵을 살펴보겠습니다. 각 단계는 명확한 셋업 시간과 기대 성과가 있습니다.

Level 1: 개인 개발자 (1~2시간)

혼자 작업하거나 소규모 사이드 프로젝트를 운영하는 경우의 최소 구성입니다.

핵심 구성 요소

| 구성 요소 | 설명 | 예시 | |---|---|---| | CLAUDE.md / .cursorrules | 에이전트 행동 지침 파일 | 코딩 스타일, 금지 패턴 | | Pre-commit hooks | 커밋 전 자동 검증 | lint, type-check, test | | 자체 검증 테스트 | 에이전트가 스스로 확인 가능한 테스트 | 단위 테스트 + CI | | 네이밍 컨벤션 | 파일/함수 명명 규칙 문서화 | README.md 내 섹션 |

셋업 체크리스트

[ ] CLAUDE.md 생성 — 프로젝트 목적, 기술 스택, 금지 패턴 기술
[ ] .pre-commit-config.yaml 설정
[ ] 기본 단위 테스트 작성 (핵심 함수 커버리지 60%+)
[ ] 에디터별 .cursorrules 또는 .windsurfrules 추가

기대 성과

에이전트 오류율 30~40% 감소
재작업 빈도 감소 (잘못된 스타일의 코드 생성 최소화)
셋업 비용 대비 즉각적인 ROI

Level 1 위험 요소와 완화 전략

Level 1에서 가장 흔히 발생하는 문제는 CLAUDE.md 가 점점 길어지면서 에이전트가 전체 내용을 무시하게 되는 현상입니다.

| 위험 요소 | 증상 | 완화 전략 | |---|---|---| | 지침 비대화 | CLAUDE.md가 500줄 이상으로 증가 | 핵심 규칙 10개로 제한, 나머지는 링크 | | 테스트 미작성 | 에이전트가 테스트 없이 코드만 생성 | pre-commit에서 커버리지 임계치 강제 | | 지침 형식 불일치 | 에이전트가 규칙을 다르게 해석 | 긍정문(“사용할 것”)으로 작성, 예시 포함 |

Level 2: 소규모 팀 (1~2일, 3~10명)

팀이 같은 에이전트를 공유하거나, 동일한 코드베이스에서 여러 명이 에이전트를 활용하는 경우입니다.

핵심 구성 요소

| 구성 요소 | 설명 | 우선순위 | |---|---|---| | AGENTS.md | 팀 전체 에이전트 컨벤션 문서 | 최우선 | | CI-enforced 제약 | GitHub Actions로 규칙 강제 적용 | 높음 | | 공유 프롬프트 템플릿 | 재사용 가능한 프롬프트 라이브러리 | 중간 | | 문서-as-코드 린팅 | Markdown/MDX 자동 검증 | 중간 | | 에이전트별 리뷰 체크리스트 | PR 리뷰 시 에이전트 코드 검토 기준 | 높음 |

AGENTS.md 기본 구조

## 팀 컨벤션
- 언어: TypeScript strict mode
- 패키지 매니저: pnpm
- 테스트: Vitest + Testing Library

## 금지 패턴
- console.log 커밋 금지 (logger 사용)
- any 타입 사용 금지
- 직접 DOM 조작 금지

## 에이전트 권한 범위
- 읽기: src/, tests/
- 쓰기: src/, tests/
- 실행 금지: production DB, 외부 API (mock 사용)

## 리뷰 체크리스트
- [ ] 타입 안전성 확인
- [ ] 테스트 커버리지 확인
- [ ] 에러 핸들링 존재 여부

팀 구조 권장사항

Level 2에서는 에이전트 사용에 대한 명시적인 역할 분담이 필요합니다.

팀 리드 (1명)
  └── AGENTS.md 유지 관리
  └── CI 파이프라인 관리
  └── 에이전트 사용 가이드라인 업데이트

개발자 (2~9명)
  └── 로컬에서 에이전트 활용
  └── 발견한 패턴 AGENTS.md에 기여
  └── 에이전트 생성 코드 PR 리뷰

팀 리드가 AGENTS.md를 단독으로 관리하는 것보다, 모든 팀원이 Pull Request를 통해 기여하는 구조가 문서를 살아있게 유지합니다.

Level 2 마일스톤별 성공 지표

| 마일스톤 | 목표 지표 | 측정 방법 | |---|---|---| | 1주차: AGENTS.md 배포 | 팀원 100% 인지 | 팀 회의에서 확인 | | 2주차: CI 통합 | 에이전트 관련 린트 오류 50% 감소 | CI 로그 분석 | | 1개월: 프롬프트 라이브러리 | 반복 프롬프트 재사용률 70%+ | 프롬프트 사용 추적 | | 3개월: 안정화 | 에이전트 관련 버그 80% 감소 | 버그 트래커 태깅 |

기대 성과

팀 전체 에이전트 출력 일관성 확보
신규 팀원 온보딩 시간 50% 단축 (에이전트가 컨벤션을 자동 학습)
코드 리뷰 시간 감소 (에이전트가 기준을 미리 지킴)

Level 3: 프로덕션 조직 (1~2주, 대규모)

수십 명 이상의 엔지니어가 에이전트를 활용하는 조직 수준의 구성입니다.

핵심 구성 요소

| 구성 요소 | 설명 | |---|---| | 커스텀 미들웨어 레이어 | 조직 전용 도구 통합, 인증, 로깅 | | 옵저버빌리티 통합 | Langfuse, OpenTelemetry 기반 전 흐름 추적 | | 엔트로피 관리 에이전트 | 기술 부채 탐지 및 정리를 자동화하는 스케줄 에이전트 | | 하네스 버저닝 & A/B 테스팅 | 프롬프트/도구 변경의 영향을 실험적으로 측정 | | 성능 대시보드 | 에이전트별 성공률, 비용, 지연 시간 모니터링 | | 에스컬레이션 정책 | 에이전트 실패 시 인간 개입 트리거 정책 |

조직 수준 체크리스트

[ ] 중앙화된 AGENTS.md 저장소 (Git submodule 또는 모노레포)
[ ] 에이전트 행동 감사 로그 (최소 30일 보존)
[ ] 모델 라우팅 정책 (Haiku/Sonnet/Opus 자동 선택)
[ ] 비용 예산 알람 (일/주 단위)
[ ] 에스컬레이션 Runbook 문서화
[ ] 하네스 버전 변경 시 카나리 배포 프로세스

조직 팀 구조

Level 3에서는 에이전트 플랫폼을 담당하는 전담 팀이 필요합니다.

Agent Platform Team (2~4명)
  ├── Harness Core 개발 및 유지보수
  ├── 옵저버빌리티 파이프라인 운영
  ├── 모델 라우팅 정책 관리
  └── 조직 전체 AGENTS.md 거버넌스

Feature Teams (N개 팀)
  ├── 플랫폼 팀이 제공하는 harness SDK 소비
  ├── 팀별 AGENTS.md 작성 (조직 표준 상속)
  └── 에이전트 관련 기능 개발

이 구조는 플랫폼 팀과 피처 팀의 책임을 명확히 분리합니다. 플랫폼 팀이 인프라를 제공하면, 피처 팀은 비즈니스 로직에 집중할 수 있습니다.

단계별 위험 완화 전략

Level 3 도입 시 각 단계에서 발생할 수 있는 위험과 완화 방법입니다.

| 도입 단계 | 주요 위험 | 완화 전략 | |---|---|---| | 옵저버빌리티 구축 | 과도한 로깅으로 비용 폭증 | 샘플링 비율 설정 (초기 10%) | | A/B 테스팅 도입 | 실험 관리 복잡도 증가 | 동시 실험 최대 3개로 제한 | | 모델 라우팅 | 라우팅 오류로 인한 품질 저하 | 폴백 정책 필수 설정 | | 에스컬레이션 정책 | 알람 피로(alert fatigue) | 임계치를 점진적으로 조정 | | 카나리 배포 | 변경 영향 범위 불명확 | 트래픽 5% → 20% → 100% 단계적 확대 |

단계 진화 기준

어떤 시점에 다음 Level로 이동해야 할까요?

| 전환 신호 | Level 1 → 2 | Level 2 → 3 | |---|---|---| | 팀 규모 | 2명 이상 협업 시작 | 에이전트 전담 팀 필요 시 | | 장애 빈도 | 주 1회 이상 에이전트 오류 | 에이전트 장애가 프로덕션 영향 | | 비용 | 월 $100+ 에이전트 비용 | 월 $1,000+ 에이전트 비용 | | 복잡도 | 단일 프로젝트 초과 | 다수 팀/서비스 에이전트 공유 |

공통 도입 실패 패턴

레벨과 무관하게 반복적으로 나타나는 실패 패턴이 있습니다.

1. 지침 문서 방치: CLAUDE.md 를 한 번 작성하고 업데이트하지 않으면, 코드베이스가 바뀌어도 에이전트는 오래된 지침을 따릅니다. 분기마다 한 번씩 검토 일정을 캘린더에 등록하세요.

2. 에이전트 결과물 무비판 수용: 에이전트가 생성한 코드를 검토 없이 머지하면 기술 부채가 빠르게 축적됩니다. 에이전트 생성 코드도 동일한 PR 리뷰 프로세스를 거쳐야 합니다.

3. 과도한 제약: 너무 많은 금지 규칙이 있으면 에이전트가 단순한 작업도 거부하거나 주저합니다. 규칙은 “왜 이것이 금지인가”의 이유와 함께 작성해야 에이전트가 맥락을 이해하고 유연하게 대응합니다.

요약

Agent Harness 도입은 한 번에 완성하는 것이 아니라 점진적으로 성장시키는 여정입니다. Level 1의 CLAUDE.md 하나가 이미 큰 차이를 만들 수 있습니다. 현재 위치를 정확히 파악하고, 그에 맞는 수준에서 시작하세요.