구현 수준별 로드맵

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

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 추가

기대 성과

반복되는 컨벤션 위반의 변화 측정
재작업 빈도 감소 (잘못된 스타일의 코드 생성 최소화)
셋업 비용 대비 즉각적인 ROI

Level 1 위험 요소와 완화 전략

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

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

Level 2: 소규모 팀 (12일, 310명)

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

핵심 구성 요소

구성 요소	설명	우선순위
`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% 감소	버그 트래커 태깅

기대 성과

팀 전체 에이전트 출력 일관성 확보
신규 팀원의 첫 변경 완료 시간과 리뷰 횟수 측정
코드 리뷰 시간 감소 (에이전트가 기준을 미리 지킴)

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% 단계적 확대

장기 작업의 인수인계와 독립 검증

Anthropic의 장기 실행 하네스 사례는 초기 환경을 만드는 단계와 기능별 구현 단계를 분리합니다. 후속 세션이 읽을 기능 목록·진행 기록·실행 명령을 남기고, 테스트로 확인한 기능만 완료 처리합니다.

2026-03-24 후속 사례는 planner·generator·evaluator를 분리하고, 구현 전에 완료 기준을 합의했습니다. 평가자는 실제 앱을 조작해 버그와 기준 위반을 보고합니다. 단순히 에이전트를 더 오래 반복하는 것보다, 무엇을 검사할지와 다음 세션에 무엇을 넘길지를 명시하는 데 초점을 둡니다.

{
  "feature": "사용자가 주문 상태를 조회한다",
  "status": "in_progress",
  "acceptance": ["다른 사용자의 주문은 조회할 수 없다", "없는 주문은 오류 상태를 보여준다"],
  "evidence": [],
  "next_step": "격리된 테스트 계정으로 API와 UI 동작 확인"
}

평가 근거가 없으면 completed로 바꾸지 않습니다. 브라우저 테스트·API 응답·DB 상태 등 요구사항에 맞는 증거를 남깁니다. 멀티에이전트 구성은 추가 시간·비용이 발생하므로 자신의 작업에서 단일 에이전트 기준선과 비교합니다.

단계 진화 기준

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

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

공통 도입 실패 패턴

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

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

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

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

요약

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