저자: 최호림 (AI-Native, 돌아온 실버 개발자) 분량: 1779 줄 / A4 ≥ 40 쪽 (본문) + 부록 7 쪽 목적: CLAUDE.md 가 바이브 코딩 시대 헌법 임을 풀어 — 돌아온 실버 개발자가 AI 에이전트를 지휘하는 첫 1 줄 을 박는 법.

---

CLAUDE.md 파일 이해

설계 없이는 코드 한 줄도 없다 — 바이브 코딩 시대 헌법 입법자의 첫 책

저자: 최호림 (AI-Native, 돌아온 실버 개발자) 작성일: 2026-05-12 (v0.1 draft) 분량 목표: A4 ≥ 40 쪽 (본문) + 부록 7 쪽

---

목차

---

들어가며 — 프로그래밍 언어의 패러다임 전환

1. 80 년의 침묵 — 컴퓨터는 사람 말을 듣지 않았다

1.1 폰 노이만의 정리 (1945) — 80 년 컴퓨팅의 토대

1945 년 6 월, 폰 노이만(John von Neumann)은 EDVAC 보고서 초안 (First Draft of a Report on the EDVAC) 을 정리했다. 단 101 페이지짜리 미공식 문서 였다. 그러나 그 문서가 — 이후 80 년의 모든 컴퓨터를 정의 했다.

폰 노이만 아키텍처의 핵심 5 원리:

이 다섯 가지가 — 지금도 — 모든 CPU 의 기본 골격이다. Intel x86, ARM, RISC-V, Apple M3, NVIDIA H100 — 모두 폰 노이만 아키텍처의 후계자.

폰 노이만 아키텍처에서 가장 혁명적인 한 줄 은 — 명령어를 데이터처럼 메모리에 저장 한다 는 발상이었다. 이전에는 명령어는 회로로 박혀 있고 데이터만 메모리 였다 (예: ENIAC). 폰 노이만은 명령어도 데이터다 — 같은 메모리에 둘 다 저장 — 따라서 *프로그램이 다른 프로그램을 작성할 수 있다. 이 단순한 통찰이 — 컴파일러·인터프리터·운영체제·AI 모두를 가능하게 했다.

★ 80 년 후의 LLM 도 폰 노이만 후계자다. LLM 의 context window 는 — 명령어 (프롬프트) 와 데이터 (대화 히스토리) 를 같은 공간에 저장 한다. 카파시의 "LLM = OS, Context = RAM" 비유 (Chapter 1 §1.3) 는 — 우연이 아니다. 폰 노이만 아키텍처의 자연스러운 진화.

폰 노이만 아키텍처의 그늘 도 80 년 내내 따라다녔다 — 폰 노이만 병목 (von Neumann bottleneck). CPU 처리 속도가 메모리 대역폭보다 훨씬 빠르다. 그래서 CPU 는 메모리를 기다리며 놀고 있다. 이 병목이 — 캐시 계층, GPU 의 고대역폭 메모리, 그리고 오늘날 HBM (High Bandwidth Memory) 까지 — *모든 메모리 기술의 진짜 동기. 부록 A 에서 다시 만난다.

1.2 프로그래밍 언어의 진화 — 낮은 추상 → 높은 추상

폰 노이만 아키텍처는 명령어를 입력받기만 한다. 어떤 형태의 명령어인가 는 — 80 년간 언어 진화의 역사 였다.

핵심 관찰: 언어가 진화할 때마다 추상화 수준이 한 단계 올라갔다. 매 단계마다 프로그래머는 더 적게 알고도 일할 수 있게 되었다. 그러나 — 각 단계의 책임이 어디론가 이동 했다. 어셈블리 시대에는 메모리 레이아웃 을 사람이 설계했다. C 시대에는 함수 분해 를 사람이 설계했다. OOP 시대에는 클래스 계층 을. 그 설계 (design) 가 — 80 년 내내 컴퓨터가 모르는 영역 이었다.

1.3 설계 도구의 진화 — 손그림 → 디지털

설계가 프로그래머의 머릿속 에만 있으면 — 팀이 공유할 수 없다. 재사용할 수 없다. 검증할 수 없다. 그래서 — 언어 진화와 평행하게 — 설계 도구의 진화 가 따라왔다.

핵심 관찰 1 — 설계 도구는 손그림에서 디지털로 이동했다. 1949 의 플로차트는 연필과 종이 였다. 2026 의 CLAUDE.md 는 git 으로 버전 관리되는 마크다운. 그러나 — 기능은 동일하다. 프로그래머의 머릿속을 외재화 하여 팀·미래 자신·검증 도구가 읽을 수 있게 하는 것.

핵심 관찰 2 — 2001 년 애자일이 설계 도구를 거의 죽였다. "작동 코드가 최고의 설계 문서" 라는 명제 아래 — UML 은 과한 도구 로 평가받고, 많은 팀이 설계 문서를 생략 했다. 그리고 10 년이 흘렀다. 코드만 있고 설계는 어디에도 없는 시스템들이 — 유지보수 불가능 한 상태에 빠졌다. 애자일의 그늘 이었다.

핵심 관찰 3 — 2026 년 그 모든 사라진 설계 도구가 부활 한다. 단, 형태가 변했다. 사람을 위한 다이어그램 이 아니라 AI 가 읽는 마크다운. 다음 절에서 이 부활 의 본질을 본다.

1.4 두 축의 수렴 — 자연어 + 마크다운, 같은 자리에서 만난다

위 §1.2 와 §1.3 의 두 표를 나란히 놓으면 — 80 년의 평행 진화가 2026 년에 정확히 한 점으로 수렴 한다.

[언어 진화]
기계어 → 어셈블리 → FORTRAN → C → Java → Python → ... → 자연어 (2026)
                                                              ↓
                                                      [AI 가 코드 작성]
                                                              ↑
플로차트 → HIPO → DFD → ERD → UML → ADR → C4 → ... → CLAUDE.md (2026)
[설계 도구 진화]

언어가 자연어로 수렴 하는 순간, 설계 도구도 마크다운으로 수렴 한다. 둘이 같은 자리 에서 만난다. 만나는 자리의 이름이 — 바이브 코딩 (Vibe Coding) 이다.

1.5 미리 보기 — 부활한 설계 도구들이 바이브 코딩의 4 층 인프라 로 통합된다

본 책 Chapter 6 에서 본격 다루겠지만 — 미리 한 줄만 정리한다. 위 설계 도구 진화 표 의 모든 도구 가 — 2026 년 바이브 코딩에서 디지털 등가물 로 부활했다. 게다가 — 4 층 인프라 로 재조직 되었다.

*돌아온 실버 개발자에게는 낯익은 풍경. *후배 개발자에게는 처음 보는 도구. 이 비대칭이 — 본 책이 돌아온 실버 개발자에게 압도적으로 유리 한 이유다. 4 층 인프라는 새로운 발명이 아니다 — 부활 이다.

1.6 폰 노이만 병목의 부활 — 80 년 후 더 결정적

마지막으로 한 가지 — 폰 노이만 아키텍처의 그늘이었던 병목 이 2026 년에 더 결정적 이 되었다.

폰 노이만 병목 (CPU 처리 속도 ≫ 메모리 대역폭) 은 — 1940 년대에는 컴퓨터가 너무 느려서 문제가 안 됐다. 1980 년대에는 캐시 계층 으로 일부 해결했다. 2010 년대에는 GPU 의 고대역폭 메모리 로 AI 시대의 토대 가 되었다.

2026 년 — LLM 의 등장 으로 그 병목이 폭발 했다. 모델 파라미터 수조 개, context window 수십만 토큰, 어텐션 메커니즘의 O(N²) 계산량 — 모두 메모리 대역폭이 부족 해서 느리고 비싸다. HBM (High Bandwidth Memory) 의 공급 부족 이 지금 산업 최대 병목 이다. 부록 A 에서 자세히 다룬다.

이 사실의 함의는 — 무거운 명제 하나다. CLAUDE.md 잘 쓰기 = 토큰 절약 = 폰 노이만 병목의 정면 대응. 80 년 전 폰 노이만이 만든 아키텍처의 그늘 을 — 오늘 우리가 CLAUDE.md 한 줄로 완화 하는 것 이다. 헌법 설계가 — 물리학과 만난다.

1.7 코드의 흡수 — 신경망에는 if 문이 없다 (Software 1.0/2.0/3.0)

§1.2 의 언어 진화 표 와 §1.3 의 설계 도구 진화 표 — 둘 다 암묵적 가정 위에 서 있다. 사람이 코드를 짠다 는 가정이다. 컴파일러·인터프리터·UML — 모두 사람이 짤 코드를 더 쉽게 짜도록 돕는 도구 였다.

그러나 2017 년, 카파시는 이 가정 자체를 부정하는 글 을 썼다 — "Software 2.0" 에세이.

1.7.1 카파시의 3 단계 패러다임

Software 2.0 의 발견은 — 매우 깊다. 신경망 안을 들여다보면 if 문도, for 루프도, switch case 도 없다. 오직 행렬 곱셈 (matrix multiplication) + 활성화 함수 + 가중치 만 존재한다. 가중치는 수십억~수조 개의 실수 일 뿐 — 사람이 읽을 수 있는 코드가 아니다. 해석 가능성 (interpretability) 문제 가 Software 2.0 의 본질적 그늘 이다.

이미지 인식이 그 단적 사례다. 1.0 시절에는 고양이 인식 을 위해 수천 줄의 픽셀 비교 if 문 을 작성했다. 2.0 시절에는 수백만 장의 고양이 사진 으로 CNN 을 학습 시켰다. if 문은 사라졌다. 가중치만 남았다. 코드가 신경망 속으로 흡수 되었다.

1.7.2 Software 3.0 — 코드와 큐레이션 모두 추상화

2025 년 카파시의 YC keynote 가 정리한 Software 3.0 의 본질:

사람이 코드를 짜지 않는다. 데이터도 큐레이션하지 않는다. 자연어로 지시 한다. 그러면 LLM 이 — 코드 + 큐레이션 + 추론 + 검증 까지 — 모두 한다.

그렇다면 우리의 일은 어디로 갔는가?

우리의 손에서 코드가 점점 빠져나간다. 그 빈자리에 — 지침과 설계만 남는다. 그래서 — "No Design, No Code" 가 공허한 표어가 아니라 물리적 현실 이다. *80 년 동안 사람이 짰던 코드 자체가 AI 신경망 속으로 사라지고 있기 때문 이다.

1.7.3 헌법 메타포의 더 깊은 정당성

이 패러다임 전환이 — 헌법 메타포의 진짜 근거 다. 왜 CLAUDE.md 가 원칙으로만 작성되어야 하는가? 왜 if 문 같은 구체 명령 이 아닌 추상 원칙 인가?

답: if 문은 이미 신경망 속에 있기 때문이다. 우리가 더 작성할 필요가 없다. 신경망의 가중치가 — 이미 학습된 수백만 줄의 if 문 등가물 을 흡수 했다. 우리가 작성해야 할 것은 — 그 신경망이 어떤 방향으로 행동할지의 원칙 이다. 헌법이 구체 시행규칙 을 정의하지 않고 원칙 만 정의하는 이유와 완전히 동일 하다.

헌법은 if/for 가 아니다. 원칙이다. CLAUDE.md 도 if/for 가 아니다. 원칙이다. 시행규칙·시행령 (구체 동작) 은 — AI 의 신경망과 4 층 인프라가 알아서 한다. 입법자의 일은 원칙을 작성하는 것.

1.7.4 Anthropic 의 구체성 원칙과의 정합 (모순 ❌)

이 통찰은 Anthropic 공식 4 작성 원칙 (Chapter 4) 의 원칙 3 — 구체성 과 얼핏 모순 처럼 보인다. 구체적으로 작성하라 했는데 원칙으로 작성하라 한다. 모순인가?

아니다. 답은 층위의 차이. 다음 표가 풀어준다.

CLAUDE.md 의 구체성 은 — if/for 의 구체성이 아니라 행동 원칙의 구체성. "npm test 실행" 은 원칙의 구체적 적용 이지 알고리즘 코드 가 아니다. 4 층 인프라의 나머지 3 층 이 코드의 구체성 을 담당한다.

1.7.5 돌아온 실버 개발자에게 — 기억의 부활

이것이 — 돌아온 실버 개발자가 가장 쉽게 도달할 수 있는 통찰 이다.

1990s 의 사내 Coding Standard Document 가 — 알고리즘 코드가 아니라 행동 원칙 이었음 을 기억하기 때문이다. "네이밍은 camelCase", "한 함수 50 줄 이하", "외부 라이브러리는 PR 승인 후 추가" — 모두 if 문이 아니라 원칙 이었다. 코드는 프로그래머가 작성 했고, 원칙은 팀이 합의 했다. 헌법과 시행규칙의 분리 — 우리는 이미 알고 있었다.

2026 년의 변화 — 코드는 AI 가 작성 한다. 우리는 원칙만 작성 한다. 1990s 의 Coding Standard Document 가 유일하게 남은 사람의 영역 이 되었다. 그 문서의 이름이 — CLAUDE.md 다.

후배 개발자에게는 — *코드를 짜는 시대가 지금 끝나고 있다. 무엇을 대신 할지 처음 배우는 중. 돌아온 개발자에게는 — *1990s 부터 해온 일이 지금 유일하게 가치 있는 일 이 되었다. 기억의 부활 이다.

---

이제 80 년의 침묵 은 끝이 났다. 침묵의 끝은 — 코드의 흡수 였다. 그 침묵이 어떻게 끝났는지 — 다음 절에서 본다. 침묵의 끝에는 — 카파시의 한 트윗 이 있었다.

2. 임계점 — 2025 년 12 월, 모든 것이 바뀌었다

2026 년 1 월 26 일, AI 분야에서 가장 신뢰받는 목소리 중 하나인 안드레이 카파시(Andrej Karpathy) — 전 OpenAI 창립 멤버이자 전 Tesla AI 디렉터, '바이브 코딩(vibe coding)' 이라는 용어를 처음 만든 사람 — 가 X 에 글을 올렸다.

"Easily the biggest change to my basic coding workflow in 2 decades." ("제 코딩 워크플로우의 지난 20 년간 최대 변화 입니다.")

그는 11 월까지 80% 수동 + 20% 에이전트로 일하다가, 12 월 한 달 만에 20% 수동 + 80% 에이전트 로 위상 전환(phase shift) 했다고 말했다. 그의 진단은 명료했다: "LLM 에이전트 능력이 2025-12 경 어떤 일관성의 임계값을 넘어섰다."

이날 이후 109,000 명이 단 한 줄의 GitHub 별을 눌렀다 — 사실은 단 한 파일 의 저장소에다. 그 파일의 이름은 CLAUDE.md 였다.

3. 위기 — 사람 말로 시키니 경계가 무너졌다

컴퓨터가 사람 말을 듣기 시작한 순간, 우리는 한 가지를 잊어버렸다. 사람 말은 모호하다.

"테스트 잘 짜줘" 라고 하면 AI 는 어떻게든 테스트를 짠다. mock 으로도 짜고, 100 줄짜리 클래스도 만들고, 우리가 생각하지 않은 추상화 까지 다 기록해 넣는다. "한국어로 답해" 라고 적어 놨는데도 영어로 답한다. "이 폴더 건드리지 마" 라고 했는데도 또 건드린다.

문제는 더 깊이 있다. AI 의 작업 메모리, 즉 context window 는 유한 하다. 카파시는 이를 RAM 에 비유했다:

"LLMs are like a new kind of operating system. The LLM is the CPU, and its context window is like the RAM." ("LLM 은 새로운 형태의 운영체제다. LLM 은 CPU 이고, context window 는 RAM — 모델의 작업 메모리다.")

RAM 이 가득 차면 OS 는 swap 으로 디스크 IO 를 발생시키고, 결국 느려진다. LLM 의 context window 가 가득 차면 — 이전 지시사항을 잊고, 실수를 늘리고, 결국 폭주한다. 이 현상을 산업계는 Context Rotting 이라 부른다.

토큰은 희소한 자원 이다. 하지만 동시에 — 낭비되기 쉬운 자원 이다.

4. 해법 — 헌법이 필요하다

이쯤에서 우리는 국가의 작동 원리 에서 답을 찾을 수 있다. 모호한 사람들의 모임이 어떻게 모순 없이 작동하는가? 헌법이 있기 때문이다. 헌법 아래에 법률, 법률 아래에 시행령, 그리고 행정규칙. 위에서 아래로 상위법 우선 원칙 이 흐른다.

바이브 코딩 시대에도 같은 구조 가 필요하다. 매번 입력하지 않아도 AI 가 읽고 따르는 영구 지시어 — 컴퓨터에게 지속적으로 알려주는 일종의 헌법. 그 헌법의 이름이 바로 CLAUDE.md 다.

CLAUDE.md 는 Claude Code (Anthropic 의 코딩 에이전트) 가 매 세션 시작에 자동으로 읽는 마크다운 파일이다. 4 곳에 둘 수 있다. 관리 정책 (헌법), 프로젝트 (법률), 사용자 (시행령), 로컬 (시행규칙). 위에 있을수록 모든 하위를 구속 한다.

이 파일을 잘 쓰면 — 토큰이 절약되고, AI 가 같은 실수를 반복하지 않고, 결과 품질이 2~3 배 올라간다. 잘못 쓰면 — 부풀려진 매뉴얼이 되어 Claude 가 실제 지시를 무시 하고, 토큰은 남발 되며, 시스템은 Context Rotting 으로 무너진다.

5. 이 책의 안내 — 헌법에 법률 을 넣지 마라

많은 개발자가 CLAUDE.md 를 잘못 쓰고 있다. 가장 흔한 실수는 — README 에 들어갈 내용 까지 CLAUDE.md 에 기록하는 것이다. 사람이 읽을 소개 문서 와 AI 가 따를 가드레일 을 구분하지 못한다. 헌법에 법률 조항 까지 다 기록해 버리면, 헌법은 무용지물이 된다.

이 책은 그 경계 를 다룬다. 헌법(CLAUDE.md)에 무엇을 넣고, 무엇을 넣지 않을 것인가. 헌법을 어떻게 설계 하고, 어떻게 고쳐 갈 것인가. 그 모든 살아 있는 입법 과정 이 바이브 코딩 시대 개발자의 새로운 본업 이다.

본 책은 모두 9 장(章, Chapter)으로 구성되어 있다. Part 1 (Chapter 1~3) 에서는 왜 CLAUDE.md 가 헌법인가 의 이론적 기반을 살핀다. Part 2 (Chapter 4~6) 에서는 헌법을 어떻게 잘 쓰는가 의 작성법을 다룬다. Part 3 (Chapter 7~9) 에서는 헌법을 자동으로 진화시키는 두 가지 꿀팁 — 카파시 65 줄 스킬과 Anthropic 공식 플러그인 — 그리고 돌아온 개발자의 30 일 처방 까지 적용한다.

저자는 1990 년대 객체지향 시절부터 코드를 짜온 돌아온 실버 개발자 다. 2010 년대 코딩 현장에서 잠시 멀어졌다가, 2025 년 위상 전환의 시기에 AI-Native 로 복귀했다. 이 책은 후배 개발자 와 복귀를 고민하는 시니어 모두에게 — 돌아온 개발자의 시선으로 — 헌법 입법의 길을 안내한다.

마지막으로 한 가지 약속: 이 책을 다 읽고 나면, 당신의 프로젝트에 오늘 즉시 CLAUDE.md 를 만들고 이번 주 첫 1 줄을 기록하며 이번 달 자가 진화 루프를 구축할 수 있게 된다. 그것이 이 책의 합격 기준 이다. 완벽한 이해 와 즉시 적용 가능 — 둘 다.

이제 시작한다.

---

Part 1 — 왜 CLAUDE.md 인가 (도입부)

Chapter 1 — 컴퓨터가 사람 말을 듣기 시작한 순간

1.1 한국어로 답하라 했는데 영어로 답하는 Claude

처음 Claude Code 를 사용하면 누구나 같은 좌절을 만난다.

"한국어로 답하라 적어 놨는데 영어로 답하고, 이 폴더 건드리지 마라 했는데 또 건드리고. 점점 줄을 추가하다 보면 어느새 CLAUDE.md 가 500 줄짜리 매뉴얼이 되어 있더라고요."

이는 어느 실벨 개발자의 YouTube 강의에 나온 한 구절이다. 청중은 고개를 끄덕인다. 모두 같은 경험 을 했기 때문이다. AI 에게 사람 말로 일을 시키는 시대 — 우리는 왜 그토록 자주 실패하는가?

답은 단순하다. 사람 말은 모호하기 때문이다. 그리고 — 더 중요한 사실은 — 그 모호함을 보완할 메커니즘을 우리가 아직 잘 모르기 때문이다.

1.2 카파시의 80% 전환 — "20 년 코딩 인생 최대 변화"

2026 년 1 월 26 일 카파시의 트윗은 증언 이었다.

• 2025 년 11 월: 80% 수동·자동완성 + 20% 에이전트
• 2025 년 12 월 ~ 2026 년 1 월: 20% 수동 + 80% 에이전트

한 달 만의 위상 전환. 카파시는 "내 20 년 코딩 인생 최대 변화" 라고 표현했다. 이 시점이 곧 AI-Native 시대의 임계점 이었다.

이 트윗이 나온 다음 날 — Forrest Chang(중국명 Jiayuan Zhang)이라는 한 개발자가 카파시의 관찰을 65 줄짜리 CLAUDE.md 한 장 으로 정리해 GitHub 에 올렸다. forrestchang/andrej-karpathy-skills. 첫 주에 수만 별, 2026 년 4 월 기준 109,000+ 별. GitHub 역사상 가장 별 많은 단일 파일 저장소 중 하나 가 되었다.

수백만 개발자가 동시에 같은 문제 를 경험하고 있었기 때문이다. 그리고 65 줄짜리 단순 텍스트 가 그 문제를 30 초 만에 해결 했기 때문이다.

이 65 줄에 무엇이 기록되어 있었는가? Chapter 7 에서 자세히 다룬다. 다만 미리 한 가지만 — 그 65 줄은 코드 가 아니었다. 영어로 쓴 행동 규제 규칙 이었다. 바이브 코딩 시대의 첫 입법문(立法文)* 이었다.

1.3 LLM = OS, Context Window = RAM

카파시의 트윗에서 가장 철학적인 한 줄 은 다음이었다.

"LLMs are like a new kind of operating system. The LLM is the CPU, and its context window is like the RAM, serving as the model's working memory."

(LLM 은 새로운 형태의 운영체제다. LLM 은 CPU 이고, context window 는 RAM — 모델의 작업 메모리 역할.)

이 비유가 왜 중요한가? 자원 관리의 본질 을 짚었기 때문이다. RAM 이 가득 차면 OS 는 swap 으로 디스크에 데이터를 내보내고, 결과적으로 느려진다. LLM 의 context window 가 가득 차면 — 이전 지시를 잊고, 실수를 늘리고, 끝내 폭주한다. 산업계는 이 현상을 Context Rotting (컨텍스트 부패) 라 부른다.

Cognition Labs(Devin 의 회사)의 한 마디로 정리하자면: "Context engineering is effectively the #1 job of engineers building AI agents."

즉 AI 엔지니어의 #1 책무는 코드가 아니라 컨텍스트 관리. 그리고 그 관리의 가장 중요한 수단 이 — 이 책의 주인공인 — CLAUDE.md 이다.

1.4 돌아온 개발자의 시선 — 1990s RAM 256KB 시절의 자산

여기서 돌아온 실버 개발자 는 미소를 짓는다.

1990 년대, 우리는 256KB RAM 으로 일했다. Photoshop 2.0 이 7MB 메모리를 요구하던 시절, 우리는 매일 메모리 누수 와 싸웠다. malloc / free 를 손으로 짝맞추고, 스택 오버플로우를 수동으로 디버그하며, 어셈블리 레벨 의 자원 절약 본능을 길렀다.

그 본능이 지금 다시 필요하다. Karpathy 의 "Context = RAM" 비유는 — 돌아온 개발자에게는 고향 풍경 이다. 희소한 자원의 조직화 — 이것이 1990s 의 일이었고, 2026 의 일이다. 다만 도구가 malloc 에서 CLAUDE.md 로 바뀌었을 뿐이다.

후배 개발자는 256KB 시절의 자원 관리 본능 이 없다. 무한 클라우드, 무한 RAM, 무한 컴퓨팅으로 자라 왔기 때문이다. 그래서 그들에게는 Context = RAM 비유가 새로운 공부 다. 돌아온 개발자에게는 복습 이다.

1.5 처방 — 오늘 즉시 /statusline 으로 토큰을 모니터링하라

이 책의 모든 챕터 는 오늘 즉시 실행 가능한 처방 으로 끝난다. Chapter 1 의 처방은 단순하다.

# Claude Code 를 실행한 후 명령어 입력
/statusline

이 명령은 현재 세션의 토큰 사용량 + 비용 + context window 점유율 을 상태 줄 에 띄운다. RAM 사용량 모니터 와 정확히 같은 역할이다. 5 분 만 보고 있으면 — 한 번의 파일 읽기로 얼마나 많은 토큰이 소비되는지 가 눈에 들어온다.

처방 1 (Day 0): /statusline 활성화 후 1 시간 작업하면서 토큰이 가장 많이 빠지는 순간 을 기록하라.

이것이 Context = RAM 비유의 체험적 학습 이다. 다음 챕터에서는 — 왜 CLAUDE.md 가 그 RAM 의 운영체제 설정 파일 인지를 보겠다. 즉 왜 헌법인가 의 본격 논증이다.

---

Chapter 2 — CLAUDE.md = 바이브 코딩의 헌법

2.1 헌법 메타포의 출발 — 4 위치 ↔ 한국 법체계

Anthropic 의 공식 문서는 CLAUDE.md 를 네 곳에 둘 수 있다 고 명시한다. 더 구체적인 위치가 더 광범위한 위치보다 우선 한다.

이 표를 보는 순간 — 돌아온 실버 개발자에게는 매우 익숙한 구조 가 떠오른다. 대한민국 법체계 다.

이는 단순한 비유 가 아니다. 작동 원리가 정확히 일치 한다. 한국 법체계의 상위법 우선 원칙 — 헌법 > 법률 > 시행령 > 시행규칙 — 이 CLAUDE.md 우선순위 규칙 과 완전히 동일하다.

2.2 상위법 우선 원칙 — 충돌은 어떻게 해결되는가

법체계에서 헌법과 법률이 충돌하면 — 헌법이 이긴다. 법률과 시행령이 충돌하면 — 법률이 이긴다. 위에 있는 것이 강하다.

CLAUDE.md 도 동일하다. 사용자 (~/.claude/CLAUDE.md) 에서 "커밋 메시지는 영어로" 라 했는데, 프로젝트 (./CLAUDE.md) 에서 "이 저장소만 한국어" 라 했다면 — 이 저장소에서는 한국어 가 적용된다. 더 구체적인 (= 더 좁은 범위의) 지침이 더 강하다. 이것이 상위법 우선 원칙 의 역방향 시점 이다.

다만 — 한 가지 특수 경우 가 있다. 관리 정책 CLAUDE.md 는 개별 사용자가 제외할 수 없다. claudeMdExcludes 설정으로 다른 CLAUDE.md 는 건너뛸 수 있어도, 관리 정책 CLAUDE.md 는 항상 적용 된다. 이는 한국 헌법의 강제력 과 정확히 같다 — 개인이 나는 헌법을 안 따른다 고 선언할 수 없는 것과 같이.

조직 IT 관리자가 회사 전체의 보안 가이드라인 을 관리 정책 CLAUDE.md 에 기록하면 — 그 회사 모든 개발자의 모든 프로젝트에 동시 적용 된다. 헌법 입법 의 디지털 형태다.

2.3 두 비유의 방향 차이 — 강의 핵심 주의

여기서 한 가지 조심해야 할 미묘한 차이 가 있다. 본 책의 헌법 메타포 와 — Claude Code 의 8 레이어 컨텍스트 우선순위 의 방향이 반대 다.

8 레이어 컨텍스트란 Claude Code 가 매 요청에 자동으로 쌓는 8 개 레이어 다.

1. 시스템 프롬프트
2. 도구 (Tool) 정의
3. 전역 CLAUDE.md           (~/.claude/CLAUDE.md)
4. 프로젝트 CLAUDE.md       (<repo>/CLAUDE.md)
5. CLAUDE.local.md          (<repo>/CLAUDE.local.md)
6. 서브디렉토리 CLAUDE.md   (<sub>/CLAUDE.md)
7. 대화 히스토리
8. 현재 사용자 메시지        ← 가장 강력

여기서는 아래로 갈수록 강력 하다. 서브디렉토리 CLAUDE.md 가 전역 CLAUDE.md 와 충돌하면 — 서브디렉토리가 이긴다. 더 현장에 가까운 지침이 더 강하다.

왜 두 비유의 방향이 반대인가? 관점이 다르기 때문이다.

• 법체계 비유: 입법 단계 관점 — 헌법이 모법(母法), 법률은 헌법의 위임 으로 존재한다.
• 8 레이어 비유: 실행 단계 관점 — 마지막에 도착한 지침 이 가장 현재 상황 에 맞다.

두 비유는 상보적 이다. 어떤 지침을 어디에 둘 것인가 를 결정할 때는 법체계 비유 가 유용하다 (보편적 → 위, 특수 → 아래). 충돌 시 어느 지침이 작동하는가 를 추적할 때는 8 레이어 비유 가 유용하다 (아래가 이긴다).

2.4 Karpathy 의 LLM = OS 비유 — 헌법 메타포의 더 깊은 토대

카파시는 2025 년 Y Combinator keynote "Software Is Changing (Again)" 에서 더 큰 그림을 그렸다.

"LLMs have properties of utilities, of fabs, and of operating systems => New LLM OS, fabbed by labs, and distributed like utilities."

(LLM 은 유틸리티·반도체 팹·운영체제 의 세 가지 성질을 모두 가진다 → 새로운 LLM OS, 연구소(labs)에서 제조 되고, 유틸리티처럼 배포.)

운영체제(OS)는 무엇을 하는가? 시스템 자원 (메모리·CPU·디스크) 을 추상화하고 관리 한다. 그리고 — 시스템 파일·설정 파일 을 통해 프로그래밍 인터페이스 를 제공한다.

이 표가 보여주는 것은 명료하다. CLAUDE.md 는 OS 의 시스템 설정 파일 등가물 이다. 윈도우의 레지스트리, 리눅스의 /etc/, macOS 의 plist — 그 모든 시스템 운영의 토대 에 해당하는 파일이 — 바이브 코딩 시대에는 CLAUDE.md 다.

OS 가 시스템 파일 없이는 작동하지 못한다. 마찬가지로 LLM 도 CLAUDE.md 없이는 폭주 한다. 이것이 본 책 표어 "No Design, No Code (설계 없이는 코드 없다)" 의 물리적·구조적 근거 다.

2.5 1990s UML 의 디지털 부활 — 운반체만 바뀌었다

돌아온 실버 개발자에게는 이 모든 그림이 이미 본 풍경 이다.

기능은 동일하다 — 설계의 외재화, 팀 공유, 검증 기준. 운반체와 독자만 바뀌었다. 마크다운으로, AI 가 읽는 형태로.

후배 개발자에게는 완전히 새로운 것 이지만, 돌아온 개발자에게는 1990s UML 시절의 본능이 그대로 부활 한다. 패키지 다이어그램 → 헤딩 계층, 클래스 다이어그램 → 코드 스타일 규칙, 시퀀스 다이어그램 → 워크플로우 명세. 그때 우리가 하던 모든 일이 — 지금 CLAUDE.md 로 디지털화 되었다.

돌아온 개발자의 고유 자산: UML 시절의 4 원칙 (크기·구조·구체성·일관성) 을 체화한 상태. CLAUDE.md 의 4 원칙 과 완벽 일치.

2.6 처방 — 첫 CLAUDE.md 를 어디에 둘 것인가 결정

이번 챕터의 처방은 입법자의 첫 결정 이다.

처방 2 (Day 1): 다음 체크리스트로 내가 기록할 지침을 어디에 둘지 결정하라.

5 분만 이 표를 따라가면 — *대부분의 지침이 사실 프로젝트 (법률) 가 아니라 사용자 (시행령) 에 가야 한다는 사실 을 발견하게 된다. 이것이 부풀려진 CLAUDE.md 의 진짜 원인 이다. 법률에 들어갈 것을 헌법에 기록하는 것 — 다음 챕터에서 본격 다룬다.

---

Chapter 3 — 헌법은 README 가 아니다

3.1 한 줄 정의 — 가드레일 이다

CLAUDE.md 가 무엇인지 한 줄로 정의 하면 다음과 같다.

**CLAUDE.md 는 사람을 위한 README 가 아닙니다. Claude 가 같은 실수를 반복하지 않게 만드는 가드레일 입니다.

이 정의를 처음 들었을 때 — 많은 개발자가 충격을 받는다. 왜냐하면 그들은 CLAUDE.md 를 README 처럼 쓰고 있었기 때문이다. 프로젝트 소개, 디렉토리 구조 설명, 시작 가이드. 모두 잘못된 사용법이다.

README 와 CLAUDE.md 는 다른 독자 를 위한 다른 문서 다.

3.2 코드로 알 수 있는 것은 쓰지 않는다 (실벨 강의 1 원칙)

YouTube 의 한 한국 개발자 (필명 실벨) 가 한 강의에서 명료하게 정리한 좋은 CLAUDE.md 의 첫 원칙 은 다음이었다.

"Claude 는 코드를 읽을 수 있다. 그래서 코드를 봐서 알 수 있는 것 은 절대 쓰면 안 된다."

다음은 쓰지 말아야 할 예시다.

그렇다면 — 써야 할 것 은 무엇인가?

3.3 Karpathy 3 실수 모드 — 왜 가드레일이 필요한가

카파시는 트윗에서 LLM 의 3 가지 핵심 실수 모드 를 영문으로 정립했다. 이 셋이 — 가드레일이 왜 필요한가 의 직접 근거다.

실수 모드 ① — Silent Assumptions (조용한 가정)

"The models make wrong assumptions on your behalf and just run along with them without checking. They do not manage their confusion, do not seek clarifications, do not surface inconsistencies, do not present tradeoffs, and do not push back when they should."

요약: 모델은 우리 대신 잘못된 가정을 세우고, 확인 없이 진행 한다. 혼란을 관리하지 않고, 명확화를 구하지 않으며, 불일치를 표면화하지 않고, 트레이드오프를 제시하지 않고, 반박해야 할 때 반박하지 않는다.

실수 모드 ② — Over-Engineering (과도한 엔지니어링)

"overcomplicate code and APIs, bloat abstractions"

요약: 코드·API 를 과도하게 복잡화 하고, 추상화를 부풀린다. 100 줄이면 되는 일을 1000 줄로 기록한다.

실수 모드 ③ — Collateral Changes (부수적 변경)

"They still sometimes change/remove comments and code they don't sufficiently understand."

요약: 충분히 이해하지 못한 주석·코드를 변경·제거 한다. 요청과 무관한 코드도 함부로 손댄다.

이 3 가지 실수 — 어떻게 막을 것인가? 카파시 4 원칙 으로 막는다. Chapter 7 에서 본격 다루지만, 미리 한 줄씩만:

• 실수 ① → Think Before Coding ("Don't assume. Don't hide confusion.")
• 실수 ② → Simplicity First ("Minimum code that solves the problem.")
• 실수 ③ → Surgical Changes ("Touch only what you must.")

이 3 원칙 + 1 (Goal-Driven Execution) = 109K 별 짜리 65 줄 CLAUDE.md 의 전체 내용 이다.

3.4 안티 패턴 표 — 사람 읽기 좋게 ❌ vs AI 실수 안 하게 ✅

YouTube 강의는 다음 대조 표 로 마무리한다 — 본 책에서 가장 자주 인용될 표다.

핵심: CLAUDE.md 를 사람한테 프로젝트 소개 하는 문서로 쓰지 마라. AI 한테 가드레일을 치는 도구 로 써라.

3.5 돌아온 개발자의 시선 — AI = 자신감 있는 무능한 인턴

Reddit 의 한 개발자가 Claude Code 를 다음과 같이 비유했다:

"Claude Code 는 자신감 있지만 무능한 인턴 (confidently incompetent intern) 같다. 빠르고 박식하지만 — 감독 없으면 위험한 지름길을 택한다."

이 비유가 돌아온 개발자에게 정확히 들어맞는다. 신입은 우리가 멘토링 했던 그 모습 그대로다. 1990s 신입은 코드를 작성 했고, 우리가 코드 리뷰 했다. 2026 의 AI 는 코드를 작성 하고, 우리가 CLAUDE.md 로 통제 한다. 메커니즘은 동일 하다.

CLAUDE.md = 멘토 노트의 디지털 등가물. 돌아온 개발자는 이미 멘토 본능 을 갖추고 있다. 단지 그 본능을 마크다운으로 옮기는 작업 만 남았을 뿐이다.

3.6 처방 — 기존 CLAUDE.md 의 50% 를 줄이는 5 분 운동

처방 3 (Day 1~2): 현재 프로젝트의 CLAUDE.md 를 열고, 다음 체크리스트로 50% 를 잘라내라.

체크 항목:

1. 코드로 알 수 있는 내용 — 삭제
2. 폴더 구조 설명 — 삭제 (Claude 가 ls 한다)
3. 함수·클래스 설명 — 삭제 (Claude 가 코드 읽는다)
4. "코드를 깨끗하게" 같은 추상론 — 삭제
5. 자주 변경되는 정보 (버전 번호 등) — 삭제

5 분이면 끝난다. 그리고 남은 30~40% 의 줄 이 — 진짜 가드레일 이다. 그 가드레일에 추가해야 할 새 줄 은 — Claude 가 실수했던 패턴들. 그 작업은 Chapter 5 에서 본격 다룬다.

이제 우리는 Part 1 을 마쳤다. 왜 CLAUDE.md 가 헌법인가 의 기초가 정립되었다. 다음 Part 2 에서는 그 헌법을 어떻게 잘 쓰는가 — Anthropic 공식 작성 4 원칙 + 가장 중요한 1 줄 (실수 즉시 반영) + 100 줄 넘으면 분할 — 의 실무로 들어간다.

---

Part 2 — 헌법을 잘 쓰는 법 (본론)

Chapter 4 — 헌법 작성 4 원칙

4.1 Anthropic 공식 4 원칙 — 크기·구조·구체성·일관성

Anthropic 공식 문서 code.claude.com/docs/ko/memory 는 효과적인 CLAUDE.md 작성 의 4 원칙 을 명시한다. 이 4 원칙은 *돌아온 개발자에게는 1990s UML·코딩 컨벤션의 4 원칙과 정확히 동일 하다.

원칙 1 — 크기 (Size)

CLAUDE.md 파일당 200 줄 이하 를 목표로 한다.

더 긴 파일은 — 더 많은 컨텍스트를 소비 + 준수도가 감소 한다. 즉 부풀려진 CLAUDE.md 가 곧 무용지물이 된다. 이는 직관에 반하는 사실이다 — 더 많이 추가할수록 더 잘 따를 것 같지만, 실제로는 *Claude 가 실제 지시사항을 무시 하게 된다.

Anthropic 의 한 마디:

"부풀려진 CLAUDE.md 파일은 Claude 가 실제 지시사항을 무시 하게 합니다!"

200 줄을 넘으면 어떻게 해야 하는가? 경로 범위 규칙 (.claude/rules/) 으로 분할하거나, @path 가져오기 로 조직화한다. 단 주의 — 가져오기는 토큰 절약 효과가 없다 (모두 시작 시 로드). 진짜 토큰 절약은 경로 범위 규칙 (특정 파일 작업 시만 로드) 만 가능하다. Chapter 6 에서 본격 다룬다.

원칙 2 — 구조 (Structure)

마크다운 헤더와 글머리 기호를 사용해 관련 지침을 그룹화 한다. Claude 는 독자처럼 스캔 하므로, 조밀한 단락보다 구성된 섹션 이 따르기 쉽다.

구조화의 효과는 스캔 가능성 만이 아니다. 지침의 재사용·재구성 도 훨씬 쉬워진다.

원칙 3 — 구체성 (Specificity)

검증할 수 있을 정도로 구체적인 지침을 작성한다. 이 원칙이 가장 자주 위반된다.

핵심 질문: 이 지침을 받은 Claude 가 옳게 했는지 그른지 검증할 수 있는가? 검증 불가능한 지침은 작동하지 않는다.

원칙 4 — 일관성 (Consistency)

두 규칙이 서로 모순 되면 Claude 가 하나를 임의로 선택 한다. CLAUDE.md 파일 전체 + 하위 디렉토리 + .claude/rules/ 를 정기적으로 검토 해 오래되었거나 충돌하는 지침을 제거 한다.

권장: 한 달에 한 번 전체 CLAUDE.md 검토 — 다음 챕터의 claude-md-improver 가 이를 자동화 한다.

4.2 ★ 포함·제외 표 (Anthropic 공식)

Anthropic 의 Best Practices 문서가 정립한 가장 가치 있는 표는 다음이다 — 본 책의 가장 자주 인용할 표.

이 표를 책상 위에 인쇄해 두고 — CLAUDE.md 를 작성할 때마다 "이 줄은 어느 칸에 속하는가?" 자문하라. 오른쪽 (제외) 칸의 내용을 발견하면 — 즉시 삭제하라. 5 분 운동의 핵심이다 (Chapter 3 §3.6).

4.3 부풀려진 CLAUDE.md 의 디버깅 신호

Anthropic 문서는 CLAUDE.md 가 비대해졌다는 신호 2 가지를 제시한다.

신호 1: 규칙에도 불구하고 Claude 가 계속 원하지 않는 작업을 한다. → 파일이 너무 길어 규칙이 노이즈에 손실 되었다.

신호 2: Claude 가 CLAUDE.md 에 답변된 질문을 한다. → 표현이 모호 하거나 위치가 잘못 되었다.

이 두 신호 중 하나라도 보이면 — CLAUDE.md 를 코드처럼 디버깅 해야 한다. 정기적으로 검토하고, 정리하고, 변경 사항을 관찰 한다.

Anthropic 의 명문: "CLAUDE.md 를 코드처럼 취급한다. 문제가 발생하면 검토하고, 정기적으로 정리하고, 변경 사항을 관찰하여 Claude 의 동작이 실제로 변경되는지 테스트 한다."

4.4 ★ 강조 도구 — IMPORTANT / YOU MUST 의 공식 허용

Anthropic 문서가 정립한 가장 실용적인 한 줄 은 다음이다.

"강조 (예: 'IMPORTANT' 또는 'YOU MUST') 를 추가하여 지시사항을 조정하면 준수 (compliance) 를 개선 할 수 있다."

영문 원문:

"Adding emphasis (e.g., 'IMPORTANT' or 'YOU MUST') can tune your instructions to improve compliance."

이 한 줄은 작동 원리 를 알려준다. CLAUDE.md 콘텐츠는 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 후 사용자 메시지로 전달된다. Claude 는 읽고 따르려고 시도 하지만 엄격한 준수를 보장하지 않는다. 그래서 — 강조어 = 권고 가중치를 인위적으로 올리는 공식 트릭 이다.

주의 — 강조의 희소성 이 효과를 만든다

모든 줄에 IMPORTANT 를 기록하면 — 그건 아무 줄에도 IMPORTANT 없는 것 과 동일하다.

권장 비율: CLAUDE.md 전체에서 5% 이하 줄에만 강조어. 헌법의 부칙·강행규정 등가물 — 희소해야 강하다.

4.5 돌아온 개발자의 시선 — 1990s 코딩 컨벤션의 부활

이 4 원칙을 본 돌아온 실버 개발자 의 머리에는 — 1990 년대 사내 Coding Standard Document 가 떠오른다.

1990s 의 코딩 컨벤션 문서 가 — 지금 다시 부활 했다. 다만 독자가 사람에서 AI 로 바뀌었다. 그래서 문체 가 — 명시적·검증 가능·구체적 — 더 엄격 해졌다. 돌아온 개발자는 이미 그 문체를 안다. *후배 개발자는 처음 배운다.

4.6 처방 — CLAUDE.md = 코드 라는 멘탈 모델 기록하기

처방 4 (Day 2~3): CLAUDE.md 의 git 히스토리 를 코드 변경 PR 처럼 관리하라.

구체 단계:

1. CLAUDE.md 의 모든 변경을 별도 커밋 으로 기록한다 (코드 변경과 분리).
2. 커밋 메시지에 추가/수정/삭제 이유 를 기록한다 (예: chore(claudemd): mock 사용 금지 규칙 추가 — issue #123 의 반복 실수 차단).
3. 주간 1 회 git log -- CLAUDE.md 로 최근 변경 을 팀과 공유 한다.

이 운동을 한 달만 하면 — CLAUDE.md 가 진짜 살아 있는 문서 로 자라난다. 다음 챕터에서는 이 살아 있는 문서 의 가장 중요한 한 줄 워크플로우 를 다룬다.

---

Chapter 5 — 가장 중요한 1 줄 — 실수 즉시 반영

5.1 ★★★ Boris Cherny 의 한 마디 — Compounding Engineering

이 책 전체에서 단 한 줄만 가져갈 수 있다면 가져가야 할 것은 다음이다.

★ "Claude 가 실수를 했을 때 그 자리에서 바로 — '이 실수 다시 안 하게 CLAUDE.md 에 반영해 줘' 라고 무조건 말하세요. 이게 제일 High ROI 아이템입니다."

— YouTube 강의 (실벨 개발자) 의 가장 중요한 1 줄.

이 한 줄은 — 놀랍게도 — Claude Code 를 직접 만든 사람 Boris Cherny 의 발언과 완전히 동일 하다.

Boris Cherny — Anthropic 의 개발자이자 Claude Code 의 창시자 — 가 2026 년 1 월 2 일 X 에 올린 트윗 (조회수 800 만) 에서 자신의 워크플로우를 공개하며 다음과 같이 말했다.

"Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time."

("Claude 가 잘못된 행동을 보이면 그때마다 CLAUDE.md 에 추가 — 다음에는 그렇게 하지 않도록.")

Boris 는 이 워크플로우에 공식 명명 을 붙였다 — "Compounding Engineering" (복리적 엔지니어링). 이 한 명명이 — 본 책의 지적 핵심 이다.

5.2 Compounding Engineering 의 복리 (Compounding) 원리

복리 는 금융 용어다. 단리(simple interest)는 원금에만 이자가 붙지만, 복리는 이자에도 이자가 붙는다. 시간이 지날수록 기하급수적으로 누적 된다.

CLAUDE.md 의 모든 추가된 1 줄 은 — 영구적으로 작동한다. 한 번 기록된 규칙은 — 다음 모든 세션에서 반복 효과 를 낸다.

1 분의 기록 → 수십~수백 토큰을 영구 절감. 수십~수백 회의 같은 실수를 영구 차단. 이것이 복리 의 실체다.

5.3 일주일 운용 효과 — CLAUDE.md 가 자라난다

YouTube 강의의 가장 강력한 증언:

"이 워크플로우를 일주일 정도 돌려 보시면 — CLAUDE.md 가 자연스럽게 우리 프로젝트에 딱 맞게 자라나는 것 을 볼 수 있습니다."

이 자라난다 (grows) 라는 동사가 핵심이다. CLAUDE.md 는 한 번에 완벽하게 작성하지 않는다. 어떤 실수가 나올지 사전에 알 수 없기 때문이다. 실수가 발생하는 그 순간마다 — 1 줄씩 기록한다. 한 달 후 — 그 줄들이 프로젝트의 DNA 가 된다.

돌아온 개발자의 고유 자산: 1990s 의 멘토 워크플로우 와 정확히 동일. 신입의 실수를 그때마다 메모지 에 적었다. 주간 1:1 때 다시 가르쳤다. 한 달이면 신입이 팀의 일원 이 되었다. 같은 본능이 지금 CLAUDE.md 로 부활 한다.

5.4 왜 돌아온 개발자가 이 워크플로우에 유리 한가

후배 개발자는 AI 가 실수하는지 모른다. mock 으로 테스트 짜는 게 왜 문제인지 모를 수도 있다. 그래서 반영할 기회를 놓친다.

돌아온 개발자는 다르다. 1990s 부터 쌓아온 경험 자본 — 잘못된 가정의 비용 을 몸으로 안다. AI 의 실수가 어느 줄의 결과인지 즉각 감지한다. 그래서 즉시 CLAUDE.md 1 줄로 기록할 수 있다. 반영의 속도가 몇 배 빠르다*.

이는 본 책 [synthesis_horim_returning-dev-claudemd-as-second-brain] 카드의 직접 인용. CLAUDE.md = 경험 자본의 디지털 백업. 돌아온 개발자에게 두 번째 두뇌 다.

5.5 빌드·테스트·린트 명령어 명시 — 결과 품질 2~3 배

Boris Cherny 가 또 정립한 공식 통계:

"Probably the most important thing to get great results out of Claude Code — give Claude a way to verify its work. If Claude has that feedback loop, it will 2-3x the quality of the final result."

("Claude Code 에서 좋은 결과 얻는 가장 중요한 한 가지 — 자기 작업을 검증할 방법 을 제공. 그 피드백 루프가 있으면 결과 품질이 2~3 배*.")

검증의 핵심은 명령어 명시 다. CLAUDE.md 에 3 줄만 기록하면 된다:

## 빌드·테스트·린트

- 빌드: `npm run build`
- 테스트: `npm test` (Vitest)
- 린트: `npm run lint` (ESLint + Prettier)

이 3 줄이 없으면 — Claude 는 package.json 을 뒤져 명령을 추측 한다. 잘못된 명령을 몇 번 시도 한 후에야 정답에 도달한다. 그 사이 수십~수백 토큰 이 낭비 된다.

이 3 줄을 기록하는 시간 — 1 분. 절감되는 시간·토큰 — 매 세션마다 수십~수백. 복리 다.

5.6 처방 — 30 일 워크플로우 시작

처방 5 (Day 1~30): 다음 30 일 워크플로우를 오늘 시작 하라.

30 일 후 — 당신의 프로젝트 CLAUDE.md 는 살아 있는 헌법 이 된다. 마치며에서 다시 만난다. 다음 챕터는 100 줄을 넘기 시작했을 때의 분할 전략.

---

Chapter 6 — 100 줄 넘으면 분할 — 4 층 인프라

6.1 100 줄의 한계 — 분할의 시점

Anthropic 공식 권장 — 200 줄 이하. YouTube 강의 권장 — 100 줄 이하. 두 권장을 종합하면 — 80~100 줄에서 분할 시작 이 안전하다.

분할의 3 가지 도구:

1. @path 가져오기 — 단순 참조 (토큰 절약 ❌, 조직화만)
2. .claude/rules/<path>.md 경로별 규칙 — 진짜 토큰 절약
3. AGENTS.md 통합 — 도구 중립적 표준과 공존

6.2 @path 가져오기 — 조직화 도구

CLAUDE.md 안에 @README.md 같이 기록하면 — 그 파일이 시작 시 컨텍스트에 합쳐진다.

# 프로젝트 개요는 @README.md 참조
# npm 명령은 @package.json 참조

## 추가 지침
- Git 워크플로우: @docs/git-instructions.md
- 개인 재정의: @~/.claude/my-project-instructions.md

규칙:

• 상대 경로·절대 경로 모두 허용 (상대 = 가져오기 포함 파일 기준)
• 최대 5 홉 재귀 가능
• 외부 가져오기는 첫 만남 시 승인 대화 표시
• ★ 토큰 절약 ❌ — 모두 시작 시 로드

언제 쓰는가? 조직화·재사용성 만 목적. 토큰 절약 목적 ❌.

6.3 .claude/rules/ 경로별 규칙 — 토큰 절약의 핵심

토큰을 진짜로 절약하려면 — .claude/rules/ 디렉토리에 경로별 규칙 을 기록한다.

---
paths:
  - "src/api/**/*.ts"
---

# API 개발 규칙

- 모든 API 엔드포인트는 *입력 검증* 포함
- 표준 *오류 응답 형식* 사용
- *OpenAPI 문서 주석* 포함

핵심:

• paths 필드의 glob 패턴과 일치하는 파일 을 Claude 가 작업할 때만 로드
• 모든 도구 사용 시가 아니라 — 해당 파일을 읽을 때 만
• 매 세션마다 항상 컨텍스트에 포함되지 않는다 → 토큰 절약 핵심

paths 가 없는 .claude/rules/*.md 는 — .claude/CLAUDE.md 와 동일 우선순위로 시작 시 로드*. 즉 경로 범위 지정 안 하면 토큰 절약 효과도 없다. 반드시 paths 기록하라.

6.4 AGENTS.md 통합 — 도구 중립적 헌법

Claude Code 는 CLAUDE.md 를 읽는다. OpenAI Codex 는 AGENTS.md 를 읽는다. Cursor 는 .cursorrules 를 읽는다. 도구마다 다른 파일 을 읽는 시대다.

여기서 AGENTS.md 가 등장했다. Linux Foundation 의 Agentic AI Foundation 이 주관하는 공식 오픈 표준. 2026 년 기준 60,000+ open-source projects 가 채택. 22+ 도구 (Codex·Cursor·Aider·Gemini CLI·Devin·GitHub Copilot 등) 가 기본으로 읽음.

예외: Claude Code 는 AGENTS.md 를 직접 읽지 않는다. 해법은 — CLAUDE.md 에 가져오기 한 줄.

# CLAUDE.md
@AGENTS.md

## Claude Code 특화 지침
- `src/billing/` 아래 변경은 *Plan Mode* 사용

이 한 줄로 — 모든 도구가 동일한 헌법을 읽는 환경 이 완성된다. AGENTS.md = 국제법·조약, CLAUDE.md = 국내법 + Claude 특화 시행규칙. 헌법 메타포의 외연 확장.

6.5 4 층 인프라 — Skills · Hooks · Subagents · Plugins

CLAUDE.md 의 진짜 한계는 — 권고 (advisory) 라는 점이다. Claude 가 읽고 따르려고 하지만 — 엄격한 준수를 보장하지 않는다. 그래서 법체계의 다른 층 이 필요하다.

층 1 — Skills (필요 시에만 로드되는 도메인 지식)

.claude/skills/<name>/SKILL.md. CLAUDE.md 가 항상 로드 되는 헌법 이라면, Skills 는 필요 시에만 로드 되는 행정규칙·고시.

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

description 이 매칭되면 — Claude 가 자동 호출. /api-conventions 로 수동 호출 도 가능.

층 2 — Hooks (결정론적 자동화)

.claude/settings.json 의 hooks 객체. CLAUDE.md 의 권고 를 결정론적 강제 로 격상.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/protect-files.sh"
          }
        ]
      }
    ]
  }
}

이 hook 은 모든 파일 편집 전에 보호 스크립트를 실행. 보호 패턴에 매치되면 — Claude 가 무엇을 결정하든 무조건 차단. CLAUDE.md 에 ".env 건드리지 마세요" 라 정립한 것은 권고 지만 — hook 으로 정립한 것은 물리적 가드. bypassPermissions 모드에서도 차단 가능.

층 3 — Subagents (격리 컨텍스트)

.claude/agents/<name>.md. 주 대화의 CLAUDE.md 토큰을 보존 하면서 격리된 작업 처리.

---
name: security-reviewer
description: 보안 취약점 검토
tools: Read, Grep, Glob, Bash
model: opus
memory: project
---

You are a senior security engineer. Review code for:
- 주입 취약점 (SQL, XSS, 명령 주입)
- 인증·권한 결함
- 비밀·자격 증명 노출

memory: project 가 핵심. Subagent 도 자체 CLAUDE.md 등가물 (MEMORY.md) 을 가질 수 있다. 시간이 지나면서 전문 지식 자본 축적.

층 4 — Plugins (배포 단위)

.claude-plugin/plugin.json. Skills·Subagents·Hooks·MCP 를 하나로 묶어 — 팀 전체 배포·버전 관리·마켓플레이스 공유 가능.

{
  "name": "my-team-plugin",
  "description": "팀 공통 헌법 + 도구",
  "version": "1.0.0",
  "author": { "name": "..." }
}

이 4 층이 모이면 — 바이브 코딩 시대의 완전한 법체계* 가 된다. Chapter 8 의 Anthropic 공식 플러그인 이 이 4 층 구조를 직접 예시 한다.

6.6 돌아온 개발자의 4 층 인지 우위

후배 개발자에게는 4 층 인프라가 너무 많은 새로운 개념 이다. 돌아온 개발자에게는 — 이미 다 본 것들 이다.

돌아온 개발자는 이 5 개를 물리적으로 다 안다. 디지털로 옮기는 작업 만 남았을 뿐이다. 학습 곡선이 매우 짧다.

6.7 처방 — 100 줄 넘어가는 CLAUDE.md 의 분할 작전

처방 6 (Day 7~14): 다음 5 단계 분할 작전 으로 100 줄 넘는 CLAUDE.md 를 반으로 줄여라.

1. 코딩 스타일 부분을 별도 coding-style.md 로 분리
2. API 규칙 은 .claude/rules/api-rules.md 로 경로 범위 지정 (paths: ["src/api/**/*.ts"])
3. AGENTS.md 가 있다면 @AGENTS.md 한 줄로 통합
4. 자동 차단이 필요한 규칙 (예: .env 보호) → Hook 으로 이전
5. 도메인 전문 지식 (예: 보안 검토) → Subagent 로 이전

5 단계 후 — 메인 CLAUDE.md 는 원래의 30~50% 로 줄어든다. 그러면서도 전체 시스템의 통제력은 오히려 강해진다*. 이것이 4 층 인프라의 위력 이다.

이로써 우리는 Part 2 를 마쳤다. 헌법을 잘 쓰는 법 의 작성·운용·분할이 모두 정립되었다. 다음 Part 3 에서는 — 2 가지 꿀팁 (Karpathy 65 줄 + Anthropic 공식 플러그인) 과 돌아온 개발자의 30 일 처방 으로 마무리한다.

---

Part 3 — 헌법을 자동으로 진화시키기 (응용·실무)

Chapter 7 — 꿀팁 1 — Karpathy 4 원칙

7.1 65 줄 + 109K Stars — 사회적 사건

2026 년 1 월 27 일 GitHub 에 한 저장소가 등장했다 — forrestchang/andrej-karpathy-skills. 단 하나의 파일 — CLAUDE.md, 65 줄 짜리. 작성자 Forrest Chang (Jiayuan Zhang). MIT 라이선스.

첫 주 수만 별. 2026 년 4 월 13 일 하루에만 5,828 별 추가. 4 월 기준 누적 109,000+ stars. GitHub 역사상 가장 별 많은 단일 파일 저장소 중 하나 가 되었다.

이는 기술 현상 이 아니라 사회 현상 이었다. 수백만 개발자가 동시에 같은 좌절 을 겪고 있었기 때문이다. 그리고 — 65 줄짜리 단순 텍스트 가 그 좌절을 30 초 만에 해결 했기 때문이다.

7.2 영문 직접 인용 — Karpathy 3 + 1 명제

65 줄 CLAUDE.md 의 지적 토대 는 카파시가 viral thread 에서 정립한 3 + 1 명제 다.

실수 모드 ① 대응 — Think Before Coding

표어:

"Don't assume. Don't hide confusion. Surface tradeoffs."

규칙:

• 가정을 명시적으로 진술한다
• 불확실하면 질문 한다
• 여러 해석이 있으면 모두 제시 한다
• 더 단순한 방식이 있으면 언급·이견 제기
• 불명확한 부분은 멈추고 혼란을 명확히 지적

금지:

• ❌ 가정에 숨어 진행
• ❌ 혼란을 감추고 진행

실수 모드 ② 대응 — Simplicity First

표어:

"Minimum code that solves the problem. Nothing speculative."

규칙:

• 요청된 기능만 구현
• 단일 용도 코드에 추상화 ❌
• 미요청 유연성·설정 가능성 ❌
• 불가능한 시나리오의 오류 처리 ❌

금지:

• ❌ 200 줄이 50 줄로 가능하면 다시 쓸 것

예시 — 할인 계산기:

# ❌ 전략 패턴 + 여러 클래스 (50+ 줄)
class DiscountStrategy(ABC): ...
class PercentageDiscount(DiscountStrategy): ...
class FixedDiscount(DiscountStrategy): ...

# ✅ 함수 하나 (1 줄)
def calculate_discount(amount, percent):
    return amount * (percent / 100)

실수 모드 ③ 대응 — Surgical Changes

표어:

"Touch only what you must. Clean up only your own mess."

규칙:

• 인접 코드·주석·포맷 개선 ❌
• 작동하는 코드 리팩토링 ❌
• 기존 스타일 유지
• 발견한 미사용 코드는 언급만 — 삭제 ❌

판단 기준: 변경된 모든 줄 = 사용자 요청과 직접 연결.

고아 발생 시:

• YOUR 변경 으로 미사용된 imports·변수·함수만 제거
• 기존 데드 코드 는 유지

명제 ④ — Goal-Driven Execution

Karpathy 원문:

"LLMs are exceptionally good at looping until they meet specific goals. Don't tell them what to do, give them success criteria and let them work."

("LLM 은 특정 목표를 충족할 때까지 루핑 하는 데 예외적으로 뛰어나다. 무엇을 하라고 말하지 말고, 성공 기준을 주고 작동하게 하라.")

표어:

"Define success criteria. Loop until verified."

작업 변환 표:

금지:

• ❌ 약한 성공 기준 ("작동하게 만들기")
• ❌ 검증 없는 구현

7.3 작동 신호 — 3 가지 변화

Forrest Chang 의 README 가 정립한 4 원칙이 잘 작동하는지 의 3 가지 신호:

1. diff 의 불필요한 변경 ↓ — 작은 PR 이 진짜 작다
2. 과한 복잡화로 인한 재작성 ↓ — 한 번에 적정 복잡도 로 기록
3. 실수 후 가 아니라 시작 전 명확화 질문 ↑ — Think Before Coding 작동

이 3 가지 신호가 모두 보이면 — 4 원칙이 내 프로젝트에 자리잡았다. 1~2 주 운용 후 측정한다.

7.4 트레이드오프 — Karpathy 의 자기 명시

카파시는 4 원칙이 모든 상황에 옳지는 않다 고 명시했다.

"These guidelines bias toward caution over speed. For trivial tasks, use judgment."

("이 지침은 속도보다 신중함에 무게 를 둡니다. 사소한 작업은 판단에 맡기세요.")

• ✅ 대규모·복잡 작업 → 4 원칙 강하게 작동 (느리지만 안전)
• ❌ 사소한 작업 (오타 수정·변수 이름 변경) → Claude 판단에 위임 (질문 없이 진행 가능)

이 균형감 이 65 줄을 109K 별 짜리 로 만든 이유 중 하나다. 맹목적 엄격성 이 아니라 실용적 분별.

7.5 돌아온 개발자의 시선 — 4 원칙 = 1990s 시니어가 후배에게 한 4 마디

4 원칙을 본 돌아온 실버 개발자 에게는 — 너무 익숙한 4 마디 가 떠오른다.

이 4 마디는 — 모든 시니어 개발자가 후배에게 한 멘토 노트의 압축*. 카파시는 그 압축을 전 세계 65 줄로 정립했다. 109K 명이 동의했다.

돌아온 개발자는 이 4 마디를 체화 한 상태. 후배에게 말로 했던 것을 — 마크다운으로 옮기는 작업만 남았을 뿐이다.

7.6 처방 — 65 줄을 전역 CLAUDE.md 에 즉시 기록하기

YouTube 강의의 가장 명료한 권장:

"저 같은 경우에는 전역 CLAUDE.md (~/.claude/CLAUDE.md) 에 넣는 걸 추천드립니다. 이거는 사실 특정 프로젝트 규칙이 아니거든요. 이거는 범용적인 워크플로우 같은 거예요."

이유:

• 4 원칙 = 프로젝트 무관 보편 규칙
• 모든 프로젝트에 일관 적용*
• 한국어 번역해도 동일 작동 (LLM 의 언어 중립성)

처방 7 (Day 7): 다음 명령으로 65 줄을 전역 CLAUDE.md 에 즉시 기록한다.

# macOS / Linux
mkdir -p ~/.claude
curl -o ~/.claude/CLAUDE.md \
  https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

# Windows PowerShell
New-Item -ItemType Directory -Force -Path ~/.claude
Invoke-WebRequest -OutFile ~/.claude/CLAUDE.md `
  https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

30 초 안에 끝난다. 다음 세션부터 — 모든 프로젝트에서 4 원칙이 작동 한다. 109K 명의 검증된 헌법 이 내 컴퓨터에 기록된다.

---

Chapter 8 — 꿀팁 2 — Anthropic 공식 플러그인

8.1 claude-md-management — 자가 진화의 도구

Anthropic 이 공식적으로 배포한 플러그인이 있다 — claude-md-management. 작성자: Isabella He (isabella@anthropic.com). 저장소: anthropics/claude-plugins-official/plugins/claude-md-management.

이 플러그인은 2 가지 도구 를 묶었다.

두 도구를 함께 쓰면 — Boris Cherny 의 Compounding Engineering 명제가 자동화 된다. 즉 우리가 직접 CLAUDE.md 를 개선할 필요가 없어진다.

8.2 claude-md-improver — 5 단계 워크플로우

claude-md-improver 스킬을 호출하면 — 다음 5 단계 가 자동 실행 된다.

Phase 1 — Discovery (발견)

저장소 내 모든 CLAUDE.md 파일 탐색:

• 루트 ./CLAUDE.md
• 개인 ./.claude.local.md
• 사용자 전역 ~/.claude/CLAUDE.md
• 모노레포의 패키지별 파일
• 중첩 하위 디렉토리 파일

bash 로 최대 50 개 수집. 모노레포 구조 자동 지원.

Phase 2 — Quality Assessment (품질 평가)

각 파일을 6 가지 기준 으로 가중 평가:

1. 빌드·테스트·배포 명령어 문서화
2. 아키텍처 명확성
3. 숨겨진 패턴 기록
4. 간결성 (200 줄 이하)
5. 현행성 (코드 ↔ CLAUDE.md 동기화)
6. 실행 가능성 (복사·붙여넣기 즉시 작동)

등급:

Phase 3 — Quality Report Output (품질 보고)

점수 매기기 전에 반드시 보고서 출력:

• 파일 개수 + 평균 점수 + 업데이트 필요 파일 수 요약
• 각 파일별 기준별 점수 + 문제점 + 권장 추가 사항 표

★ 사용자 명시적 승인 없이 변경 ❌.

Phase 4 — Targeted Updates (목표화된 수정)

실제 코드 분석에서 발견한 실질적 정보만 추가:

추가할 것:

• 명령어, 비명백 패턴, 패키지 관계, 테스트 접근, 설정 특이사항

제외할 것:

• 명백한 내용 반복, 일반론·추상론, 일회성 수정, 장황 설명

각 변경을 diff 형식 으로 표시 + 이유 설명.

Phase 5 — Apply Updates (적용)

사용자 승인 후 Edit 도구로 실제 적용. 기존 콘텐츠 구조 유지 + 타겟된 추가만.

8.3 4 파일 시연 — 평균 80 점 (B)

YouTube 강의에서 실제 시연 한 결과 (사이드 프로젝트 4 개 CLAUDE.md):

P0 우선순위 출력: "루트 CLAUDE.md 우선 개선".

이는 전형적 패턴 이다. 모노레포에서 루트 CLAUDE.md 가 가장 부풀려진다. 왜냐하면 — 모든 디렉토리에 공통 적용 되어야 하는 유혹 때문이다. 더 세분화된 (서브디렉토리·.claude/rules/) 파일이 오히려 점수가 높다.

8.4 /revise-claude-md — 6 단계 자동화

/revise-claude-md 명령은 — 세션 종료 시 호출하면 다음 6 단계 가 자동:

1. Reflect — 누락 컨텍스트 식별 (bash 명령·패턴·테스트·환경 특이·함정)
2. Locate — 기존 CLAUDE.md·.claude.local.md 찾기
3. Categorize — 팀 공유 (CLAUDE.md) vs 개인 (.claude.local.md)
4. Draft — 간결한 한 줄 추가
5. Preview — 제안 변경 + 이유 표시
6. Apply — 승인 후 편집

이는 — *Boris Cherny 의 수동 워크플로우의 완전 자동화. 세션 안에서 한 실수가 → 세션 종료 시 자동으로 CLAUDE.md 1 줄 로 기록된다. Compounding Engineering 의 실시간 구현.

8.5 자가 진화 루프 — 두 도구의 상호 보완

세션 시작 → CLAUDE.md 자동 로드
       ↓
   세션 진행 — Claude 가 실수·학습·패턴 발견
       ↓
세션 종료 → /revise-claude-md (학습 캡처, 한 줄 추가)
       ↓
   매월 1 회 → claude-md-improver (전체 감사·리팩토링)
       ↓
   ← 세션 시작 (자가 진화 루프 반복)

이 루프가 돌아가기 시작하면 — CLAUDE.md 는 우리 손을 떠나 스스로 자라난다. 복리 (compounding) 가 기계적으로 적용된다. 1 개월 → 80 점 (B), 3 개월 → 90 점 (A−), 6 개월 → 95 점 (A) 의 측정 가능한 진화.

8.6 돌아온 개발자의 시선 — 멘토 자리의 디지털화

후배 개발자에게는 — 자가 진화 가 마법 같다. AI 가 스스로 자기 가드레일을 개선 한다고? 어떻게?

돌아온 개발자에게는 — 익숙한 풍경 이다. 1990s 사내 위키, 2000s Confluence, 2010s Notion. *멘토가 정립한 체크리스트가 시간이 지나며 팀 전체 지식 자본 으로 자라나는 과정. 그게 Compounding Engineering 의 오프라인 등가물 이다.

차이점은 — 지금은 멘토 없이도 가능하다. AI 가 자기 자신을 가르친다. 단, 처음에 4 위치 + 4 원칙 + 분할 + 자가 진화 루프 를 설계한 입법자 가 있어야 한다. 그 입법자가 — 돌아온 개발자 다.

8.7 처방 — 플러그인 설치 + 첫 감사 실행

처방 8 (Day 21): 다음 3 분 작전 으로 자가 진화 루프를 오늘 구축 하라.

1. 플러그인 설치 (30 초)

Claude Code 에서 다음 한 줄 요청:

github.com/anthropics/claude-plugins-official/tree/main/plugins/claude-md-management
이 플러그인 설치해줘.

2. 첫 감사 (1 분)

Claude Code 에서:

audit my CLAUDE.md files

5 단계 워크플로우 자동 진행 → 점수 확인.

3. 결과 해석 (1 분)

3 분 안에 — 우리 프로젝트의 헌법 점수 가 측정 가능 해진다. 다음 챕터에서는 — 이 측정을 30 일에 걸쳐 A 등급까지 끌어올리는 처방 을 본다.

---

Chapter 9 — 돌아온 개발자의 30 일 처방

9.1 한 페이지 체크리스트 6 — 자가 점검 도구

YouTube 강의가 정립한 마무리 한 페이지 는 — 6 가지 자가 점검 체크리스트 다. 이 6 항목이 *본 책의 압축 이다.

이 6 항목을 책상 위에 인쇄해 두고 — 매월 1 회 자가 점검 하라. 6 항목 모두 ✅ 이면 — 당신은 바이브 코딩 입법자 다.

9.2 30 일 워크플로우 — Day 1 부터 Day 30 까지

본 책의 처방 1~8 을 시간 순서로 재배치 하면 — 다음 30 일 처방 이 된다.

Week 1 — 헌법 세우기 (Day 1~7)

목표: 프로젝트 CLAUDE.md 첫 생성 + 1 줄 → 10 줄 로 성장.

Week 2 — 헌법 고치기 (Day 8~14)

목표: 분할 + 일관성. 100 줄 ↔ @coding-style.md 분리.

Week 3 — 헌법 자동화 (Day 15~21)

목표: 자가 진화 루프 구축 — /revise-claude-md + Hooks.

Week 4 — 헌법 최적화 (Day 22~30)

목표: 팀 단위 배포 + 플러그인 마이그레이션.

9.3 Software 3.0 4 기둥 — 돌아온 개발자의 1990s 등가물

본 책의 지적 골격 은 Software 3.0 의 4 기둥 으로 정리된다 — 단순화하면 다음 표.

돌아온 개발자에게 — 4 기둥 모두 물리적 등가물 을 체화한 상태*. 학습 시간이 후배보다 훨씬 짧다. 본 책 30 일 처방을 완주하면 — Karpathy 의 80% 에이전트 수준에 6 개월 안 도달 가능하다.

9.4 두 번째 두뇌 — CLAUDE.md 가 경험 자본을 백업한다

마지막으로 — 왜 돌아온 개발자에게 이 책이 결정적으로 유리한가. 한 마디로 답하면 — CLAUDE.md 가 경험 자본의 디지털 백업 이기 때문이다.

돌아온 개발자는 첫 번째 두뇌 의 모든 자산을 물리적으로 안다. CLAUDE.md 학습 = 디지털 등가물 매핑 한 단계 만 남았을 뿐이다. 후배는 두 두뇌를 동시에 키워야 한다. 돌아온 개발자는 첫 번째 두뇌의 자산을 옮기기만 하면 된다.

9.5 토큰 차익거래 — 경험 자본의 경제학적 활용

마지막 한 관점 — 경제학적 시선.

차익거래 (Arbitrage): 가격 차이를 이용한 수익 창출.

돌아온 개발자는 — 동일 토큰으로 더 많은 가치를 생산한다. 이것이 경험 자본 차익거래 다. 그 차익을 CLAUDE.md 에 기록하는 1 줄마다 — 영구적으로 누적 된다 (복리).

게다가 — 부록 A 에서 다루겠지만 — 토큰은 점점 더 희소해질 예정이다. 메모리 반도체 (HBM·D-RAM) 의 물리적 생산 한계 가 3~5 년간 풀리지 않기 때문이다. 희소 자원 관리 에 경험 자본을 가진 사람이 더 큰 차익 을 얻는다. 돌아온 개발자에게 역사상 가장 유리한 시기 가 — 지금 이다.

9.6 처방 — 30 일 후 자가 점검 — Karpathy 80% 수준 도달

처방 9 (Day 30): 다음 4 가지 지표 로 80% 에이전트 수준 도달 을 측정하라.

4 가지 모두 ✅ — 당신은 AI-Native 4 단계 의 Maximalist → Native 도약 을 완성했다 (Karpathy 의 80% 와 동급).

이로써 9 챕터를 모두 마쳤다. 왜 헌법인가 (Part 1), 어떻게 잘 쓰는가 (Part 2), 어떻게 자동 진화시키는가 (Part 3). 이제 마치며 — No Design, No Code 라는 본 책의 최종 명제 가 어떻게 바이브 코딩 시대 개발자의 정체성 을 정의하는지를 본다.

---

마치며 — No Design, No Code, 헌법 입법자의 시대

1. ★★★ 최종 명제 — 설계의 시작은 헌법 설계

본 책의 모든 9 장을 하나로 묶는 한 명제가 있다.

*마무리는 No Design, No Code 이다. 설계 없는 코드 없다. 그런데 — 설계의 시작 은 헌법을 설계 하는 것이고, 헌법을 고쳐 가는 것 이다. 즉 — CLAUDE.md 를 설계하고 최적화해 가는 과정 이 바로 바이브 코딩의 설계 그 자체 이다.

이를 3 단 논증으로 정리하면:

1. (전제)  설계 없이는 코드 없다 = No Design, No Code = AI-Native 강의 표어
   ↓
2. (확장)  설계의 시작 = 헌법을 설계하는 것 + 헌법을 고쳐 가는 것
   ↓
3. (결론)  CLAUDE.md 를 설계하고 최적화해 가는 과정 = 바이브 코딩의 설계 그 자체

이 결론이 본 책의 모든 9 챕터를 하나로 묶는다. 각 챕터는 이 한 명제의 부분 적용 이었다.

• Part 1 (Ch1~3) → 왜 CLAUDE.md 가 설계의 시작 인가
• Part 2 (Ch4~6) → 어떻게 그 설계를 잘 쓰는가
• Part 3 (Ch7~9) → 어떻게 그 설계를 자동으로 고쳐 가는가

2. 3 단 안내문 — 오늘·이번 주·이번 달

본 책의 합격 기준 은 완벽 이해 + 즉시 적용. 그 적용 을 3 단 안내문 으로 정리한다.

1단계 — 오늘 즉시 (헌법을 세운다)

# 프로젝트 루트에 빈 CLAUDE.md 생성
touch CLAUDE.md

# 첫 1 줄 기록하기 — 빌드 명령
echo "## 빌드·테스트·린트
- 빌드: \`npm run build\`
- 테스트: \`npm test\`
- 린트: \`npm run lint\`" > CLAUDE.md

30 초 안에 끝난다. 입헌 시민 의 첫 발걸음.

2단계 — 이번 주 (헌법을 고친다)

매번 Claude 가 실수할 때마다 — 그 자리에서 즉시:

"이 실수 다시 안 하게 CLAUDE.md 에 반영해 줘."

이 한 마디가 — Compounding Engineering 의 시작점. 일주일 후 — CLAUDE.md 가 자라난 모습 을 발견한다.

3단계 — 이번 달 (헌법을 최적화한다)

# Claude Code 에서
audit my CLAUDE.md files

claude-md-improver 5 단계가 자동 진행. 점수 측정 + 리팩토링 + 분할 권장. 30 일 후 — 당신의 CLAUDE.md 는 A 등급 헌법 이 된다.

3 단계 = 설계·개정·최적화 의 입법 사이클. 입법자 = 개발자 자신. 이 사이클이 돌아가기 시작하면 — 당신은 코드 노동자가 아니라 헌법 입법자*.

3. 마치며의 마침 문장

바이브 코딩 시대의 개발자는 코드 노동자 가 아니다 — 헌법 입법자 이다.

코드는 AI 가 쓴다. 우리는 — CLAUDE.md 를 설계하고 고쳐 가는 사람들 이다.

No Design, No Code — 그 설계의 출발점이자 살아 있는 형식 이 — 바로 CLAUDE.md 다.

이것이 본 책의 모든 페이지가 수렴 하는 한 문장 이다.

돌아온 실버 개발자에게 — 환영한다. 1990s 부터 쌓은 경험 자본 이 지금 가장 필요한 시대 다. 후배 개발자에게 — 지금 시작하라. 30 일 워크플로우는 오늘 시작 할 수 있다.

이 책이 — 당신의 바이브 코딩 시대 첫 입법문 이 되기를 바란다.

— 최호림 (AI-Native, 돌아온 실버 개발자) 2026 년 5 월 12 일

---

부록

부록 A — 토큰의 본질과 미래

A.1 토큰이란 무엇인가 — 트랜스포머 어텐션의 기본 단위

LLM 시대의 기본 화폐 가 바로 토큰 이다. 우리가 Claude 에게 보낸 한 문장 도 받은 한 문장 도 — 모두 토큰의 묶음 이다.

토큰은 — 2017 년 트랜스포머 (Transformer) 논문 (Vaswani et al., Attention Is All You Need) 이후 어텐션 메커니즘 (Attention Mechanism) 의 기본 단위 로 자리잡았다. 입력 텍스트를 분해하는 최소 단위 — 보통 subword 또는 word piece 다.

예시:

• "안녕하세요, 반갑습니다." → 약 10~15 토큰 (한국어 byte-pair encoding 기준)
• "Hello, nice to meet you." → 약 7~8 토큰 (영어 BPE 기준)

한 가지 흥미로운 사실: 영어가 한국어보다 훨씬 토큰 효율적 이다. 같은 의미를 표현하는 데 영어가 2 배 적은 토큰 을 사용한다. 이는 훈련 데이터의 영어 편향 때문이다. 돌아온 개발자가 CLAUDE.md 를 영어로 기록하는 것 이 토큰 절약 측면에서 유리 한 이유다.

A.2 어텐션 메커니즘과 토큰의 관계 — O(N²)

어텐션 메커니즘의 수학적 본질 은 — 모든 토큰 쌍 사이의 관련성 (attention score) 계산 이다. N 개 토큰 → 계산량 O(N²).

즉 — context window 의 크기가 계산 비용·메모리 비용을 직접 결정 한다. Claude 3.5 의 200K 토큰 context window 는 — 어텐션 계산만으로 400 억 회 연산 이 필요하다. 이를 수 초 안 에 처리하려면 — *대량의 HBM (High Bandwidth Memory) 가 필요 하다.

A.3 ★ 향후 더 중요해질 이유 — 하드웨어 공급의 물리적 한계

토큰 관리가 지금까지보다 더 중요 해질 이유 4 가지:

1. LLM 모델 크기의 기하급수적 증가

2. Context window 의 확장

3. 메모리 물리적 생산 한계

HBM 과 D-RAM 의 공급 부족 은 2026 년 기준 산업 최대 병목. 이유:

• 반도체 팹 (제조 시설) 신규 건설 = 3~5 년 소요
• EUV 노광 장비 공급 부족
• 재료 (실리콘 웨이퍼·금속) 공급 한계

→ 공급은 수년간 풀리지 않는다. 동시에 수요는 지속 폭증.

4. 수요 ≫ 공급 의 직접 결과

• 토큰당 가격 상승 압력
• API 호출 속도 제한 증가
• 경량 모델로의 전환 압력 (Haiku·GPT-4o-mini 등)
• CLAUDE.md 최적화 = 경제적 가치의 직접 증가

A.4 토큰 = 점점 더 희소한 화폐 (본 위키 VCE 트랙)

본 위키 (wiki_강의_vibe_coding) 의 VCE (Vibe Coding Economy) 트랙 은 — 이 토큰 ↔ 메모리 ↔ 산업 의 인과 사슬을 4 층위 로 분석한다.

→ *CLAUDE.md 잘 쓰기 = 토큰 절감 = 희소 자원의 경제적 활용. 바이브 코딩의 기술 이 바이브 코딩의 경제 와 직접 연결 된다.

A.5 본 책 핵심 메시지와의 연결

토큰이 희소 하기 때문에 — CLAUDE.md 가 헌법으로 필요 하다. 희소 자원의 조직화 가 헌법의 본질 이다. 카파시의 Context = RAM 비유 (Chapter 1) 가 — 물리적 하드웨어 한계로 더욱 정합 된다.

본 책 30 일 처방 (Chapter 9) 을 완주한 독자가 다음에 읽을 자료:

• 30_wiki/3020_VCE_economy/ — VCE 트랙 카드 묶음
• 토큰 → 메모리 → 산업 → 투자 의 4 층위 인과 사슬

A.6 30 일 후 행동 — VCE 트랙 입문

부록 처방: 본 책 30 일 처방 완료 후 — 다음 한 달 은 VCE 트랙 으로 — 토큰 ↔ 메모리 ↔ 반도체 산업 의 경제적 함의 를 공부한다. 기술자 + 경제 시각 을 동시에 갖춘 사람 — 가장 희소한 자산이다.

---

부록 B — 자동 메모리 + /memory 사용법

B.1 자동 메모리란 무엇인가

CLAUDE.md 와 별개로 — Claude Code 는 자동 메모리 (Auto Memory) 시스템을 가진다. 사용자가 작성하지 않아도 Claude 가 자기 자신을 위해 노트를 저장하는 기능. v2.1.59+ 필요.

저장 위치: ~/.claude/projects/<project>/memory/

~/.claude/projects/my-project/memory/
├── MEMORY.md          ← 인덱스 (처음 200줄·25KB 만 자동 로드)
├── debugging.md       ← 주제별 노트 (필요 시 로드)
├── api-conventions.md
└── ...

B.2 CLAUDE.md ↔ 자동 메모리 비교

B.3 /memory 명령 사용법

세션 내에서 /memory 입력 — 다음 기능:

• 현재 세션에 로드된 모든 CLAUDE.md·CLAUDE.local.md·규칙 파일 나열
• 자동 메모리 켜기·끄기 토글
• 자동 메모리 폴더 열기 링크
• 파일 선택 → 편집기에서 열기

B.4 자동 메모리 활성화·비활성화

기본값 — 켜짐. 비활성화:

// settings.json
{
  "autoMemoryEnabled": false
}

또는 환경변수: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

B.5 권장 운용

• 처음 1 주 — 자동 메모리 그대로 둠. Claude 가 무엇을 저장하는지 관찰
• 둘째 주 — /memory 로 저장된 내용 검토. 불필요한 것 삭제
• 셋째 주~ — 자주 저장되는 패턴을 CLAUDE.md 로 승격 — 영구 헌법화

---

부록 C — 문제 해결 FAQ

C.1 Claude 가 CLAUDE.md 를 안 따라요

원인 진단:

1. /memory 실행 — CLAUDE.md 가 로드되었는지 확인
2. 지침이 모호 한가? — Chapter 4 구체성 원칙으로 다시 기록하기
3. 충돌 지침 이 있는가? — 우선순위 표 (Chapter 2 §2.3) 검토
4. 200 줄을 초과 하는가? — Chapter 6 분할 작전 적용

최종 해결: 결정적 규칙은 CLAUDE.md → Hook 으로 이전 (Chapter 6 §6.5).

C.2 자동 메모리에 무엇이 저장되어 있는지 모르겠어요

/memory → 자동 메모리 폴더 선택 → Claude 가 저장한 내용 찾아보기. 모든 것이 읽기·편집·삭제 가능한 일반 마크다운.

C.3 CLAUDE.md 가 너무 큽니다

Chapter 6 4 층 인프라 로 분할:

1. 경로별 규칙 → .claude/rules/<path>.md (paths glob)
2. 도메인 지식 → Skills
3. 결정적 규칙 → Hooks
4. 팀 단위 배포 → Plugins

C.4 /compact 후 지침이 사라진 것 같습니다

• 프로젝트 루트 CLAUDE.md = 압축 완전 생존. /compact 후 Claude 가 디스크에서 다시 읽고 새로 주입
• 하위 디렉토리 중첩 CLAUDE.md = 자동 재주입 ❌. 해당 폴더 파일 다시 읽을 때 lazy load

압축 후 사라진 대화 전용 지침 → CLAUDE.md 에 영구 기록.

C.5 팀원과 CLAUDE.md 충돌이 발생합니다

해결책:

1. 프로젝트 CLAUDE.md (git 체크인) = 팀 공통
2. 개인 선호 = CLAUDE.local.md (gitignored)
3. 주간 1 회 팀 회의에서 프로젝트 CLAUDE.md 변경 사항 공유

---

부록 D — 참고 링크 + 14 SNLS 자료 목록

D.1 본 책의 Ground Truth 14 자료 (모두 본 위키 10_source/2026/05/)

Anthropic 공식 7 자료 (evidence_grade A_meta)

1. 2026-05-12_claude_code_memory_official_docs_snls.md — /docs/ko/memory
2. 2026-05-12_anthropic_best_practices_official_snls.md — /docs/ko/best-practices
3. 2026-05-12_anthropic_skills_official_snls.md — /docs/ko/skills
4. 2026-05-12_anthropic_hooks_official_snls.md — /docs/ko/hooks-guide
5. 2026-05-12_anthropic_subagents_official_snls.md — /docs/ko/sub-agents
6. 2026-05-12_anthropic_plugins_official_snls.md — /docs/ko/plugins
7. 2026-05-12_anthropic_claudemd_management_plugin_snls.md — github.com/anthropics/claude-plugins-official/plugins/claude-md-management

Karpathy 자료 2 (evidence_grade B, 영문 직접 인용 부분은 A)

1. 2026-05-12_karpathy_claudemd_skills_snls.md — github.com/forrestchang/andrej-karpathy-skills
2. 2026-05-12_karpathy_viral_thread_context_engineering_snls.md — viral thread + Context Engineering 종합

보조·합성 2 자료 (evidence_grade B)

1. 2026-05-12_software3_maintenance_sdd_harness_snls.md — Software 3.0 4 기둥 통합
2. 2026-05-12_youtube_lecture_claudemd_real_usage_snls.md — YouTube 실벨 개발자 강의 전사

갭 보강 3 자료 (evidence_grade A_meta)

1. 2026-05-12_karpathy_software3_yc_keynote_snls.md — YC 2025 Software Is Changing (Again)
2. 2026-05-12_agents_md_open_standard_snls.md — Linux Foundation 공식 표준
3. 2026-05-12_boris_cherny_compounding_engineering_snls.md — howborisusesclaudecode.com

D.2 본 위키 외부 참고 URL

• Anthropic Claude Code 공식: https://code.claude.com/docs/
• Karpathy LLM Wiki gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
• Forrest Chang 저장소: https://github.com/forrestchang/andrej-karpathy-skills
• AGENTS.md 공식: https://agents.md/
• Boris Cherny 공개: https://howborisusesclaudecode.com/
• Cognition (Devin): https://cognition.ai/blog/dont-build-multi-agents

D.3 후속 학습

본 책 완독 후 — 다음 자료 권장:

1. VCE 트랙 (30_wiki/3020_VCE_economy/) — 토큰 ↔ 메모리 ↔ 산업 ↔ 투자 4 층위
2. VCG 트랙 (30_wiki/3030_VCG_for_good/) — AI 의 선용 (for Good) 관점
3. VCH 트랙 (30_wiki/3040_VCH_history/) — 1990s~2026 바이브 코딩 역사

— 끝 —

---

본 초안 (v0.1 draft) 완성일: 2026-05-12 다음 단계: Stage 5 — 톤 통일 (vibe-book-publish-edit 적용) → 02_Booklet_Final.md 이후 단계: Stage 6 — PPT 변환 (별도 세션, 사용자 검토 후)