CLAUDE.md 最佳实践：适合真实项目的配置模板与团队规则

CLAUDE.md 的价值，是让 Claude Code 每次进入项目时都能看到稳定的项目说明，而不是让你反复解释目录结构、测试命令和团队约定。

但它不是越长越好。官方文档把 CLAUDE.md 定位为加载到上下文中的指令，而不是强制执行的安全策略。真正需要阻止的行为，应该放到 settings、permissions 或 hooks 中。

本文给出适合初学者直接复制的模板，也会说明团队如何维护、哪些内容不该放进去，以及如何和 Obsidian、教材、咨询转化路径连接起来。

先理解：CLAUDE.md 是指导，不是强制策略

先区分四层：CLAUDE.md 是人写的长期指令；Auto memory 是 Claude 在本机保存的学习笔记；settings 和 permissions 控制客户端行为；hooks 在固定生命周期执行命令。把安全阻断写进 CLAUDE.md，看起来像规则，实际并不可靠。

机制	作用	适合内容
CLAUDE.md	人写的长期指令	规范、结构、验证命令
Auto memory	Claude 保存的本机学习笔记	调试经验、偏好、反复发现
settings / permissions	客户端配置和权限规则	允许、拒绝、目录权限
hooks	固定生命周期执行命令	阻止危险操作、验证、格式化

如何选择 CLAUDE.md 的位置

Claude Code 会从当前工作目录向上读取 CLAUDE.md 和 CLAUDE.local.md。项目根目录的文件会在会话开始时进入上下文；子目录中的 CLAUDE.md 通常在 Claude 读取该目录文件时才加入。团队共享规则放根目录，个人偏好放 CLAUDE.local.md，模块规则靠近对应代码。

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

哪些内容应该常驻，哪些不该放

应该常驻的内容包括构建命令、测试命令、架构边界、命名规范、禁止模式、发布前检查。不要放密钥、长会议纪要、完整历史日志、一次性任务计划，或任何不是每次都需要的信息。

• 放入：构建、测试、lint、类型检查、发布前确认。
• 放入：可修改边界、不可修改边界、命名规范。
• 不要放：密钥、长会议纪要、历史日志、一次性指令。
• 不要放：官方文档全文复制。保留 URL 和判断标准即可。

可复制的 CLAUDE.md 模板

下面的模板故意保持短。它让 Claude Code 知道怎么验证、哪里可以改、哪里不能动，同时不会把启动上下文撑爆。

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

谨慎使用 imports 与 .claude/rules/

@path/to/file import 适合整理结构，但不会节省 token，因为被 import 的文件仍然会加载到上下文。文件变大时，先删除过期内容，再把路径相关规则移动到 .claude/rules/。

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

三个真实使用场景

1. 新成员加入时，CLAUDE.md 应该告诉他系统边界、常用命令和验收方式，而不是复制所有 README。
2. 修 bug 时，写清复现命令、日志位置、最小测试命令，可以减少 Claude Code 的无效探索。
3. 做内容和知识管理时，把语气、内部链接、发布检查放进 CLAUDE.md，把长研究笔记留在 Obsidian 或 docs 中。

失败案例与陷阱

1. 失败例1：把所有 README、会议纪要都 import。解决办法是只保留常用的五到十条，其余让 Claude 按需读取。
2. 失败例2：写“代码要优雅”这种无法验证的规则。应该改成 npm run lint、src/api/**、禁止 default export 等具体规则。
3. 失败例3：只在 CLAUDE.md 写安全禁令。真正危险的命令要用 permissions 或 PreToolUse hook 阻止。

团队维护规则

维护节奏要克制。只有当 Claude 第二次犯同样错误、代码评审反复出现同样意见、命令或架构边界发生变化时，才更新 CLAUDE.md。

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

实际设计步骤

不要一开始就追求完美的 CLAUDE.md。更好的做法是让 Claude Code 处理一个小任务，观察它在哪些地方迷路：是否读了太多文件，是否忘记测试，是否修改了不该碰的模块。只把这些真实问题变成短规则。

例如它总是直接读取环境变量，就写明“环境变量只能通过 src/config.ts 访问”。如果它每次都跑全量测试导致很慢，就写明“API 修改先跑对应 spec，最后再跑全量验证”。来自实际失败的规则，比抽象口号更稳定。

团队维护时，CLAUDE.md 的 PR 应该检查三件事：新规则是否和旧规则冲突，是否能被命令或路径验证，是否把个人偏好误写成团队标准。

下一步阅读与转化路径

想连接知识工作流，可以继续读Claude Code 与 Obsidian 集成；日常提效看Claude Code 生产力技巧；安全自动化配合Claude Code 权限设置指南。团队培训和咨询可以从培训与咨询页面进入。

本文确认过的内容

这次更新参考了官方 memory、context window、settings 和 commands 文档，避免把 CLAUDE.md 写成强制策略，并把模板压缩到真实项目可维护的长度。 Official references: memory, context window, settings, and commands.