CLAUDE.md가 필요하지 않아요

I’m happy to translate the content for you, but I’ll need the text you’d like translated. Could you please paste the article (or the specific portion) you want rendered in Korean? The source line will stay exactly as you provided it.

Source:

CLAUDE.md / AGENTS.md를 효과적으로 관리하는 방법

이 글은 일반적인 프롬프트 엔지니어링 기본(예: “부정적인 예시를 피하세요”, “LLM 역할을 설정하세요”, “구체적으로 작성하세요”)을 다루지 않습니다. 해당 기초가 필요하면 Anthropic 또는 OpenAI 공식 문서를 참고하세요.

대신, Claude Code를 실제 프로젝트에 수개월 동안 사용하면서 다듬은 실용적인 패턴을 공유합니다. 초점은 문서 정리에 맞춰 LLM이 코드베이스가 커져도 효율적으로 작동하도록 하는 것입니다.

나의 작업 철학

• 나는 **“바이브 코더”**가 아닙니다. LLM이 몇 시간·몇 일 동안 자율적으로 돌아가게 두지 않습니다.
• LLM을 키보드처럼 다룹니다: 초인적인 속도로 읽고 입력할 수 있고, 작업을 검증하기 위해 행동을 실행할 수도 있지만 내가 제어합니다.
• 제안이 너무 추상적이거나 불명확하면 즉시 중단합니다.

왜 작은 CLAUDE.md가 필요한가?

모든 프로젝트에는 CLAUDE.md(또는 AGENTS.md) 파일이 있어야 하며, 여기에는 다음 내용이 포함됩니다:

• 프로젝트가 무엇을 하는지
• 프로젝트를 어떻게 탐색하는지
• 사용 가능한 개발 워크플로우

프로젝트가 성장함에 따라 파일이 커져 LLM의 컨텍스트 윈도우를 초과할 수 있습니다. 해결책: CLAUDE.md를 약 30줄 이하로 유지하고, 워크플로우를 정의하는 진입점으로만 사용합니다. 이후 LLM은 현재 작업에 따라 읽어야 할 다른 문서를 스스로 선택합니다.

예시 CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

당신의 역할

당신은 부지런한 어시스턴트입니다. 작업과 코드를 주의 깊게 살피세요.
멍청한 아이디어를 발견하면 중단하고 보고하세요.
극도로 간결하게—문법을 희생하고 간결함을 우선하세요.

주요 흐름

다음 작업 목록을 즉시 생성하세요:

1. 사용자 요청을 분석합니다.
2. find docs/ -name "*.md" | sort 명령을 실행해 사용 가능한 문서를 나열합니다.
3. 현재 작업을 해결하는 데 도움이 될 수 있는 문서를 읽습니다.
4. 경로 별칭을 이해하기 위해 tsconfig.app.json을 읽습니다.
5. 명령을 이해하기 위해 package.json을 읽습니다.
6. 문서의 예제를 분석합니다.
7. 실행 계획을 수정하고 사용자에게 할 일 항목과 함께 제시합니다.
8. 사용자가 수락하면 수정된 할 일 항목을 만듭니다.
9. 작업을 시작합니다.
10. 현재 작업을 해결하는 데 도움이 될 수 있는 기술과 명령을 사용합니다.

DO NOT EDIT THIS FILE – it is the final form.

> **핵심 포인트:** 모든 상세 가이드라인, 워크플로우, 설명은 `docs/` 폴더 안에 있습니다. `CLAUDE.md`는 LLM에게 해당 파일들을 어떻게 찾고 사용하는지 *방법*만 알려줍니다.

### `docs/` 폴더 정리  

문서를 논리적으로 구성하고, 관련 파일을 설명적인 이름의 하위 폴더로 그룹화합니다. 아래는 실제 예시입니다:

docs/ ├─ backend/ │ ├─ graphql-api-patterns.md │ ├─ rest-api-patterns.md │ ├─ service-layer.md │ ├─ data-layer.md │ └─ event-system.md ├─ frontend/ │ ├─ actions/ │ │ ├─ create-component.md │ │ ├─ create-modal.md │ │ ├─ create-data-form.md │ │ ├─ create-entity-selection.md │ │ ├─ create-graphql-service.md │ │ ├─ create-rest-service.md │ │ ├─ create-route.md │ │ └─ create-tree-view.md │ ├─ architecture.md │ ├─ design-tokens.md │ └─ ui-ux.md ├─ build-deployment.md ├─ currency-system.md ├─ documentation.md ├─ error-handling.md ├─ localization.md ├─ security.md └─ testing.md

- **전역 문서**(예: `security.md`, `testing.md`)는 높은 수준의 개념을 다룹니다.  
- **기능별 문서**(예: `frontend/actions/create-component.md`)는 구체적인 작업을 안내합니다.

### 이것이 도움이 되는 이유  

1. **작업당 최소 컨텍스트** – LLM이 `find docs/ -name "*.md" | sort`를 실행하면 파일 이름 목록(몇십 줄)만 보게 됩니다.  
2. **선택적 로딩** – 파일 이름을 기반으로 LLM이 관련 문서를 판단하고 해당 문서만 읽습니다.  
3. **확장성** – 문서 파일을 무제한으로 추가해도 컨텍스트 제한을 걱정할 필요가 없습니다. 프론트엔드 작업은 명시적으로 필요하지 않은 한 백엔드나 GraphQL 문서를 로드하지 않습니다.  

### LLM을 사용한 문서 집합 관리  

LLM 자체를 활용해 문서를 깔끔하게 유지하세요:

1. **작업 중** – LLM의 행동을 지속적으로 모니터링하고, 실수를 기록하며, 어떻게 수정했는지 기록합니다.  
2. **작업 후** – `/refine` 명령(또는 동등한 커스텀 명령)을 실행해 학습 내용을 통합하고 불필요한 내용을 정리합니다.

#### 샘플 정제 Todo 리스트

```markdown
- Run `find docs/ -name "*.md" | sort` to see available docs.  
- Review the “How to Write Documentation” guide.  
- Identify outdated or duplicate files.  
- Update file headings for consistency.  
- Add cross‑references where needed.  
- Remove any files that are no longer relevant.  
- Commit the cleaned‑up docs with a concise commit message.  

세션 되돌아보기

이 명령은 LLM에게 세션 중에 일어난 일을 되돌아보게 합니다: 어떤 오류가 발생했는지, 어떻게 극복했는지, 그리고 향후 이러한 오류를 피하기 위해 문서에 추가할 유익한 내용이 있는지.

전제 조건

프로젝트에 대한 문서 작성 방법을 설명하는 markdown 파일이 필요합니다. 이것이 준비되면 LLM은:

1. 세션에 대해 생각합니다.
2. 기존 문서 내 적절한 위치를 찾거나 필요하면 새 문서를 생성합니다.
3. 향후 문제를 방지하는 방법을 자세히 설명합니다.

이렇게 하면 실제 개발 중 겪은 문제를 기반으로 문서가 자연스럽게 진화합니다. 매 세션이 지식 베이스를 개선할 기회가 됩니다.

Why This Works

• Not just for fixing errors – it applies to any case when you create a new system or discover an important action that you want to ensure is done correctly and consistently.
• Action documents (e.g., create‑modal.md, create‑component.md, create‑service.md) define a strict structure for specific tasks, reducing randomness when the LLM executes CLI commands or follows a precise sequence of steps.

Claude Code로 워크플로우를 개선하는 기술

1. Prompt‑First, Refine‑Later

LLM에게 작업을 바로 수행하도록 요청하기보다 다음과 같이 요청합니다:

• 프로젝트 조사하기.
• 문서 읽기.
• 프롬프트에 문제점 찾기.
• 모든 불명확한 경우를 포괄하도록 프롬프트 확장하기.

장점

핵심 팁: LLM이 만든 것을 버리고 새로 시작하는 것을 두려워하지 마세요.

2. 결과가 완벽하지 않을 때

1. 현재 실행을 중단합니다.
2. 프롬프트로 돌아가 무엇이 잘못됐는지 설명합니다.
3. 누락된 정보를 추가하거나 요구사항을 명확히 합니다.
4. 컨텍스트를 정리하고 새 세션을 시작합니다.

그럼 LLM이 명확히 물어보거나 더 나은 접근법을 제안하거나 요구사항을 다듬는 데 도움이 되는 예시를 제공할 수 있습니다. 첫 번째 시도에서 얻은 교훈을 바탕으로 한 두 번째 시도는 거의 항상 원하는 결과에 더 가깝고, 수정 패치가 얽힌 것이 아니라 깨끗한 기반 위에서 이루어집니다.

3. 반복 작업 (Meta‑Prompting)

• 견고한 프롬프트가 준비되면 그 프롬프트를 메타‑프롬프트해서 다시 요청할 수 있습니다.
• 모든 것이 이미 괜찮다면 LLM은 빠르게 프롬프트의 견고함을 확인해 줍니다.
• 새 컨텍스트에서는 처음에 놓쳤던 점을 발견할 수도 있습니다.

같은 원리가 구현에도 적용됩니다:

• 두 개의 구현을 만들고 비교합니다.
• 두 번째 시도의 비용은 낮지만, 문제를 잡아내거나 더 나은 접근법을 찾는 이점은 큽니다.

4. 부분 구현

1. 모의 데이터(인‑메모리 쿼리, 가짜 API 호출)로 완전한 UI를 구축합니다.
2. 구조, 흐름, 사용자 경험을 빠르게 반복합니다.
3. 만족스러워지면 모의를 실제 API 호출로 교체합니다.

Claude Code 이전에는 구현 → 검증 → 테스트 → 반복이라는 과정이 번거로웠습니다.
Claude Code를 사용하면 약 15분 안에 모의 데이터 UI를 만들고, 또 다른 15분 정도면 실제 데이터베이스 연동을 추가할 수 있습니다. 추가 테스트 작업은 약 1시간 안에 완성된 제품을 제공함으로써 예측 가능한 결과를 얻는 데 큰 도움이 됩니다.

주요 요점

• CLAUDE.md를 최소화하고, 진입점으로만 사용하며, 지식 덤프로 사용하지 마세요.
• 모든 실질적인 지식을 잘 정리된 docs/ 계층 구조에 저장하여 LLM이 필요한 부분만 선택적으로 읽을 수 있게 하세요.
• 이 접근 방식은 확장성이 있어, 컨텍스트 제한에 걸리지 않으면서 수십 개의 문서 파일을 보유할 수 있습니다.

지속적인 문서 유지 관리

• LLM 자체를 사용해 문서를 유지하고 발전시키세요.
• 오류를 발견하고 수정하는 각 세션은 향후 세션을 위한 지식 베이스를 개선할 기회입니다.
• 반복 작업을 위해 액션 문서를 만들어 무작위성을 없애고 일관성을 확보하세요.

Claude Code가 제공하는 속도를 활용하고, 각 상호작용이 문서를 더 똑똑하게 만들고 워크플로를 원활하게 하도록 하세요.

Claude Code와 작업하기 위한 팁

• 메타‑프롬프트를 사용해 구현 전에 요구 사항을 다듬으세요.
• 코드를 버리고 새로 시작하는 것을 두려워하지 마세요.
• 두 번 실행하세요 – 빠른 두 번째 검토가 숨겨진 문제를 잡아냅니다.
• 모크를 이용해 부분 구현을 구축하여 빠르게 반복하세요.
• 반복을 수용하세요: 비용은 낮고, 원하는 것을 정확히 얻는 이점은 큽니다.

이러한 패턴은 제가 Claude Code와 작업하는 방식을 바꾸었습니다. 여러분에게도 도움이 되길 바랍니다.