blog.ruahverce Vol · 2026 · Issue 001 — A field log of LLMs, RAG, and ML systems

Field Log · Entry

CLAUDE.md 작성 가이드 — 에이전트 지식 구조화의 3계층 원칙과 Agent Legibility (3/8)

하네스 엔지니어링 시리즈 3편 오픈 그래프 카드

CLAUDE.md를 처음 만들 때 흔히 빠지는 함정이 있습니다. README를 그대로 복사하거나, “프로젝트의 모든 규칙”을 한 파일에 욱여넣는 것입니다. OpenAI도 거대한 AGENTS.md에 전부 넣었다가 실패했다고 공개했습니다.

결론부터 말하면, CLAUDE.md(AGENTS.md)는 모든 규칙을 담는 백과사전이 아니라 50줄짜리 맵이어야 하고, 실제 지식은 docs/와 코드로 내려보내는 3계층 구조가 정답이었습니다.

이 글이 답하는 질문

  • CLAUDE.md에 뭘 적어야 하고, 뭘 적지 말아야 하나?
  • AGENTS.md와 CLAUDE.md는 뭐가 다른가?
  • Agent Legibility란 무엇이고, 코드 구조를 어떻게 바꿔야 하나?

왜 문서가 중요한가

AI는 컨텍스트 윈도우 안에 있는 정보만 알 수 있습니다. 거기에 없으면 학습 데이터에서 “대충 이럴 것 같다”고 추측합니다. 프로젝트마다 컨벤션, 아키텍처, 금지사항이 다른데, 이걸 매번 프롬프트로 설명할 수 없습니다.

OpenAI는 처음에 하나의 거대한 AGENTS.md에 모든 규칙을 넣었는데 실패했다고 밝혔습니다(OpenAI — Practices for Governing Agentic AI Systems). 문서가 너무 길면 에이전트가 중요한 부분을 놓치고, 오래된 정보와 새 정보가 섞이면서 판단이 흔들렸기 때문입니다.

교훈은 명확합니다: AGENTS.md는 백과사전이 아니라 맵(table of contents)이어야 하고, 실제 지식은 구조화된 문서에 둬야 합니다.

CLAUDE.md 3계층 구조

에이전트 지식 3계층 구조도: 1계층 CLAUDE.md(맵) → 2계층 docs/(상세 기준) → 3계층 코드(최종 진실)

CLAUDE.md (또는 AGENTS.md)     ← 1계층: 맵. "어디에 뭐가 있는지"
  ↓ 가리킴
docs/                           ← 2계층: 상세 기준. 실제 규칙과 설명
  architecture.md
  conventions.md
  api-spec.md
  ↓ 참조됨
코드베이스 자체                  ← 3계층: 최종 진실. 실제 구현
  • 1계층 CLAUDE.md는 50줄 이내의 짧은 맵. 빌드 명령, 디렉터리 구조, 핵심 규칙 5개.
  • **2계층 docs/**는 에이전트가 필요할 때 참조하는 상세 문서.
  • 3계층 코드는 최종 진실. 문서와 코드가 충돌하면 코드가 맞음.

좋은 CLAUDE.md vs 나쁜 CLAUDE.md

나쁜 예 (1주차 - README를 그대로 옮긴 흔한 패턴):

# Dashboard SaaS
This is a Next.js project for a customer dashboard.
Please write good code.
Follow best practices.
Don't make bugs.

에이전트가 쓸 수 있는 구체적 정보가 없습니다. “좋은 코드”가 뭔지 기준도 없습니다.

좋은 예 (3주차 - 같은 프로젝트, 디렉터리·규칙·금지 명시):

# Dashboard SaaS (Next.js 14)

## 명령어
- 빌드: pnpm build
- 테스트: pnpm test
- 단일 테스트: pnpm test -- -t "이름"
- 린트: pnpm lint

## 구조
- src/app/ → 페이지 라우트
- src/lib/api/ → API 래퍼 (직접 fetch 금지)
- src/components/ → 공용 컴포넌트

## 규칙
- 상태관리: Zustand만 사용
- API 호출: lib/api/ 래퍼만 사용
- 컴포넌트: 함수형만, class 금지

## 상세 문서
- 아키텍처: docs/architecture.md
- API 스펙: docs/api-spec.md

## 금지
- .env 커밋 금지
- console.log 남기고 커밋 금지

차이가 보이시죠? 빌드 명령이 복사-붙여넣기 가능하고, 디렉터리 역할이 명확하고, 규칙이 판단 가능한 형태입니다.

Agent Legibility — 코드 자체를 읽기 쉽게

지식 구조화는 문서만의 문제가 아닙니다. 코드 자체가 에이전트에게 읽기 쉬워야 합니다. OpenAI는 이를 “agent legibility”라고 부릅니다(OpenAI — Practices for Governing Agentic AI Systems).

# 나쁜 구조 — 에이전트가 헷갈림
src/utils.ts, helpers.ts, misc.ts, common.ts

# 좋은 구조 — 에이전트가 바로 찾음
src/utils/date-format.ts, response-wrapper.ts, validation.ts

파일 이름만으로 역할을 알 수 있고((4/8) 도구 설계에서 SKILL.md 네이밍 원칙과 맞물립니다), 패턴이 모든 파일에서 일관되면, 에이전트가 하나만 보고 나머지도 같은 방식으로 작업할 수 있습니다.

CLAUDE.md vs AGENTS.md — 도구별 비교

Claude CodeOpenCodeOpenClaw
맵 파일CLAUDE.mdAGENTS.mdAGENTS.md
특수 파일——SOUL.md (성격), USER.md (사용자)
자동 생성/init/init수동
스코프프로젝트/사용자/조직프로젝트에이전트별 workspace

OpenClaw가 특이한 건 역할별 파일 분리입니다 ((7/8) 역할 분리 편에서 subagent 정의 파일과 같은 패턴을 다룹니다). “어떻게 일하나”(AGENTS.md)와 “어떤 톤으로 말하나”(SOUL.md)를 나눠서, 같은 규칙으로 다른 성격의 에이전트를 만들 수 있습니다.

흔한 실수 3가지

  1. CLAUDE.md에 모든 걸 넣는다 → 50줄 이내로 줄이고 나머지는 docs/로 분리
  2. 문서 대신 매번 프롬프트로 설명한다 → 두 번 이상 말한 규칙은 문서에 기록
  3. “왜”를 안 적는다 → docs/decisions/에 ADR을 남겨야 에이전트가 결정을 존중

점진적으로 발전시키기

  • 1주차: CLAUDE.md만 쓴다. 명령어 + 구조 + 핵심 규칙 5개.
  • 2주차: 반복해서 말하는 규칙을 docs/conventions.md로 분리한다.
  • 3주차: docs/architecture.md를 쓴다. 시스템 전체 구조를 문서화한다.
  • 4주차+: 중요한 기술 결정마다 docs/decisions/에 ADR을 남긴다.

4주차 이후 CLAUDE.md가 100줄을 넘기 시작하면, (8/8) 검증과 반복 편의 ‘실패 로그 기반 보강’ 루프로 오래된 규칙을 정리할 시점입니다.

내가 실제로 부딪힌 문제와 해결 (1인칭 경험)

처음 문서를 정리할 때는 README에 있는 설명과 운영 규칙을 한 파일에 몰아넣으려 했습니다. 그런데 파일이 길어질수록 에이전트가 핵심 규칙보다 주변 설명을 더 자주 집어 들었고, 어떤 세션에서는 오래된 설명을 기준으로 판단하기도 했습니다. 문제는 문서가 많아서가 아니라, 맵과 상세 문서가 분리되지 않아 판단 경로가 흐려진 것이었습니다.

그래서 지금은 짧은 진입 문서, 세부 스킬 문서, 실제 코드/콘텐츠 스키마를 분리해서 두고 있습니다. 이렇게 나누고 나니 에이전트가 어디서 결정을 내려야 하는지가 훨씬 명확해졌습니다. 제 기준에서 CLAUDE.md는 지식을 많이 담는 문서가 아니라, 올바른 위치로 빠르게 보내는 문서일 때 가장 잘 작동했습니다.

자주 묻는 질문 (FAQ)

Q1. CLAUDE.md는 최대 몇 줄이어야 하나요? 50줄 이내를 권장합니다. 에이전트는 매 세션 시작 시 이 파일을 읽으므로, 길어지면 핵심을 놓칩니다. 상세한 규칙은 docs/ 폴더에 분리하세요.

Q2. AGENTS.md와 CLAUDE.md는 같은 건가요? 역할은 같습니다. Claude Code는 CLAUDE.md, OpenCode와 OpenClaw는 AGENTS.md를 사용합니다. 형식과 위치만 다르고, “에이전트에게 프로젝트 맵을 주는 문서”라는 목적은 동일합니다.

Q3. 이미 README.md가 있는데 CLAUDE.md가 따로 필요한가요? 네. README.md는 사람(주로 신규 개발자)을 위한 문서이고, CLAUDE.md는 에이전트를 위한 작업 지시서입니다. 에이전트에게는 빌드 명령, 디렉터리 역할, 금지 패턴처럼 “판단에 바로 쓸 수 있는 정보”가 필요합니다.

Q4. Agent Legibility는 구체적으로 뭘 바꾸라는 건가요? 파일 이름만으로 역할을 알 수 있게 하고, 같은 패턴을 일관되게 유지하라는 뜻입니다. utils.ts 대신 date-format.ts, helpers/ 대신 validators/처럼 구체적인 이름을 쓰세요.

Q5. docs/ 폴더가 너무 커지면 어떻게 관리하나요? docs/ 내부에도 2계층 구조를 적용합니다. docs/architecture.md 같은 최상위 문서가 하위 docs/architecture/auth.md 등을 가리키는 식입니다. CLAUDE.md(1계층)는 항상 최상위 문서만 참조하고, 하위 분기는 상위 문서가 책임집니다.

마무리

  • CLAUDE.md는 50줄짜리 맵이어야 하고, 상세 지식은 docs/와 코드로 내려보냅니다.
  • Agent Legibility(코드 가독성)도 문서와 같은 수준의 투자 대상입니다.
  • 1주차부터 4주차까지의 점진 발전 플랜을 따라가면 무리 없이 안정화됩니다.

다음에 읽으면 좋은 글

참고자료