5분이면 시작한다: 실전 하니스 구축 가이드

그래서 어떻게 시작하는가

Can Boluk의 실험을 다시 꺼낸다. 동일 모델, 동일 벤치마크에서 6.7%가 68.3%로 뛰었다. 코드 한 줄 안 바꿨다. 바뀐 건 에이전트가 작동하는 환경, 즉 하니스다.

6편에 걸쳐 이 차이의 근원을 해부했다. 1편에서 프롬프트가 하니스로 진화하는 흐름을 짚었고, 2편에서 네 기둥의 전체 지도를 펼쳤다. 3편은 에이전트가 실수할 수 없는 구조를 만들었고, 4편은 스스로 고치는 피드백 루프를 설계했다. 5편에서 복잡한 작업을 분해하고 조율하는 워크플로우를, 6편에서 관찰, 판단, 실행이라는 개선 사이클을 완성했다.

남은 질문은 하나다. "오늘 무엇을 하는가?"

이 글은 시리즈의 마지막 편이자 유일한 실행편이다. 이전 편들이 "왜"와 "무엇"을 다뤘다면, 7편은 "지금 당장 어떻게"에 답한다. 네 단계로 나눴다. 시간 기준이다.

5분이면 첫 단계를 마친다. 거기서 멈춰도 된다. 준비가 되면 다음 단계로.

1. 5분: 바닥을 깐다

하니스의 시작은 파일 하나다. Claude Code라면 CLAUDE.md, Codex라면 AGENTS.md, Cursor라면 .cursor/rules/ 디렉토리. 이름과 위치는 달라도 하는 일은 같다. 에이전트에게 "이 프로젝트는 이렇게 돌아간다"고 알려주는 것이다.

가장 빠른 시작법: Claude Code에서 /init을 실행하면 프로젝트를 분석해 CLAUDE.md 초안을 자동 생성한다. Cursor는 Command Palette에서 규칙을 생성하고, Codex는 프로젝트 루트에 AGENTS.md를 직접 만든다.

자동 생성된 파일은 출발점일 뿐이다. Anthropic의 기준은 명쾌하다. 매 줄마다 자문하라. "이것 없으면 에이전트가 실수하나?" 아니면 삭제한다. 150줄 이하가 권장선이다. 나머지는 skills나 rules로 분리한다.

최소 골격은 네 가지다.

## 프로젝트 개요
TypeScript + Next.js 16 프로젝트. Cloudflare Workers로 배포.

## 빌드/테스트
- 빌드: `npm run build`
- 단일 테스트: `npm run test -- --filter [파일명]`
- 전체 테스트 스위트는 CI에서만 실행

## 코드 스타일
- TypeScript strict mode
- named exports만 사용 (default export 금지)
- Tailwind utility 클래스로 스타일링

## 금기사항
- `any` 타입 사용 금지
- console.log 디버깅 코드 커밋 금지

이게 전부다. 장문의 산문이 아니다. builder.io가 정리한 좋은 예와 나쁜 예를 보면 차이가 선명하다.

Mitchell Hashimoto는 이 파일의 성격을 한 문장으로 정의했다. "AGENTS.md의 모든 줄은 과거 에이전트 실패에서 비롯된 규칙이다." 처음부터 완벽할 필요 없다. 에이전트가 실수할 때마다 한 줄씩 추가하면 된다. 살아있는 문서다.

이 5분이 1편에서 말한 "프롬프트에서 하니스로 올라가는 첫 걸음"이다. AGENTS.md가 있을 때 작업 완료 시간이 29% 줄고 출력 토큰이 17% 감소했다는 연구 결과(arXiv 2601.20404)가 있다. 파일 하나로 얻는 효과치고는 나쁘지 않다.

2. 30분: 울타리를 세운다

바닥을 깔았으면 울타리를 세운다. 에이전트가 해도 되는 일과 하면 안 되는 일의 경계를 긋는 단계다. 3편의 "아키텍처 제약"이 여기서 설정 파일로 바뀐다.

Claude Code: Hooks

Claude Code의 울타리는 hooks다. .claude/settings.json에 정의한다. Trail of Bits 팀이 공개한 보안 설정이 좋은 참고다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "echo $TOOL_INPUT | jq -r '.command' | grep -qE 'rm\\s+-rf' && echo 'Use trash instead of rm -rf' >&2 && exit 2 || exit 0"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null; exit 0"
        }]
      }
    ]
  }
}

PreToolUse는 도구 실행 전에 개입한다. 위 예시는 rm -rf 명령을 차단한다(exit code 2가 차단 신호). PostToolUse는 도구 실행 후에 개입한다. 파일을 수정할 때마다 Prettier가 자동으로 돈다.

Cursor: Glob 패턴 규칙

Cursor는 .cursor/rules/ 디렉토리에 .mdc 파일로 규칙을 관리한다.

---
description: "React 컴포넌트 작성 패턴"
alwaysApply: false
globs: ["src/components/**/*.tsx"]
---
- 함수형 컴포넌트만 사용
- Props interface를 별도 export
- 'use client' 디렉티브 필수

globs 패턴에 매칭되는 파일을 작업할 때만 규칙이 활성화된다. 모든 규칙을 항상 로드하지 않으니 컨텍스트를 절약한다.

Codex: 샌드박스 모드

Codex는 .codex/config.toml에서 에이전트 권한을 3단계로 제어한다. read-only(기본) → workspace-write → danger-full-access. 이름에 "danger"가 붙은 데는 이유가 있다.

공통으로 해야 할 세 가지:

1. 디렉토리 구조를 5줄 이내로 문서화한다. 에이전트가 파일을 어디에 만들어야 하는지 알게 된다.
2. 금기사항 3개를 추가한다. "프로덕션 의존성 추가 전 확인 요청", "API 키 하드코딩 금지", "main 브랜치 직접 푸시 금지" 같은 것.
3. .gitignore에 CLAUDE.local.md를 추가한다. 팀 공유 설정과 개인 설정을 분리하는 시작점이다.

이 30분이 2편의 네 기둥 중 "아키텍처 제약"을 실전에 옮기는 시간이다.

3. 1시간: 루프를 잇는다

울타리를 세웠으면 피드백 루프를 연결한다. 에이전트가 실수했을 때 스스로 감지하고 교정하는 구조를 만드는 단계다. 4편의 자가 검증 루프가 여기서 실제 도구로 구현된다.

CI에 에이전트 검증을 통합한다. 에이전트가 만든 코드도 인간이 만든 코드와 동일한 게이트를 통과해야 한다. lint, 타입 체크, 테스트. Anthropic의 #1 권고가 이것이다. "에이전트에게 검증 수단을 줘라." 에이전트가 npm run test를 직접 실행하고 결과를 확인할 수 있어야 한다.

PostToolUse 훅 체인을 건다. 코드 변경이 일어날 때마다 린트와 포매팅이 자동으로 돈다. 앞 단계의 PostToolUse 훅을 확장하면 된다. 파일 수정 후 Prettier, ESLint, 타입 체크가 순서대로 실행된다. 규칙을 어기면 즉시 피드백이 돌아온다.

실수 패턴을 규칙으로 전환한다. 에이전트가 같은 실수를 반복하면 CLAUDE.md나 AGENTS.md에 해당 규칙을 추가한다. "useEffect 의존성 배열 빠뜨리지 말 것", "API 응답 타입을 any로 두지 말 것" 같은 구체적인 지침이다. Claude Code의 /insights 명령이 이 패턴을 자동 분석해준다.

Stop 훅으로 최종 검증을 건다. Claude Code의 Stop 훅은 에이전트가 응답을 완료할 때 실행된다. "변경한 파일의 테스트가 통과하는가?" 마지막으로 한 번 더 묻는 관문이다. 6편에서 다룬 "관찰" 렌즈의 첫 번째 설치다.

LangChain이 이 접근법의 효과를 직접 증명했다. 모델 변경 없이 하니스(시스템 프롬프트, 도구, 미들웨어 훅)만 개선해서 Terminal Bench 순위를 30위 밖에서 5위로 끌어올렸다. 52.8%에서 66.5%로 13.7pp 상승. Can Boluk의 6.7%에서 68.3%도 같은 원리다. 모델이 아니라 루프가 성능을 결정한다.

4. 반나절: 팀으로 확장한다

혼자 쓰던 하니스를 팀으로 확장하는 단계다. 5편의 워크플로우 제어가 팀 구조로 구현된다. 규모에 따라 전략이 달라진다.

1인 개발자: Peter Steinberger 모델

Steinberger는 혼자서 5~10개 에이전트를 동시에 운용한다. 월 6,600건 이상의 커밋. 직접 하는 건 아키텍처 리뷰뿐이다. 나머지는 에이전트가 처리한다. "Attended parallelization"이라 부르는 방식으로, 여러 에이전트 세션을 열어놓고 능동적으로 관리한다.

1인이라면 이렇게 시작한다.

1. 반복되는 워크플로우 하나를 skills로 정의한다(배포, 테스트, 리뷰 등).
2. 서브에이전트를 하나 만들어 위임한다(보안 리뷰어, 테스트 작성자 등).
3. 주 1회 /insights를 실행해 에이전트 사용 패턴을 분석한다.

소팀(2~5명): Boris Tane 권고

Boris Tane의 핵심 조언은 하나다. 에이전트에게 바로 코딩을 시키지 말고, 먼저 상세 계획을 문서로 작성하게 하라. 계획서가 아키텍처 제어와 토큰 절약을 동시에 달성한다.

소팀의 체크리스트:

1. CLAUDE.md / AGENTS.md를 git에 커밋한다. 팀 전원이 같은 규칙을 공유한다.
2. CLAUDE.local.md로 개인 선호를 분리한다. 에디터 설정, 디버깅 습관 같은 것.
3. AGENTS.md 변경을 코드 리뷰 대상에 포함한다. 하니스도 코드다.
4. PR에 에이전트 출력물과 변경 사유를 함께 포함한다.

조직(10명 이상): Stripe Toolshed 모델

Stripe는 400개 이상의 내부 도구를 MCP 서버로 중앙 관리한다. "Toolshed"라 부르는 이 시스템을 통해 에이전트가 인간 개발자와 동일한 개발 환경(devbox)을 쓴다. Slack에서 작업을 요청하면 에이전트가 코드를 작성하고 CI를 통과시켜 PR을 생성한다. 주 1,000건 이상의 머지된 PR, 대부분 무인(unattended) 처리다.

조직 규모에서 갖춰야 할 세 가지:

1. 도구 레지스트리: 에이전트가 접근할 수 있는 도구를 중앙에서 관리한다. MCP 서버가 이 역할을 한다.
2. 조직 표준 강제: Cursor Team Rules처럼 최상위 우선순위로 조직 규칙을 적용한다.
3. 감사 추적: 에이전트의 모든 결정을 기록한다. "머지되는 모든 코드에 책임지는 사람이 있어야 한다"는 원칙이다.

어디쯤 와 있는가

네 단계에 대응하는 성숙도 모델로 현재 위치를 가늠할 수 있다.

Can Boluk의 실험을 대입하면 선명해진다. Level 0에서 6.7%, Level 3 이상에서 68.3%. 레벨이 올라갈수록 동일 모델의 성능 천장이 높아진다.

시리즈를 한 장으로

7편을 한 문단으로 압축한다.

1편에서 프롬프트가 하니스로 진화하는 흐름을, 2편에서 네 기둥의 전체 지도를 펼쳤다. 3편은 실수할 수 없는 환경, 4편은 스스로 교정하는 루프, 5편은 작업을 분해하고 조율하는 구조, 6편은 하니스 자체를 개선하는 사이클을 다뤘다. 7편에서 이 모든 것을 5분짜리 첫 걸음부터 조직 확장까지 네 단계로 엮었다.

시리즈를 관통하는 문장은 하나다. 하니스 엔지니어링은 AI를 잘 쓰는 기술이 아니라, AI가 잘 작동하는 환경을 만드는 기술이다.

OpenAI에서 3명이 100만 줄을 출하한 건 코딩 실력 때문이 아니다. 에이전트가 성공할 수 있는 환경을 설계했기 때문이다. 그 환경은 CLAUDE.md 파일 하나에서 시작한다.

5분이면 된다. /init 한 번이다.