구현 수준별 로드맵

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

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 시작 팁

CLAUDE.md에 가장 자주 틀리는 패턴을 3개만 명시해도 효과가 큽니다. “절대 mutation 하지 말 것”, “async/await 대신 Promise.then 사용 금지” 같은 구체적 규칙이 추상적 지침보다 훨씬 효과적입니다.

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

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

핵심 구성 요소

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

AGENTS.md 기본 구조

AGENTS.md

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

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

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

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

기대 성과

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

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

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

핵심 구성 요소

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

조직 수준 체크리스트

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

Level 3 주의사항

Level 3의 모든 구성 요소를 동시에 도입하려 하면 실패합니다. 하네스 버저닝 과 옵저버빌리티 통합 을 먼저 구축하고, 나머지는 데이터를 기반으로 우선순위를 정하세요.

단계 진화 기준

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

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

요약

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