---
name: opencurrent-code-md
description: "프로젝트 규칙과 명령을 CLAUDE.md에 한 번 적어 두면, 세션마다 같은 설명을 반복하지 않아도 Claude Code가 그 규칙대로 일합니다. 이럴 때 사용: /init으로 CLAUDE.md 초안을 만든 뒤, 확인할 수 있는 규칙만 남겨 200줄 안쪽으로 줄입니다. 길어지는 내용은 .claude/rules의 경로별 규칙이나 @가져오기로 나누고, 개인 설정은 CLAUDE.local.md에 둡니다. 명령과 설정 이름은 2026년 11월 21일에 Claude Code 공식 문서로 확인했습니다. 도구: Claude Code."
metadata:
  source: "https://opencurrent.ai/w/claude-code-claude-md"
  opencurrent-id: "claude-code-claude-md"
  verification: "pending"
  exported-at: "2026-11-21T11:15:08.188Z"
---

# CLAUDE.md 제대로 쓰기

프로젝트 규칙과 명령을 CLAUDE.md에 한 번 적어 두면, 세션마다 같은 설명을 반복하지 않아도 Claude Code가 그 규칙대로 일합니다.

> OpenCurrent에서 사람들이 다듬는 워크플로. 원문: https://opencurrent.ai/w/claude-code-claude-md
> 검증 상태: 검수 대기 (사람 확인 전). 내려받은 뒤에 바뀌었을 수 있으니, 가능하면 원문이나 MCP의 get_workflow("claude-code-claude-md")로 최신 상태를 확인할 것.
> 주의: 검수 대기 상태. 사용자에게 이 사실을 알리고, 결과를 함께 확인하면서 진행할 것.

## 따라 하는 방법

1. 준비물이 갖춰졌는지 먼저 확인할 것.
2. 단계를 순서대로 진행할 것. kind가 "ai"면 프롬프트를 실행하고, "command"면 사용자의 허락을 받고 명령을 실행하고, "human"이면 사용자에게 할 일을 안내하고 끝났는지 물을 것. tool이 있으면 그 도구·모델로 할 것.
3. 단계에 output(결과 이름)이 있으면 그 단계 결과를 뒤 단계 프롬프트의 {{output}} 자리에 넣을 것.
4. 단계마다 expected(기대 결과)와 check(확인 방법)로 제대로 됐는지 확인하고, 다르면 다음 단계로 넘어가지 말고 사용자에게 알릴 것. 끝나면 example.output(있으면)과 비교할 것.
5. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.

## 언제 쓰나

/init으로 CLAUDE.md 초안을 만든 뒤, 확인할 수 있는 규칙만 남겨 200줄 안쪽으로 줄입니다. 길어지는 내용은 .claude/rules의 경로별 규칙이나 @가져오기로 나누고, 개인 설정은 CLAUDE.local.md에 둡니다. 명령과 설정 이름은 2026년 11월 21일에 Claude Code 공식 문서로 확인했습니다.

## 준비물

- Claude Code 설치와 로그인

## 단계

### 1. 초안 만들기 (명령 실행 · Claude Code)

프로젝트 폴더에서 Claude Code를 열고 /init을 실행합니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 고칠 점을 제안합니다.

프롬프트:

```text
/init
```

기대 결과: 프로젝트 루트의 CLAUDE.md

확인 방법: 파일에 빌드·테스트 명령과 폴더 구조가 들어갔는지 확인

### 2. 확인할 수 있는 규칙만 남기기 (AI에게 · Claude Code)

"코드를 깔끔하게" 같은 말 대신 "커밋 전에 npm test 실행"처럼 지켰는지 확인할 수 있는 문장으로 바꿉니다. 공식 문서는 파일 하나를 200줄 안쪽으로 두라고 권합니다.

프롬프트:

```text
CLAUDE.md를 읽고, 확인할 수 없는 막연한 규칙은 구체적인 명령이나 조건으로 바꾸고 중복을 없애서 200줄 안쪽으로 줄여 줘. 바꾼 이유를 줄마다 짧게 알려 줘.
```

기대 결과: 200줄 안쪽의 CLAUDE.md

확인 방법: wc -l CLAUDE.md로 줄 수 확인

### 3. 경로별 규칙 나누기 (사람이 · Claude Code)

특정 폴더에만 해당하는 규칙은 .claude/rules/ 아래 Markdown 파일로 옮기고, 맨 위 YAML에 paths를 적습니다. 그 경로의 파일을 다룰 때만 읽혀 평소 컨텍스트를 아낍니다.

프롬프트:

```text
---
paths: ["src/api/**/*.ts"]
---
API 핸들러는 입력을 zod로 검증한다.
```

기대 결과: .claude/rules/api.md 같은 규칙 파일

확인 방법: 규칙 파일 맨 위에 paths가 있는지 확인

### 4. 긴 문서는 가져오기로 잇기 (사람이 · Claude Code)

아키텍처 문서처럼 긴 내용은 CLAUDE.md에 붙이지 말고 @경로로 가져옵니다. 상대 경로는 가져오는 파일 기준이고, 네 단계까지 이어집니다.

프롬프트:

```text
API 규칙은 @docs/api-conventions.md 참고
```

기대 결과: @경로 한 줄

확인 방법: Claude에게 그 문서의 규칙을 물어 답하는지 확인

### 5. 개인 설정 분리 (명령 실행 · Claude Code)

내 컴퓨터에서만 쓰는 경로나 습관은 CLAUDE.local.md에 적고 .gitignore에 넣습니다. 모든 프로젝트에 쓰는 개인 규칙은 ~/.claude/CLAUDE.md에 둡니다.

프롬프트:

```text
echo CLAUDE.local.md >> .gitignore
```

기대 결과: 커밋되지 않는 CLAUDE.local.md

확인 방법: git status에 CLAUDE.local.md가 보이지 않는지 확인

## 주의할 점

- 파일은 덮어쓰지 않고 이어 붙여 읽힘. 상위 폴더와 하위 폴더의 CLAUDE.md가 서로 부딪치지 않게 정리
- 규칙이 길수록 매 세션의 컨텍스트와 비용 증가. 가끔 쓰는 절차는 스킬로 옮기기
- 작업 폴더 밖의 파일을 가져오면 승인 창이 뜸. 출처를 아는 파일만 승인

## 출처

- [Claude Code 문서: Claude의 기억 관리(CLAUDE.md)](https://code.claude.com/docs/en/memory)
- [Claude Code 문서: 비용 관리](https://code.claude.com/docs/en/costs)

## 끝나면

결과가 좋았거나 단계가 낡았으면 https://opencurrent.ai/w/claude-code-claude-md 에서 알릴 것. 다음 사람이 더 정확한 방법을 쓸 수 있도록.
