이 글은 Building with Claude Code의 파트 2입니다. 파트 1에서는 프리랜서 웹 개발을 위한 기본적인 .claude/ 폴더 설정에 대해 다루었습니다. 저는 몇 달 동안 Claude Code를 사용해 왔습니다. 대부분의 개발자와 마찬가지로, 저도 처음에는 빠른 자동 완성(Autocomplete) 용도로 사용하기 시작했습니다. 질문을 입력하고, 코드를 받고, 이를 반복하는 방식이었죠. 문제는 매 세션(Session)이 처음부터 다시 시작된다는 점이었습니다. 프로젝트 상태에 대한 기억도 없고, 하던 작업에서 바로 이어갈 방법도 없으며, 세션 전반에 걸쳐 유지될 구조도 없었습니다. 그래서 저는 구조화된 시스템을 구축했습니다. 여기 그 아키텍처(Architecture)와 이를 작동하게 만든 핵심 통찰이 있습니다.

"챗봇 모드(Chatbot Mode)"의 핵심 문제
Claude Code를 챗봇처럼 사용할 때, 여러분은 매 세션마다 암묵적으로 컨텍스트(Context)를 다시 구축하고 있는 것입니다. 프로젝트를 다시 설명하고, 제약 사항을 다시 설명하고, 현재 어디까지 진행되었는지 다시 설명해야 합니다. 속도는 빠르지만, 매번 설정 비용을 지불하는 셈입니다. 또 다른 문제는 챗봇에게는 의사 결정 프레임워크(Decision Framework)가 없다는 것입니다. 챗봇은 즉흥적으로 행동합니다. 때로는 그것이 훌륭할 수 있지만, 장기적으로 실행되는 자율 작업(Autonomous work)에서 즉흥성은 실패 모드(Failure mode)가 됩니다.

아키텍처: 4가지 구성 요소

1. 프로젝트 DNA로서의 CLAUDE.md
   이것은 필수적인 스타트업 파일(Startup file)입니다. Claude Code는 어떤 작업을 수행하기 전에 이 파일을 가장 먼저 읽습니다. 잘 작성된 CLAUDE.md는 다섯 가지 섹션을 포함합니다:

• Identity (정체성) — 프로젝트가 무엇인지, 어떤 스택(Stack)을 사용하는지, 누가 운영하는지
• Startup sequence (시작 시퀀스) — 세션 시작 시 실행할 정확한 단계 (이 파일 읽기, RUNBOOK.md 읽기, 진단 실행 등)
• Autonomous permissions (자율 권한) — Claude가 묻지 않고 할 수 있는 일과 인간의 승인이 필요한 일
• Current state (현재 상태) — 3줄 요약: 현재 단계, 마지막 작업, 다음 작업
• Rules (규칙) — 5~10개의 타협 불가능한 제약 사항

자율 권한(Autonomous permissions) 섹션은 대부분의 사람들이 건너뛰는 부분이지만, 가장 중요합니다. 이 섹션이 없으면 시스템은 모든 것에 대해 허가를 요청하거나(번거로움), 모든 것에 대해 허가가 있다고 가정하게 됩니다(위험함). 이 섹션을 통해 경계를 정확하게 정의할 수 있습니다. 매 세션 종료 시 업데이트되는 현재 상태(Current state) 섹션 덕분에, 새로운 세션은 30초 이내에 방향을 잡을 수 있습니다.

2. YAML 프론트매터(Frontmatter)를 활용한 특화된 에이전트(Specialized Agents)
   에이전트들은 .claude/agents/ 폴더에 거주합니다.

각 에이전트는 다음과 같은 YAML Frontmatter를 포함하는 마크다운 (Markdown) 파일입니다:

---

name : judge
description : "기회 점수를 0-100점으로 매기고, Top5/Top3를 선정합니다. 읽기 전용 액세스."
tools : Read, Glob, Grep
model : sonnet
permissionMode : default

핵심 통찰: 각 에이전트에게 역할에 정확히 필요한 도구만 부여하고, 그 이상은 주지 않는 것입니다.

• Scout: WebSearch, WebFetch, Write (data/pipeline/ 폴더에만 작성 가능)
• Judge: Read, Glob, Grep (점수 산정만 수행, 쓰기 권한 없음)
• Builder: Read, Write, Edit — 단, experiments/<id>/ 내부에서만 가능
• Compliance: 모든 내용 읽기 가능, docs/swarm/COMPLIANCE_REVIEW_*.md 파일에만 쓰기 가능
• Treasury: data/portfolio/ 읽기 가능, data/portfolio/에만 쓰기 가능

제약 사항(Constraints)은 기능(Features)입니다. 제약 사항은 시스템을 예측 가능하게 만듭니다. 거버넌스(Governance) 파일을 건드릴 수 없는 Builder는 자율적으로 실행할 수 있다고 신뢰할 수 있는 Builder입니다.

비용 관리를 위해 모델 계층화(Model layering)가 중요합니다:

• Scout는 Haiku에서 실행: 저렴하고 빠르며, 웹 검색 및 추출에 충분합니다.
• Judge와 Builder는 Sonnet에서 실행: 의사결정에 중요한 단계에 필요한 더 나은 추론 능력을 제공합니다.
  모든 작업에 가장 비싼 모델이 필요하지는 않습니다.

3. 안전 계층(Safety Layer)으로서의 settings.json
   이곳은 거버넌스가 단순히 문서화되는 것을 넘어, 런타임(Runtime) 시점에 실제로 강제되는 지점입니다:

{
  "permissions" : {
    "deny" : [
      "Read(./.env)" ,
      "Read(./.env.*)" ,
      "Bash(rm -rf *)" ,
      "Bash(curl *)"
    ],
    "ask" : [
      "Bash(*)"
    ],
    "allow" : [
      "Read" ,
      "Write" ,
      "Edit" ,
      "Glob" ,
      "Grep"
    ]
  }
}

.env 파일은 단순히 접근 금지라고 문서화된 것이 아니라, 런타임 수준에서 읽을 수 없도록 차단됩니다. 모든 Bash 명령은 실행 전 인간의 승인이 필요합니다. 거부 목록(deny list)이 실제적인 안전 경계(safety boundary) 역할을 합니다.

4. 심박수(Heartbeat)로서의 RUNBOOK.md
   항상 최신 상태를 유지하는 단 하나의 파일:

RUNBOOK

최종 업데이트: 2026-03-31 14:32

현재 단계: Build — exp_002

마지막 작업: Builder가 14:32에 가이드 완료

다음 작업: 인간이 ZIP 파일을 생성하여 Gumroad에 업로드

예정된 작업: /portfolio-review (D+1), /kill-or-scale (D+14)

이 파일을 읽는 에이전트는 현재 어떤 일이 일어나고 있는지 정확히 알게 됩니다. 다시 설명할 필요가 없습니다. 30초 만에 문맥(Context)이 복구됩니다.

의사결정 파이프라인 (The Decision Pipeline)
시스템은 코드를 건드리기 전에 모든 아이디어를 다음의 파이프라인을 통해 실행합니다: 발견 (DISCOVERY) → 점수 산정 (SCORING) → 준수 여부 확인 (COMPLIANCE) → 결정 (DECISION) → 빌드 (BUILD) → 출시 (LAUNCH). 각 단계에는 명시적인 거절 기준이 있습니다. 이 파이프라인은 구축한 아이디어보다 더 많은 아이디어를 폐기해 왔습니다 — 그것이 바로 핵심입니다.

점수 산정 모델 (Scoring model): 10가지 차원

• 구매자 명확성 (Buyer clarity): 구매자가 이 문제를 겪고 있다는 것을 알고 있는가?
• 긴급성 (Urgency): 지금 당장 고통스러운 문제인가, 아니면 있으면 좋은 (nice-to-have) 정도인가?
• 빌드 속도 (Build speed): 8시간 이내에 출시할 수 있는가?
• 지원 부담 (Support burden): 이것이 지원 티켓을 생성할 것인가?
• 스택 적합성 (Stack fit): 우리가 가진 것으로 구축할 수 있는가?

• 기타 5가지 차원

자동 거절 규칙 (Auto-reject rules): 점수 < 50, 빌드 시간 > 8시간, 지원 부담 > 월 2시간.
결과: 실제로 성공할 가능성이 있는 것들만 구축하게 됩니다.

운영하며 배운 점 (What I Learned Running This)
거버넌스 계층 (Governance layer)은 가장 가치 있는 부분이지, 결코 사소한 부분이 아닙니다. 엄격한 금지 사항을 작성하는 것은 시스템의 목적을 명확히 하도록 강제합니다. "유료 광고 지출 금지" 및 "매일 수동 개입 불필요"는 제약 사항이 아닙니다 — 그것은 당신이 명확하게 생각하고 있을 때, 즉 빌드 중간에 편법을 쓰고 싶은 유혹에 빠지기 전에 미리 내려진 설계 결정 (Design decisions)입니다.

RUNBOOK.md는 예상보다 훨씬 중요합니다. 업데이트를 건너뛸 때마다 다음 세션은 고통스러웠습니다. 최신 상태를 유지할 때마다 다음 세션은 30초 만에 시작되었습니다.

모델 계층화 (Model layering)는 실제 비용을 절감해 줍니다. Haiku에서 발견 (Discovery) 과정을 실행하고, 실제 결정 단계에서만 Sonnet으로 에스컬레이션(Escalating)하는 방식은 전체 시스템을 대규모에서도 지속 가능하게 만들었습니다.

빠른 시작 (Quick Start) (파일 3개, 10분)
6개 에이전트 전체 시스템이 필요하지는 않습니다. 다음으로 시작해 보세요:

• CLAUDE.md — 정체성, 시작 시퀀스, 자율 권한, 현재 상태, 5가지 규칙
• RUNBOOK.md — 현재 단계, 마지막 작업, 다음 작업
• .claude/settings.json — .env 거부, rm -rf 거부, 모든 Bash 명령에 대해 확인 요청
  10분의 설정만으로도, 당신의 다음 Claude Code 세션은 근본적으로 다르게 느껴질 것입니다.

추가 읽을거리 (Further Reading)
에이전트 템플릿, 기술 템플릿, 그리고 치트 시트가 포함된 구조화된 가이드로 전체 7단계 청사진을 정리해 두었습니다:
The Blueprint Method on Gumroad — $27.

Revenue Swarm OS(이 글에서 설명하는 시스템)는 이 방법론이 실제로 작동함을 보여주는 실질적인 증거입니다. 코드베이스는 스스로 구축되었습니다. 프리랜서 웹 개발을 위한 사전 제작된 파일들(CLAUDE.md 템플릿, 에이전트, 스킬)만 원하신다면: Claude Code Skill Folders — $19. 질문이나 아키텍처(Architecture)에 대한 피드백은 댓글로 환영합니다. 파트 3: 중단/확장 결정 로직 — 시스템이 언제 자산을 계속 밀어붙일지, 그리고 언제 중단할지를 결정하는 방법.