如何编写CLAUDE.md：向Claude Code说明项目规则

核心摘要： 在CLAUDE.md中简短、具体地写下每次都需要重新说明的项目规则。适合记录可实际核验的内容，例如工作命令、修改时的注意事项和完成报告标准。请选择所需规则，而不是复制所有文档；项目发生变化时，也应一并更新该文件。

1. 选择要写入CLAUDE.md的内容

官方文档将CLAUDE.md描述为用于记录项目或用户工作的持续指导的Markdown文件。项目文件的位置与读取范围可在官方记忆文档中确认。可以将项目根目录的CLAUDE.md作为起点。

适合写入的是每次新任务都会反复说明的内容。例如“保留用户已经修改的文件”“本项目的日期使用韩国时间显示”“界面文字采用术语表中的表达”等，都是仅阅读代码难以理解其意图的规则。仅一个临时任务需要的详细要求可在对话中说明，持续适用的规则则留在文件中。

2. 从简短的编写示例开始

以下是假想待办事项管理网页项目的示例。命令与路径应按实际仓库修改。直接粘贴该示例并不会自动建立验证环境或运行测试。

# 프로젝트 규칙
## 목적
한국어 사용자를 위한 개인 할 일 관리 화면이다.

## 작업 방식
- 작업 시작 전 기존 변경 사항을 확인하고 보존한다.
- 요청한 기능과 관계없는 파일은 수정하지 않는다.
- 화면 문구는 docs/terms.md의 용어를 따른다.

## 검증
- package.json에서 실제 실행 가능한 검증 명령을 확인한다.
- 관련 검증을 실행하고 명령과 결과를 보고한다.
- 화면 동작 변경은 정상 입력과 빈 입력을 함께 확인한다.

## 완료 보고
- 변경 파일과 이유를 간단히 정리한다.
- 실행하지 않은 검증은 실행했다고 쓰지 않는다.
- 남은 문제와 확인하지 못한 조건을 명시한다.

此示例的关键是将句子对应到可检查的行为。“做得完美”很难判断是否完成，而“确认输入为空时是否显示提示”有明确的比较对象。如果项目没有术语表，应删除相应规则，或先整理实际文档。

3. 只记录已确认的执行命令

看到其他项目的示例就直接写入npm test或npm run build，可能会写下实际不存在的命令。应从配置文件和项目说明确认命令，并记录它验证哪些工作。如果快速语法检查与完整集成测试的作用不同，可以各用一行说明目的。

例如“修改界面文字后打开指定页面确认换行”与“修改计算逻辑后验证边界值案例”需要不同的检查方式。可以写下根据变更选择必要验证的标准，避免对所有修改都重复同一套冗长操作。每次任务的报告应说明是否实际执行以及结果。

4. 区分指导与权限设置的作用

“不要打开真实客户文件”是说明意图的指导。如果需要从技术上限制工具访问，应另行处理权限设置。Anthropic文档说明，不将CLAUDE.md视为强制配置，而是通过独立规则管理工具权限。设置方法请参阅官方权限指南。

此外，不要在将上传至公开仓库的CLAUDE.md中写入密码或API密钥。可以说明所需值的名称和查找流程，但不要粘贴实际秘密值。“需要环境变量X”与“记录X的实际值”是不同内容。也应确认规则文件的共享范围。

5. 规则增多时的整理方法

优先删除或修改过时命令、重复表达和相互冲突的规则。如果“新代码使用A库”与“停止使用A”同时存在，就无法明确应该遵循哪一条。添加规则时，应让读者知道为什么需要它，以及它适用于哪些任务。

确认文件是否正确应用时，可以要求Claude整理当前任务适用的指导及其依据路径，然后自行对照。但AI说明了规则，并不能证明所有工作都遵守了规则。完成后仍应检查修改的文件和验证结果。

定期检查时可以使用三个简单问题：“这是当前项目中可执行的命令吗？”“是否与其他规则冲突？”“能否从回答或修改结果判断是否遵守？”无法回答这三个问题的句子，可以进一步具体化，或移至个别任务说明中。

6. 区分写入规则文件与留在个别对话中的条件

将规则文件作为所有工作的记录本，会混淆过去与当前的要求。应区分“项目始终需要遵守的约定”与“仅本次请求需要的选择”。例如本次页面的按钮颜色可写在任务请求中，而所有页面都应遵循的术语表可写入持续指导。

每添加一条规则，都应思考“这是项目中反复发生的问题吗？”如果只是一次回答不满意，就强制所有工作采用冗长流程，小修改也可能变得不必要地复杂。问题反复发生时，连同适用条件一起记录更容易管理。

7. 理解适用范围并拆分文件

当前官方记忆文档区分用户指导、项目指导与子区域指导。工作目录及其上级路径中的CLAUDE.md会在启动时读取，子文件夹指导可能在读取相关文件时加入。多个指导文件会共同进入上下文，而不是简单地互相替换，因此需要检查是否存在冲突。

[가상 배치 예시]
my-project/
  CLAUDE.md                 공통 약속
  docs/
    CLAUDE.md               문서 표현과 출처 기록 규칙
  src/
    ui/
      CLAUDE.md             화면 문구와 표시 검토 규칙

这种布局是解释各自职责的示例，并非必须遵循的官方文件夹结构。小项目可能只需要一个根目录文件。如果拆分，可在根文件中放置所有工作的共同约定，在子文件中只记录该区域需要的不同要求。同一验证命令若复制到三个文件，下次命令变化时就需要全部更新。

可以请求“列出当前适用的指导路径，以及与本次文件相关的规则”，检查是否读取了预期文件。如果文件遗漏，应先对比工作位置与文件布局，而不是立即扩充内容。回答提到指导，与实际修改遵守指导，需要分别审查。

8. 将抽象规则改成可检查的句子

右侧句子整理了假想项目的要求，因此直接应用前，应先确定自己项目的正常行为。例如结果为0条时显示提示，并不是所有应用都通用的正确答案。规则文件用于记录产品决策，不应让AI擅自确定决策。

현재 CLAUDE.md를 검토해 주세요. 파일은 수정하지 마세요.
각 규칙에 대해 다음을 정리하세요.
- 적용할 작업의 종류
- 지켰는지 판단할 결과나 근거
- 코드나 설정과 충돌하는 부분
- 이번 작업만의 요구가 섞인 부분
모호한 규칙에는 구체화한 문장 초안을 제안하세요.
근거가 없는 실행 명령과 경로는 만들지 마세요.

9. 整理假想规则冲突的示例

假设根目录指导写着“所有界面文字均使用英语”，而UI指导写着“新页面文字使用韩语”。不能仅因为某规则写在更近的文件中，就代替团队确定选择；应确认希望对哪些任务应用哪条规则。明确适用范围可以减少矛盾。

[수정 전 가상 지침]
루트: 화면 문구는 영어로 쓴다.
UI 폴더: 새 화면은 한국어로 쓴다.

[작성자가 제안한 정리 예시]
루트: 기존 화면 문구는 이번 작업에서 번역하지 않는다.
UI 폴더: 새 한국어 화면의 문구는 docs/terms.md를 따른다.
대상 화면 목록은 개별 작업 요청에서 지정한다.

该修改方案区分了保持既有页面与编写新页面这两个不同对象。如果实际项目决定“将所有页面改为韩语”，就需要完全不同的规则。整理前应确认产品选择，再将选择写入指导。

阅读/init生成的草稿时

官方文档中的/init可用于生成起始指导。应检查生成草稿发现的命令是否确实存在于配置中、是否过于冗长地复制了文件结构，以及是否将个人偏好当作项目共同规则。自动生成并不意味着已经成为获团队批准的规则。

/init 초안에서 다음 부분을 다시 검토해 주세요.
1. 명령은 설정 파일의 근거 위치를 함께 적으세요.
2. 일반적인 설명과 이 프로젝트만의 주의점을 구분하세요.
3. 실행하지 않은 명령을 성공한 것으로 쓰지 마세요.
4. 서로 다른 폴더 지침이 충돌하면 목록으로 보여 주세요.
5. 제안은 먼저 검토 가능한 초안으로 제시하세요.

完成改变命令或保存格式的任务后，也应查找相关指导。如果代码说明与指导不一致，后续任务可能再次采用错误前提。相比规则数量，当前代码、团队决策与验证流程是否相互一致更重要。

常见问题与错误解决

可以自动生成吗？ 官方文档介绍了通过/init创建起始文件的方法。生成内容也需要检查是否符合实际命令与团队规则。 文件越长越好吗？ 目的是清楚保留所需指导。 似乎忽略规则时怎么办？ 检查文件位置、适用范围及相互矛盾的指导，并具体比较实际违反的内容。

官方来源与确认日期

• Claude如何记住您的项目
• 配置权限

官方文档确认日期：2026年10月3日。此后界面与提供条件可能发生变化。