티스토리 뷰

글/트렌드 Ranking

CLAUDE.md 작성법 완전 정리 (2026) — Claude Code 성능이 달라지는 이유

octo54 2026. 6. 1. 12:27

CLAUDE.md 작성법 완전 정리 (2026) — Claude Code 성능이 달라지는 이유

한 줄 요약

CLAUDE.md는 Claude Code가 프로젝트를 이해하기 위해 매 세션 읽는 프로젝트 메모리(Project Memory) 파일이다. 잘 작성된 CLAUDE.md는 코드 품질, 작업 속도, 컨텍스트 유지 능력에 큰 영향을 준다. (Medium)

이 글에서 다루는 내용

CLAUDE.md란?
왜 중요한가?
AGENTS.md와 차이
실제 작성 예제
NestJS 프로젝트 예시
Context Engineering 관점
실무 Best Practice
자주 하는 실수

CLAUDE.md란?

Claude Code에서 가장 중요한 파일 중 하나다.

Claude Code는 프로젝트 시작 시:

CLAUDE.md
↓
프로젝트 규칙 로드
↓
작업 수행

순서로 동작한다.

Anthropic 생태계에서는 CLAUDE.md를 프로젝트 메모리(project-level memory)로 활용하는 패턴이 확산되고 있다. (Medium)

왜 CLAUDE.md가 중요한가?

예를 들어:

회원가입 API 만들어줘

라고 요청한다.

CLAUDE.md 없음

Claude:

추측
↓
랜덤 구조
↓
팀 규칙 무시

CLAUDE.md 있음

Claude:

프로젝트 규칙 확인
↓
아키텍처 확인
↓
정해진 방식으로 생성

결국:

Claude가 똑똑해지는 게 아니라
프로젝트가 Claude를 교육하는 것

CLAUDE.md vs AGENTS.md 차이

이거 진짜 많이 헷갈린다.

구분CLAUDE.mdAGENTS.md

목적	Claude 전용 메모리	범용 Agent 규칙
대상	Claude Code	Claude, Cursor, Codex 등
역할	Claude 행동 최적화	저장소 규칙
범위	Claude 특화	Agent 공통

최근 가이드들은:

AGENTS.md
+
CLAUDE.md

조합을 가장 추천한다. (Medium)

2026 추천 구조

repo/

AGENTS.md
CLAUDE.md

context/
skills/
evals/

가장 많이 쓰는 CLAUDE.md 구조

최소 버전

# Project

NestJS Backend

# Rules

- Use PostgreSQL
- Use Prisma
- Service Layer required

Claude Code가 가장 잘 활용하는 섹션

1. Architecture

예:

# Architecture

Controller
Service
Repository

2. Database Rules

# Database

UUID PK
Soft Delete

3. Security

# Security

JWT required
Role validation required

4. Testing

# Testing

Unit test mandatory

5. Personal Preferences

이게 의외로 중요하다.

예:

# Coding Preferences

Prefer small diffs

Ask before major refactors

Avoid unnecessary abstractions

실무 워크플로우 가이드에서도 개인 선호 규칙을 별도 섹션으로 관리하는 패턴이 많이 소개된다. (Medium)

NestJS 프로젝트 실제 예시

CLAUDE.md

# Backend Rules

Use NestJS

# Controllers

Validation only

# Services

Transaction handling

# Repository

DB access only

# Database

PostgreSQL

# Security

JWT required

이후 Claude는:

회원가입 API 생성

요청 시:

Controller
↓
Service
↓
Repository

구조를 유지하려고 한다.

Context Engineering 관점

2026 AI 개발 핵심 키워드:

Context Engineering

예전:

Prompt Engineering

지금:

Context Engineering

AI 성능은:

모델
+
컨텍스트

조합에서 결정된다.

실제 개발자 워크플로우도 프롬프트보다 Context 설계를 더 중요하게 보는 방향으로 이동 중이다. (Medium)

좋은 CLAUDE.md 예시

좋은 예

# API Rules

REST only

DTO validation required

No business logic in controllers

특징:

짧음
명확함
규칙 중심

나쁜 CLAUDE.md 예시

우리 회사는...
우리의 비전은...

Claude는:

회사 소개

보다:

개발 규칙

이 필요하다.

최근 연구에서 나온 흥미로운 결과

재밌는 사실 하나.

모든 Context File이 좋은 건 아니다.

최근 연구에서는:

과도한 규칙
너무 긴 파일

이 오히려 성능을 떨어뜨릴 수 있다고 분석했다. (arXiv)

그래서 핵심은:

많이 쓰기
❌

중요한 것만 쓰기
⭕

실무 Best Practice TOP 5

1. 100줄 이하 유지

길수록 좋지 않다.

2. 규칙 중심 작성

Do:
...
Don't:
...

3. Architecture 명시

반드시 넣기.

4. Context 분리

CLAUDE.md
↓
context/*

5. Skill과 연결

CLAUDE.md
↓
skills/

Claude Code Best Practices에서도 Skills + Memory 조합을 강조한다. (Claude Code)

앞으로 뜨는 구조

2026 상위 개발팀은:

CLAUDE.md
↓
AGENTS.md
↓
Skills
↓
Subagents
↓
Eval

구조로 이동 중이다. (atal upadhyay)

FAQ

Q. CLAUDE.md는 자동 생성해도 되나요?

가능하다.

하지만 최근 연구에서는:

자동 생성 파일
과도한 규칙

이 성능을 떨어뜨릴 수 있다고 분석했다. (arXiv)

그래서:

초안 생성
↓
사람 수정

Q. CLAUDE.md와 README 둘 다 필요한가요?

필요하다.

파일목적

README	사람
CLAUDE.md	Claude

Q. CLAUDE.md는 어디에 두나요?

보통:

repo root

최상위.

핵심 요약

CLAUDE.md는 Claude Code 프로젝트 메모리
프로젝트 규칙을 지속적으로 제공
Architecture, Security, Testing 규칙이 핵심
짧고 명확하게 작성
Context Engineering의 중심 파일
AGENTS.md와 함께 사용하는 것이 가장 강력

출처

CLAUDEmd, ClaudeCode, AGENTSmd, ContextEngineering, AI개발, AgenticAI, LLM개발, AI코딩, ClaudeSkill, 2026AI

'글 > 트렌드 Ranking' 카테고리의 다른 글

Context Engineering이란 무엇인가? Claude Code 성능을 10배 높이는 핵심 개념 (2026) (0)	2026.06.03
Memory.md란 무엇인가? Claude Code Auto Memory 시스템 완전 정리 (2026) (0)	2026.06.02
AGENTS.md란 무엇인가? Claude Code 프로젝트 운영 규칙 설계 완전 정리 (2026) (0)	2026.05.29
Claude Code Skill이란? SKILL.md부터 AGENTS.md까지 실전 구조 완전 정리 (2026) (0)	2026.05.27
🚀 실전 — Claude Skill 만들기 랭킹 TOP 5 (0)	2026.05.26

※ 이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.

공지사항

최근에 올라온 글

최근에 달린 댓글

Total

Today

Yesterday

링크

TAG more

« 2026/06 »
일	월	화	수	목	금	토
	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30

글 보관함

티스토리 뷰