Claude Code를 도구가 아닌 운영 시스템으로 다루는 법
유명 개발자들의 블로그·인터뷰 리서치 기반 개론
2026. 4 · 김학민
유명 개발자들의 블로그 · 인터뷰 · X 포스트를 기반으로 정리한 하네스 엔지니어링 개론
장문 에세이
· 회고
팟캐스트
· 영상
실시간
운영 노트
settings
AGENTS.md
특정 인물의 의견이 아니라 여러 실무자가 독립적으로 도달한 공통 패턴에 초점
HashiCorp 창립
Ghostty 메인테이너
대규모 OSS
운영자 시각
Anthropic
Claude Code 헤드
제품 메이커
시각
Datasette 창립
Django co-creator
연구자·toolsmith
시각
Flask·Jinja2
creator
회의주의
엔지니어 시각
indie engineer
ghuntley.com
자율 루프
운영자 시각
서로 다른 입장이지만 독립적으로 같은 결론에 도달한 지점들이 오늘의 뼈대
에이전트가 실수할 때마다,
그 실수를 다시는 못 하도록
환경에 영구적 해결책을 박아 넣는 것
단순히 결과를 잘 받는 게 아니라 — 실수가 물리적으로 불가능한 환경을 점진적으로 빚는 것
| 컨텍스트 엔지니어링 | 하네스 엔지니어링 | |
|---|---|---|
| 목표 | 이번 호출을 잘하게 | 다음번엔 물리적으로 불가능하게 |
| 단위 | 1 prompt · 1 호출 | 영구 변경 (커밋) |
| 수명 | 그 세션 · 일회성 | 시스템 수명 전체 |
| 도구 | prompt · context window | hook · test · settings · AGENTS.md |
| 실패 시 | 다음 prompt를 다듬음 | 환경에 표지판을 박아 재발 차단 |
이번을 잘하게가 아니라 다음을 막는다 — 패러다임 전환
SECTION 01
우리가 빠진 두 가지 루프
"다음 모델 나오면
좀 나아지려나"
"프롬프트를
더 잘 써야 하나"
모델 기다림 ↔ 프롬프트 다듬기의 무한 루프
Claude Code 바깥을
먼저 손봄
모델 싸움도 아니고 프롬프트 싸움도 아님
=
그대로
⇄
구조가 바뀜
같은 모델이 같은 자리에 있지만 — 주변 구조가 결과를 갈랐다
바깥을 손본다는 건
구체적으로 무엇인가
표지판 · 자동 검증 · 규칙 · 메모리 · 훅 — 다음 섹션부터 하나씩
SECTION 02
모델을 둘러싼 구조물 만들기
어떤 작업자가 와도
비슷하게 잘 처리
모델 의존도 낮음
유능한 작업자도
엉뚱한 데를 건드림
모델만으로는 부족
'표지판'은 결과를 모델 능력에 덜 의존하게 만드는 장치
표지판은 선언하는 게 아니라 자동으로 집행되어야 한다
CLAUDE.md · AGENTS.mdsettings.json{
"hooks": { ... },
"permissions": { ... },
"agents": { ... },
"env": { ... }
}
/commit-push-prcode-simplifierverify-app여러 운영 사례에서 반복적으로 등장하는 패턴
CLAUDE.md — 팀의 압축된 기억무엇을 다루는 곳인지
어떤 말투 / 어떤 코드 스타일
절대 하지 말아야 할 것
매뉴얼이 아니라 반복된 실수의 흔적 — 모델이 좋아지면 적극적으로 prune
- 내 PR은 자동 머지 활성화 - 팀 stamps 채널에 PR 자동 포스트
실제 운영 사례에서 발견된 personal CLAUDE.md 패턴 — 개인용 글로벌 파일은 작을수록 좋다
팀 공유 CLAUDE.md는 짧고 주에 여러 번 업데이트되는 살아있는 문서. 모델이 발전하면 룰 한 줄씩 삭제
작업 한 개를 고른다
내가 반복하는 작업 중 하나만
CLAUDE.md에 규칙을 적는다
그 작업에 대한 규칙을 파일로
이 한 번이 다음 모든 시도에 적용된다 — 결과물이 아닌 생성기를 고치는 첫 걸음
SECTION 03
한 번에 끝낸다는 환상 깨기
"한 번에 끝낸다"는
없다
한 번에 완성된 사례
0건
대부분
분해 부족으로 귀결
분해 → 계획 → 검증의
반복 루프
계획
전체 그림 그리기
조각
실행 단위로 분할
실행
한 조각씩 처리
검증
단계별 결과 확인
분해하지 않은 작업은 거의 실패 — 리서치 전반에서 일관된 보고
plan mode 작동 방식큰 작업을 던지기 전에 항상 계획 단계를 먼저 요구 — 변경 범위와 가정이 코드 작성 전에 드러난다
"Ralph Loop"라 명명된 패턴 — Bash 한 줄로 표현되는 무한 반복 루프
# 의도: 같은 PROMPT.md를 무한 반복 while :; do cat PROMPT.md | claude done
프롬프트가 마법이 아니라 루프 + 멈춤 신호가 시스템이다
PROMPT.md를 안정적으로 유지AGENTS.md에 기록조심: Ralph Loop는 신규 코드베이스 부트스트래핑에만 적합 — 기존 코드베이스에 적용은 위험
파일당 1개
모델과 대화하며 작성
매번 spec 재로드
대화 history 의존도 0
plan/AGENTS.md
세션 사이 영구 기억
spec은 매 세션마다 다시 읽히는 메모리 — 대화 history에 의존하지 않는 운영 단위
실험 단위가 작을수록 실패 진단도 빠르다 — 레포 / 워크트리 / 폴더 어느 단위든 적용
SECTION 04
루프를 멈출 권리는 도구의 몫
추론은 슬롯머신과 너무 닮았다
결과가 좋아 보여도 검증되지 않은 추론은 검증된 적이 없다
| 실무자 유형 | 1차 검증 도구 | 왜 거기에 의지하는가 |
|---|---|---|
| 제품 운영자 | eval · CI 리뷰 · 자체 dogfood | 출시되는 도구이므로 사용자 경로가 곧 진실 |
| 연구자 | 사람이 line-by-line 읽기 | 새로운 아이디어 검증이 목적이라 자동화가 의미 없음 |
| 코드베이스 메인테이너 | compiler + 타입체커 + 스냅샷 테스트 | 강타입 언어 (Zig/Go)가 자동으로 거대 영역을 검증 |
| 회의주의 엔지니어 | 스냅샷 테스트 · 다른 엔진 리뷰 | 추론을 신뢰하지 않으니 외부 ground truth로 |
| 자율 루프 운영자 | 생성된 테스트 · 고정된 문서 · AGENTS.md | 무인 루프가 돌려면 자동 멈춤 신호가 필수 |
도구·언어가 달라도 공통 원칙 — agent가 자기 결과를 자기가 검증할 수 없다
Agent가
코드 수정
훅으로
trigger
의미 있는
출력
맥락 갖고
재시도
핵심: 실패가 의미 있는 메시지여야 함. "Test failed"보다 "expected X, got Y at line 42" 같은 actionable 메시지
실패가 명시적이면 견딜만 하다.
문제는 조용히 멈추는 것
실패는 명시적이어야 멈춤 신호가 됨 — 조용히 멈춘 agent가 진짜 문제
대응: 즉시 정지 → manual research, scope 재설계, 또는 다른 엔진으로 교차 시도
디버깅 · 도구 호출 · 코드 생성
빠른 합성
PR 리뷰 · 보안 · 엣지 케이스
적대적 검토
같은 결론을 다른 엔진이 동의하면 high-confidence. 엇갈리면 사람이 봐야 한다는 신호 — disagreement-driven integration
SECTION 05
정답은 없고, 맞춤 조정만 있다
거의 전량 AI 작성
자기 코드의 ~100%를 AI가 작성
수개월간 hand-edit 거의 없음
장기 무인 루프
3개월 동안 사람 안 붙은
루프로 새 언어 1개 완성
두 사람 모두 출시 가능한 결과물을 만들어 냈다 — 정답이 하나가 아니라는 증거
새 코드베이스
제약 없음
무인 루프 적합
기존 시스템
호환성 제약 다수
사람 개입 필수
신규 코드베이스는 자율 루프가 잘 통하지만, 기존 코드베이스에 그대로 적용하면 위험
무인 루프 사례를 그대로 사내 레거시에 적용하면 위험 — 우리 환경의 제약을 먼저 식별
이해하지 못한 코드는 출시하지 않는다 — 모든 운영 사례의 공통 마지노선
한 흐름 추론
깊이 따라감
맥락 전환 비용 ↑
세션이 얕아짐
리뷰는 사람 몫
병목은 그대로
병렬로 돌려봤자 리뷰가 사람이라 병목은 똑같다 — 회의주의 관점의 일관된 지적
파이프라인의 한 부분이 극적으로 빨라지면
입력을 덜 흘려보내야 한다
AI가 빨라진 만큼 사람의 검토 대역폭이 새로운 병목
SECTION 06
실무자들이 함께 부정하는 것들
GitHub · Slack · DB 같은
표준 외부 시스템 연결
도구를 더하는 것일 뿐
판단 / 검증 / 보안까지 풀지 못함
MCP만 붙이면 다 된다
실무에서
빠르게 약화
MCP는 접근 채널이지 해결책의 자동화가 아니다
실무에서 MCP 만능론은 빠르게 약해지는 중 — 도구를 더하는 것과 시스템을 안전하게 만드는 것은 다른 문제
다음 모델 나오면
다 해결된다
6개월 후의 모델을
가정해서 설계한다
모델은 변수가 아니라 상수에 가까운 것으로 가정 — 변하는 건 주변 구조뿐
프롬프트가 마법이 아니라,
루프 + 멈춤 신호가 시스템이다
프롬프트 한 줄 더 잘 쓰는 게 아니라 — 매 loop마다 같은 컨텍스트가 reload되는 시스템을 만드는 일
보여주기식 하네스 경고: 측정 안 되는 컴포넌트는 장식. 누구도 안 읽는 AGENTS.md, 한 번도 발동 안 된 hook, 비교 검증 안 한 prompt — 모두 보여주기
SECTION 07
실제 운영자들이 반복적으로 등장시키는 8가지 패턴
한 고개입 운영자의 일상 패턴 — 다만 병렬은 깊은 사고를 깨는 트레이드오프가 있다는 회의도 함께
code-simplifier
독립 컨텍스트에서 단순화 작업
verify-app
실행 검증 (browser/sandbox)
codex-reviewer
다른 엔진의 PR 리뷰
explore
read-only 코드베이스 탐색
.claude/agents/에 역할별로 정의 · 메인 컨텍스트 보호 + 토큰 절약
Edit/Write 직후
포매터 자동 실행
linter 자동 실행
Bash 실행 전
위험 명령 차단
특정 경로 보호
세션 종료 시
최종 검증 / 알림
상태 체크포인트
CLAUDE.md에 적은 룰은 1번 따르고, 훅은 매번 자동으로 집행 — 지침과 행위의 간극을 메우는 도구
{
"allow": ["Bash(npm test:*)", "Bash(git status)"],
"deny": ["Bash(rm -rf:*)", "Bash(git push --force:*)"]
}
안티패턴: --dangerously-skip-permissions 항상 켜두기 — 안전한 명령만 명시적으로 allow하는 게 더 빠르고 안전
한 작업당 얼마가 보이면 harness 변경의 효과도 측정 가능 — theater 방지의 출발점
# 새 worktree 생성 git worktree add ../feat-x feat-x # Agent에 위임 cd ../feat-x && claude
레포 루트에 명시 — 기여자가 AI 사용 시 공개 의무, 인간 이해 의무, 저품질 PR 금지
메인테이너가 저품질 PR에 익사하지 않게 — 검증된 기여자만 머지 가능한 게이트
하네스가 코드베이스를 넘어 팀·커뮤니티 운영 정책으로 확장된 사례
SECTION 08
실무자들이 공통으로 명시한 실패 모드
10-20 PR/day
초고속 산출
+ 4시간/day
사람이 봐야 하는 시간
병목 이동
검토가 critical path
AI에게 이건 안 된다고 말하는 디시플린이 새로운 핵심 역량
하네스가 빠지면
모델은 그냥 챗봇이다
모델은 바뀌어도, harness는 그 자리에서 계속 동작한다
모델 업그레이드도 프롬프트 재치도 아닌
모델을
잇는 구조물
계획 → 조각
→ 실행
안티 슬롭
세션
대부분 팀의 합리적 목표는 Level 2-3 — Level 4는 신규 코드베이스 + 측정 인프라 갖춰진 후
반복 작업 1개
CLAUDE.md에
룰 1줄 추가
한 작업의
cost·time·eval
1번 측정
위험 명령 1개
settings.json
deny에 추가
좋은 명령 1개
팀 레포
커밋
harness는 한 번에 못 만든다 — 작업 → 룰 → 측정의 사이클
질의 · 토론
Harness Engineering · 2026. 4 · 김학민