CLAUDE.md — Claude를 위한 온보딩 문서

이전 이야기에서: Agent Loop의 비밀을 이해했다. 30줄의 while 루프. Claude가 도구를 요청하고, 시스템이 실행하고, 결과를 돌려준다. 지민은 감탄했다. 하지만 새 대화를 시작하자마자 문제를 발견했다...

Harness = Tools + Knowledge + Context + Permissions

CLAUDE.md는 Knowledge 레이어의 첫 번째 구현이다. "매번 설명하는 건 지쳤다"

탄생 배경: "매일 출근하는 신입사원"

Agent Loop가 완성됐다. Claude는 이제 파일을 읽고, 코드를 실행하고, 결과를 보고 다음 행동을 결정할 수 있었다.

그런데 결정적인 문제가 있었다.

Claude는 매 세션마다 빈 slate에서 시작했다.

# Claude가 아는 것 (대화 시작 시)
- 일반적인 프로그래밍 지식 ✅
- 자신이 Claude라는 것 ✅
- 이 프로젝트가 뭔지 ❌
- 여기서 어떤 코딩 규칙을 쓰는지 ❌
- 어떤 스택인지 ❌
- 주의해야 할 것이 뭔지 ❌

Harness 관점에서 보면 이건 Knowledge 레이어가 없는 Harness다.

Claude Code (초기) = agent loop + tools
                   ← Knowledge 없음!

개발자들은 매번 직접 Knowledge를 주입해야 했다:

나: 우리 프로젝트는 Next.js 14, TypeScript, Tailwind야.
    테스트는 Vitest로 하고, pnpm이야.
    컴포넌트는 feature 폴더 아래 두는 구조야.
Claude: 알겠습니다!
(다음 날)
나: 버튼 컴포넌트 만들어줘
Claude: 어떤 스택을 쓰시나요?
나: ...

해결책: 자동 Knowledge 주입

Anthropic이 선택한 해결책은 우아하게 단순했다.

"대화 시작 시 프로젝트 루트의 파일을 자동으로 읽어서 시스템 프롬프트에 주입한다."

CLAUDE.md의 탄생.

Claude Code 기동 시:
1. 프로젝트 루트에서 CLAUDE.md 탐색
2. 파일 내용을 시스템 컨텍스트에 주입
3. Claude는 대화 시작 전 이미 프로젝트를 "안다"

# My Project

## Tech Stack
- Next.js 14, TypeScript, Tailwind CSS
- Vitest for testing, pnpm as package manager

## Code Style
- Feature-based folder structure
- Functional components only, no default exports

이걸 한 번 써두면, 다시는 설명하지 않아도 된다.

CLAUDE.md가 Harness에서 하는 일

Harness = Tools + Knowledge + Context + Permissions
                    ↑
              CLAUDE.md가 여기를 채운다

CLAUDE.md는 Claude Code Harness의 항상 활성화된 Knowledge다.

모든 대화에서, 모든 에이전트에게, 자동으로 주입된다.

Claude를 새 팀원이라고 생각해보자:

팀원이 매일 출근할 때마다 회사 소개를 다시 해야 하는가? → ❌ 비효율
입사 첫날 회사 온보딩 문서를 주고, 이후엔 안 해도 되는가? → ✅ CLAUDE.md

CLAUDE.md는 Claude를 위한 온보딩 문서다.