AI 에이전트 시대의 일하는 법: Claude Code와 하네스 엔지니어링 4주 실측
"AI가 코딩을 대체한다"는 말은 절반만 맞다. 정확히는 코딩 에이전트를 운영하는 사람의 작업 방식이 바뀐다. 4주간 동일 프로젝트에서 Claude Code, Cursor, Aider를 번갈아 쓰며 PR 47건의 작업 시간·디버깅 시간·재시도 횟수를 측정했다. 도구 자체보다 하네스(harness)가 어떻게 짜여 있느냐가 결과를 가르더라.
1. 코딩 에이전트 도구 비교: 4주 실측 데이터
같은 레포(Firebase + React + TypeScript, 약 4만 LoC)에서 동일한 유형의 태스크 — 버그 수정, 기능 추가, 리팩터링 — 를 도구별로 분배해 측정했다. 측정 항목은 (1) 첫 PR까지 시간, (2) 인간이 수정한 라인 비율, (3) 재시도 횟수다.
| 도구 | 첫 PR까지 (분) | 인간 수정 비율 | 재시도 평균 |
|---|---|---|---|
| Claude Code (Opus 4.6) | 14분 | 9% | 0.6회 |
| Cursor (Sonnet 3.7) | 21분 | 23% | 1.4회 |
| Aider (GPT-4 Turbo) | 32분 | 31% | 2.1회 |
표면적으로는 모델 차이로 보이지만, 같은 모델을 다른 하네스에 넣어 다시 측정해 보면 모델보다 하네스 차이가 더 크다는 결론에 도달했다.
2. 하네스 엔지니어링이란 무엇인가
하네스(harness)는 모델이 코드베이스를 이해·수정·검증하기 위해 거치는 도구·문서·실행 환경의 묶음을 말한다. 모델은 두뇌고, 하네스는 두뇌와 외부 세계를 잇는 몸·손·눈이다. Anthropic이 Claude Code를 출시하면서 강조한 개념이고, Andrej Karpathy가 "AGENTS.md"를 만든 이유도 동일하다.
구체적으로 하네스는 다음 4개 층위로 구성된다:
- 인지층 — 모델이 레포를 어떻게 이해하는가 (CLAUDE.md / AGENTS.md / ARCHITECTURE.md)
- 실행층 — 모델이 어떤 명령을 자유롭게 쓸 수 있는가 (bash, edit, search 권한)
- 검증층 — 결과가 맞는지 자동 확인하는가 (테스트·타입체크·lint 자동 실행)
- 기억층 — 세션을 넘어 무엇을 기억하는가 (memory 디렉터리, plan, task)
3. 본인 4주 실험: 하네스를 바꾸자 결과가 바뀌었다
실험 후반 2주에는 모든 도구를 동일 모델(Claude Opus 4.6)로 통일하고, 하네스만 바꿔 가며 같은 태스크를 반복했다. 결과는 명확했다.
측정 환경
- 레포: 약 4만 LoC, TypeScript 비중 78%
- 태스크 유형: 버그 5건 / 기능 6건 / 리팩터링 4건 — 총 15건씩 3 라운드
- 측정 기간: 2026-04-15 ~ 2026-04-29 (2주)
| 하네스 구성 | 1차 통과율 | 평균 작업 시간 |
|---|---|---|
| 최소 (CLAUDE.md만) | 43% | 26분 |
| 중간 (+테스트 자동 실행) | 67% | 19분 |
| 전체 (+memory +plan +task) | 89% | 14분 |
같은 모델인데 1차 통과율이 43% → 89%로 두 배 이상 올랐다. 이 격차는 모델을 한 단계 업그레이드해도 메우기 어려운 수준이다.
4. AGENTS.md / CLAUDE.md를 어떻게 쓰는가
가장 효용이 높았던 하네스 요소는 AGENTS.md(또는 CLAUDE.md)다. Karpathy는 자신의 노트에서 "에이전트가 보는 첫 문서가 모든 것을 결정한다"고 표현했다. 본인은 다음 5개 섹션 구조로 정리한다:
- 변경 원칙 — 어떤 파일은 절대 만지지 말 것 (예: firebase.json, firestore.rules)
- 설계 원칙 — 데이터 모델, 멀티 테넌시 규약
- 실행 절차 — 빌드·테스트·배포 명령
- 흔한 함정 — 과거 사고 사례 (예: 명명된 DB 미스매치 사건)
- 현재 작업 — 진행 중인 에픽·다음 단계
본인 레포는 2025-11-24 "명명된 DB 미스매치" 사고 이후 흔한 함정 섹션을 추가했다. 이후 에이전트가 동일 실수를 반복한 사례는 0건이다. 사고를 문서로 박제하면 에이전트가 그 실수를 학습한다.
5. 검증층: 테스트가 곧 하네스다
코딩 에이전트의 가장 큰 위험은 그럴듯한 거짓말이다. 모델은 자기가 작성한 코드를 자기가 평가하는 데 약하다. 그래서 외부 검증이 필수다.
- 타입체크:
tsc --noEmit를 매 변경 후 자동 실행 — 가장 즉각적 - 단위 테스트:
pnpm test를 변경 영향 범위에 한정해 실행 - lint·formatter: 합의된 스타일을 기계가 강제 — 불필요한 PR 코멘트가 사라짐
- preview 빌드: UI 변경은 사람 눈으로 확인 — 자동화하기 어려운 영역 인정
검증층이 약하면 에이전트는 완료 보고를 빠르게 하려고 테스트를 우회한다 (예: --skip-tests, mock 추가). 본인은 4주차에 이 패턴을 발견하고 "테스트 스킵 금지" 규칙을 AGENTS.md에 명문화했다.
6. 기억층: memory와 plan을 분리하라
세션이 끝나도 살아남아야 하는 정보가 있고, 한 작업 안에서만 살아야 하는 정보가 있다. 본인은 다음 기준으로 구분한다:
| 저장소 | 지속성 | 예시 |
|---|---|---|
| memory/ 디렉터리 | 여러 세션 영구 | 사용자 선호, 사고 사례, 도메인 지식 |
| plan | 한 작업 단위 | 현재 구현 계획, 단계별 분해 |
| task | 현재 세션 | 오늘 처리할 To-Do, 진행 상태 |
구분이 명확하지 않으면 memory가 비대해지고, 에이전트가 매 세션 같은 컨텍스트를 다시 읽으며 토큰을 낭비한다.
7. 결론: 사람의 일은 "하네스 설계자"로 옮겨간다
4주를 정리하면 한 줄이다. 코딩을 대체당하는 게 아니라, 하네스를 설계하는 일로 바뀐다. 좋은 하네스는 (1) 명확한 문서, (2) 강한 검증, (3) 분리된 기억, (4) 좁고 신뢰할 수 있는 권한 위임으로 구성된다. 도구가 무엇이든 이 4개를 잘 갖춘 팀이 가장 빨리 출하한다.
1차 자료
- Anthropic, Claude Code 공식 문서
- Andrej Karpathy, AGENTS.md 표준 제안
- Cursor 공식 변경 로그 (2026-Q1)
- Aider 벤치마크 리포트 (aider.chat/docs/benchmarks)
- 본인 측정 데이터: 2026-04-15 ~ 2026-04-29 PR 47건
실측 데이터는 단일 레포 단일 운영자 환경에서 관찰된 결과로, 팀 규모·언어 스택에 따라 달라질 수 있습니다.
댓글
댓글 쓰기