실전 — 빈 파일에서
완전한 하네스까지

한 번에 완성하려 하지 마라. 빈 파일 하나, 실수하는 agent 하나, 새 규칙 한 줄. 3개월 뒤 돌아보면 그 파일이 곧 당신의 하네스다.

세 도구, 세 개의 출발점

어떤 AI 코딩 도구를 쓰든 하네스의 출발점은 같다 — 빈 지시 파일 하나. 차이는 파일명과 위치뿐이다.

Claude Code — CLAUDE.md

touch CLAUDE.md

세션 기동 시 자동으로 읽는다. 추가 설정도 명령 등록도 필요 없다. 3층 상속을 지원한다 — ~/.claude/CLAUDE.md(전역, 모든 프로젝트) → 프로젝트 루트(프로젝트 레벨) → 하위 디렉터리(상층 덮어쓰기). 형식은 평범한 Markdown으로 특수 문법이 없다.

Codex CLI — AGENTS.md

touch AGENTS.md

기동 시 프로젝트 루트에서 현재 작업 디렉터리까지 층별로 순회하며 각 층에서 AGENTS.override.md → AGENTS.md → fallback 파일명 순으로 확인한다. 병합 전략은 루트에서 리프로 이어 붙이되 가까운 쪽이 먼 쪽을 덮어쓴다. OpenAI는 약 100줄을 유지하며 백과사전이 아닌 지도로 삼아 docs/의 상세 문서를 가리키라고 권고한다.

Cursor — .cursor/rules/

mkdir -p .cursor/rules
touch .cursor/rules/project.mdc

---
description: 프로젝트 공통 규범
globs: "**/*"
alwaysApply: true
---
# 규칙은 여기에 쓴다

Cursor의 독자성은 glob scoping — 규칙을 특정 파일이나 디렉터리에만 발효시킬 수 있어 대형 프로젝트에서 실용적이다.

빈 파일에서 시작, 실수가 이끈다

파일은 만들었다. 무엇을 쓰는가? — 아무것도 쓰지 않는다. 게으름이 아니다.

구체적 시연 — React 프로젝트의 첫 10개 규칙

막 인수한 React 프로젝트를 가정한다. 빈 파일에서 시작해 처음 10개의 규칙이 어떻게 생기는지 본다.

# 테스트
- 테스트 실행: `pnpm vitest run`
- 단일 파일: `pnpm vitest run src/path/to/test.ts`

# 패키지 관리
- pnpm만 사용, npm과 yarn 금지
- 의존성 설치: `pnpm add`

# 프로젝트 구조
- src/components/ — 공유 UI 컴포넌트
- src/features/   — 기능 모듈별 비즈니스 코드
- src/lib/        — 유틸과 서드파티 래핑
- src/api/        — API 요청 계층. 요청 로직을 컴포넌트에 쓰지 말 것

# 코드 스타일
- TypeScript enum 금지, literal union type 사용
  ❌ enum Status { Active, Inactive }
  ✅ type Status = 'active' | 'inactive'

# Git 규범
- main 브랜치에 직접 push 절대 금지
- feature/ 브랜치 생성 후 PR로 병합
- commit message는 영문, 형식: type(scope): description

# 아키텍처 원칙
- 단일 컴포넌트 파일 200줄 이하
- 150줄 초과 시 자식 컴포넌트 분리 검토
- 비즈니스 로직은 커스텀 hook으로 추출, 컴포넌트는 렌더링만

# 의존성 관리
- 새 의존성 추가 전 기존 의존성으로 가능한지 확인
- 네이티브 API와 프로젝트 기존 라이브러리 우선
- date-fns 설치됨 — moment나 dayjs를 들이지 말 것

# 커밋 전 검사
- 커밋 전 필수 실행: `pnpm lint && pnpm type-check`
- lint 오류는 반드시 수정, eslint-disable 불허

# 에러 처리
- 빈 catch 블록 불허
- API 오류는 src/lib/error.ts의 AppError 클래스로 통일
- 사용자 노출 오류는 친화적 안내로, 기술 세부 노출 금지

# API 계층
- 모든 API 요청은 src/api/ 하위 모듈에서 발신
- 프로젝트가 래핑한 apiClient 사용 (src/lib/api-client.ts)
- 컴포넌트에서 fetch 직접 호출 금지

10개의 규칙 중 허공에서 나온 것은 하나도 없다. 모든 규칙 뒤에 구체적인 문제가 있다 — 이것이 실수 주도 하네스다.

세 가지 기동 조언

3+1 도구 기동 조견표

지금 쓰는 도구를 고르고, 해당 빈 파일을 만들고, 일을 시작한다. agent가 실수하면 한 줄 더한다. 이것이 당신의 첫 하네스다.

지시 파일에 「main에 push하지 마라」고 쓰는 것은 권고다. hooks로 프로그램 층에서 막는 것이 제약이다. 이 구별이 하네스가 art에서 engineering으로 넘어가는 전환점이다.

근본적인 구별

CLAUDE.md에 이렇게 썼다고 하자 — - main 브랜치에 직접 push 절대 금지. 이것은 권고다. Claude는 대체로 준수하지만 보장은 없다. 컨텍스트가 길어지거나 과제가 복잡해지거나 모델이 가끔 엇나가면 규칙이 무시될 수 있다. 이제 방식을 바꾼다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git push*main*)",
        "handler": {
          "type": "shell",
          "command": "echo 'DENY: main 브랜치 직접 push 금지'"
        }
      }
    ]
  }
}

이것은 제약이다. Claude가 무슨 생각을 하든, 컨텍스트가 얼마나 혼란하든, main으로의 push 명령은 실행 전에 차단된다. 프로그램 레벨이고 확정적이며 우회 불가능하다.

Claude Code의 Hooks 시스템

Hooks는 Claude Code의 결정적 무기다. 2026년 4월 기준(v2.1.90) 20여 종의 생명주기 이벤트를 지원하며 자주 쓰는 것은 일곱이다.

가장 핵심은 PreToolUse — deny 신호로 특정 작업을 프로그램 층에서 저지할 수 있는 것은 모든 AI 코딩 도구 가운데 유일하다.

실용적인 hooks 네 가지

{ "hooks": { "PostToolUse": [ {
  "matcher": "Edit|Write",
  "handler": { "type": "shell",
    "command": "npx eslint --fix \"$CLAUDE_TOOL_ARG_file_path\" 2>&1 | true" }
} ] } }

{ "hooks": { "PreToolUse": [ {
  "matcher": "Edit(.env*)|Edit(*.production.*)",
  "handler": { "type": "shell",
    "command": "echo 'DENY: 프로덕션 설정 파일은 보호됨. 직접 수정 불허'" }
} ] } }

{ "hooks": { "PostToolUse": [ {
  "matcher": "Edit(*.ts)|Edit(*.tsx)",
  "handler": { "type": "shell",
    "command": "npx tsc --noEmit 2>&1 | head -20" }
} ] } }

{ "hooks": { "PreToolUse": [ {
  "matcher": "Bash(git commit*)",
  "handler": { "type": "shell",
    "command": "pnpm test --run 2>&1 || echo 'DENY: 테스트 미통과, 커밋 금지'" }
} ] } }

흥미로운 디테일 — Claude에게 hooks를 스스로 쓰게 할 수 있다. 「모든 파일 편집 후 eslint를 돌리는 hook을 써라」고 말하면 구성까지 해 준다. agent가 스스로에게 제약을 채운다.

OpenAI의 하드 제약 — 기계화된 강제 집행

Codex CLI에는 hooks가 없지만 OpenAI 팀은 다른 하드 제약 체계를 썼다. 핵심 철학 — 「코드의 어디가 나쁜지 말로 표현할 수 있다면, 다음 단계는 그것을 써 내리는 것이다.」 구체적으로 3층이다.

• 제1층 — 의존 계층 아키텍처. 고정 순서 Types → Config → Repo → Service → Runtime → UI. 각 비즈니스 도메인에서 코드는 이 방향으로만 의존한다. UI는 Service에 의존할 수 있지만 역은 불가. 횡단 관심사(인증·텔레메트리·Feature Flags)는 유일한 명시적 인터페이스인 Providers로만 진입한다. — 「이 아키텍처는 통상 엔지니어 수백 명이 될 때까지 미루는 것이다. coding agent가 있으면 초기 전제 조건이다.」 agent는 일관성을 자발적으로 유지하지 않는다. 제약만이 그것을 해낸다.
• 제2층 — 커스텀 linter. Codex가 스스로 생성한 커스텀 ESLint 규칙과 structural test가 계층 경계 위반 코드를 전담 검출한다. linter는 CI에서 돌고 위반 PR은 병합되지 않는다. 오류 메시지는 위반 사실만이 아니라 수정 가이드와 문서 링크를 담아 agent가 인간 개입 없이 스스로 고치게 한다.
• 제3층 — CI 강제. 상기 모든 검사가 CI에서 실행된다. 권고도 알림도 아니고, 물리적으로 메인 브랜치에 합쳐지지 않는다.

Codex의 Sandbox — 물리적 격리

.git/과 .codex/는 full-access 모드에서도 항상 보호된다. 가장 단순하고 거친 제약 — agent가 못 하는 일은 그냥 못 한다. 규칙으로 하지 말라고 말하는 것이 아니라 환경 층에서 할 수 없게 만든다.

제약 스펙트럼 — 부드러움에서 단단함으로

오른쪽으로 갈수록 제약이 단단하다. 단단할수록 신뢰할 수 있지만 유연성은 떨어진다. 좋은 하네스는 이 층들의 조합이다 — 전부 최강으로도, 전부 최약으로도 쓰지 않는다. 대부분의 규칙은 지시 파일이면 충분하고, 소수의 핵심 안전선만 hooks나 CI로 지킨다.

권고인가 제약인가 — 판단법

규칙 하나가 권고여야 하는지 제약이어야 하는지의 판단 — 스스로 묻는다: agent가 이 규칙을 위반하면 후과는 무엇인가. 코드 스타일 불일치? 성가시지만 치명적이지 않다 — 권고. 프로덕션 DB 삭제? 재앙적 후과 — 반드시 제약. main 브랜치 push? revert 가능하지만 번거롭다 — 제약. 변수 이름? review 때 고치면 된다 — 권고. 제약이 지키는 것은 마지노선이지 취향이 아니다.

제약이 전환점이다

도구들을 조사하면 분명한 경계선이 보인다 — 프로그램 레벨의 하드 제약을 제공하는 것은 Claude Code와 Codex CLI뿐이다. Cursor·Windsurf·GitHub Copilot·Aider는 프롬프트 레벨 규칙만 있다. Claude Code의 hooks는 프로그래머블(임의 로직으로 approve/deny 결정), Codex CLI의 sandbox는 정책식(프리셋 레벨 선택, 커스텀 로직 불가), 나머지 도구의 규칙은 권고적(AI가 「따라야 하지만」 「어길 수도 있는」)이다. Cline은 제3의 길 — Plan/Act 이중 모드로 「사회적 제약」을 구현한다. Plan 모드는 분석만 하고 수정하지 않으며, Act 모드는 매 단계 인간 승인을 요구한다. 기술로 agent를 저지하는 것이 아니라 프로세스로 인간 확인을 보장하는 방식이다.

agent 하나가 못 푸는 문제를 agent 열이 반드시 푼다는 보장은 없다. 그러나 편성이 옳다면, 열 개의 agent는 하나의 agent가 영원히 못 하는 일을 해낸다. 언제 멀티 Agent를 쓰고 어떻게 쓰는가를 다룬다.

말 한 마리에서 말 떼로

앞의 모든 장은 단일 agent의 하네스였다. 그러나 실제 프로젝트의 많은 과제는 agent 하나로 감당이 안 된다. 똑똑하지 않아서가 아니다 — 컨텍스트 윈도가 물리적 한계다. 프런트엔드·백엔드·DB·테스트·문서를 하나의 agent가 동시에 다루면 컨텍스트가 차는 순간 성능이 절벽처럼 떨어진다(약 100만 토큰이 천장). 그래서 각자의 컨텍스트 윈도를 가진 복수의 agent가 필요하다. 문제는 — 누가 이들을 조율하는가.

Boris의 10–15 동시 세션 — 사람이 편성기가 된다

가장 소박한 편성 — 인간이 편성기 노릇을 한다. Boris Cherny(Claude Code 창시자)는 일상적으로 10–15개의 동시 세션을 유지한다. 터미널 5개(1–5번 번호, 셸 별칭 za·zb·zc로 전환), 브라우저 5–10개, 아침에 띄워 두고 나중에 확인하는 모바일 세션. 각 세션은 독립 git worktree 위에서 돌아 코드가 충돌하지 않는다. 일부 엔지니어는 코드를 쓰지 않고 로그와 조회 전용인 「분석」 worktree를 따로 둔다. 고급 아키텍처가 아니지만 Boris는 이것이 팀 내부의 the single biggest productivity unlock이라 말한다.

장점은 완전한 통제. 단점은 계속 지켜봐야 하고 과제 간 의존 관계가 당신 머릿속에만 존재한다는 것.

Anthropic의 3-Agent 아키텍처 — 사람 없이 조율하려면

20배 이상 비싸지만 단일 Agent의 산출은 아예 쓸 수 없다 — 더 많은 돈으로 더 잘 만든 것이 아니라, 이 돈을 쓰지 않으면 아예 안 되는 것이다. 흥미로운 후일담 — 모델이 Sonnet 4.5에서 Opus 4.6으로 오르자 Sprint 메커니즘이 완전히 제거되었다. 모델이 장기 과제를 원생 처리하고 Evaluator는 전 과정 종료 후 1회 평가로 바뀌었다. 모델의 진보가 편성을 단순화하고 있다.

당신도 쓸 수 있다 — Planner/Generator/Evaluator의 서민판

3-Agent 아키텍처의 서민판이다. 복잡한 시스템을 세울 필요 없이 대화 창 세 개면 충분하다.

Agent Teams — Claude Code 내장 멀티 Agent

Claude Code의 Agent Teams는 agent 간 직접 통신을 지원하는 현재 유일한 방안이다. 한 세션이 team lead가 되어 과제를 배분하고 결과를 종합하며, teammate들은 lead를 거치지 않고 직접 통신할 수 있다. 각 agent는 독립 컨텍스트 윈도를 갖는다. Boris의 수동 모드 대비 강점은 자동 조율 — 큰 과제를 기술하면 lead가 스스로 쪼개고 배분하고 수거한다. 병렬 조사, 독립 모듈 개발, 경쟁 가설 디버깅에 적합하다.

• Cursor 2.0 — 최대 8개의 AI agent 병렬 실행. 수는 가장 많지만 각 agent가 독립 작업할 뿐 통신 메커니즘이 없다. 여덟 마리 말이 각자 달릴 뿐, 이들을 묶는 고삐가 없다.
• Codex CLI의 Subagents — 부모 agent의 sandbox 정책과 승인 설정을 상속하고 메인 agent의 컨텍스트 안에서 돌며 위로만 보고한다. 탐색성 하위 과제에 적합, 장시간 독립 작업에는 부적합.

Writer/Reviewer 병렬 패턴

멀티 Agent가 꼭 복잡한 아키텍처일 필요는 없다. 가장 실용적인 패턴은 아마 가장 단순한 것 — 하나는 쓰고, 하나는 심사한다. Anthropic 공식 권장 — 한 Claude가 코드를 쓰고, 다른 Claude가 완전히 새 컨텍스트로 심사한다. 자기 코드에 대한 편견을 회피한다. 이 패턴은 배치 처리로 확장된다.

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

병렬도는 동시에 몇 개의 프로세스를 돌릴 의향이 있는가에 달렸다.

Stripe의 Pipeline 편성

엔지니어가 Slack에 메시지 한 통을 보내고 자리를 뜨면 돌아왔을 때 PR이 준비되어 있다. 주당 1,300+ PR, 전부 인간 수기 코드 제로. 핵심 인프라 — 각 Minion은 표준화된 AWS EC2 인스턴스(devbox) 위에서 돌며 Stripe 전체 코드 트리, 예열된 Bazel·타입 체크 캐시가 사전 설치되어 있다. warm pool에서 devbox 기동은 10초 미만. Stripe의 핵심 통찰 — Minions가 동작하는 첫째 이유는 AI 모델과 거의 무관하며, LLM 이전부터 인간 엔지니어를 위해 쌓은 다년의 인프라 덕분이다. 전면적 테스트 커버리지, 합성 end-to-end 테스트, 신속 롤백의 블루-그린 배포. 하네스는 인프라 위에 세워진다. 인프라가 나쁘면 하네스도 서지 않는다. 모든 AI 생성 PR은 여전히 인간 review를 거치되 자동화된 신뢰 신호에 크게 의존한다 — 인간은 여전히 loop 안에 있고, 위치만 바뀌었다.

언제 멀티 Agent를 쓰는가

멀티 Agent 편성은 매혹적이지만 대부분의 장면은 단일 Agent로 충분하다. Anthropic이 Building Effective Agents에서 준 판단 기준 — 단일 LLM 호출로 풀리는 일에 Agent를 쓰지 마라. Agent는 단계 수를 예측할 수 없고 고정 경로를 하드코딩할 수 없는 개방형 문제에 적합하다. 같은 논리를 한 층 올리면 — 단일 Agent로 풀리는 일에 멀티 Agent를 쓰지 마라.