Claude Code 的 CLAUDE.md 入门模板：既有代码库的最小规则

CLAUDE.md 用来减少每次开工前的重复说明

在既有代码库里使用 Claude Code，最大的摩擦往往不是模型不够聪明，而是它不知道这个项目的本地规则。包管理器是什么、应用目录在哪里、哪些文件是生成物、哪些命令不能碰、完成标准是什么，如果这些信息只存在于聊天记录里，下一次会话还要重新解释。

CLAUDE.md就是为了解决这个问题。官方的Claude Code memory 文档说明，CLAUDE.md会作为持久指令在会话开始时加载。需要注意的是，它是上下文，不是强制执行层。真正要限制命令、文件路径或危险操作时，要配合settings和security里的权限设计。

下面的模板适合已经存在的项目，而不是空白演示仓库。这里的 harness 可以理解为“让 agent 安全工作的脚手架”。你不需要一开始就写完整的公司手册，先给 Claude Code 一个小而具体的工作边界。更多模板可以看CLAUDE.md 模板集，权限部分可以接着读Claude Code 权限指南。

可直接复制的 CLAUDE.md 模板

第一版要短。把每次会话都需要的事实写进去：项目概况、命令、工作边界、质量规则和完成条件。不要把所有愿望都塞进去。

# CLAUDE.md

## Project snapshot
- Product: content site and paid template store
- Stack: Astro, TypeScript, MDX, npm
- Main app: site/
- Source articles: site/src/content/blog*/
- Owner voice: practical, evidence-based, no hype

## Commands
- Install dependencies: cd site && npm install
- Start local dev server: cd site && npm run dev
- Build check: cd site && npm run build
- Search fast: rg "keyword" site/src
- Inspect git state: git status --short

## Working rules
- Read existing files before editing.
- Keep changes scoped to the requested slug or feature.
- Do not edit .env, dist, generated reports, or unrelated locale files.
- Preserve pubDate, category, tags, author, lang, and heroImage unless they are broken.
- Ask before destructive git operations, production deploys, or secret rotation.

## Article quality
- Japanese canonical articles should be 4000-6000 characters excluding code.
- Include at least three real use cases.
- Include concrete pitfalls and how to avoid them.
- Include runnable code or config examples, not pseudocode.
- Check official docs when the topic may have changed.

## Definition of done
- The requested files are edited.
- Code fences and JSON/YAML examples are valid.
- Links to internal pages and official docs are present.
- Verification commands have run or skipped checks are explained.
- Remaining risks are stated in the final message.

把它保存到仓库根目录的CLAUDE.md。如果团队已经有AGENTS.md，不要复制两份规则；新建一个很薄的CLAUDE.md去引用它，再补充 Claude Code 专用内容。个人偏好放进CLAUDE.local.md，不要污染团队共享文件。

用 settings 管住危险动作

CLAUDE.md能告诉 Claude Code 怎么做，但不能替代权限控制。比如只写“不要 git push”是不够的。危险命令和敏感路径应该放在.claude/settings.local.json或共享的.claude/settings.json里。

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(site/src/content/blog/**)",
      "Bash(rg:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(git reset:*)",
      "Bash(git checkout --:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)",
      "Edit(reports/**)"
    ]
  }
}

这段 JSON 是配置，不是文章内容。个人环境使用settings.local.json，团队默认值使用settings.json。真实项目复制前，请再核对官方settings 文档，因为权限项会随着 Claude Code 更新而变化。

3 个实际用例

用例	写进 CLAUDE.md 的内容	改善点
多语言文章维护	目标 slug、10 个 locale、frontmatter 保护、正文长度、CTA、验证步骤	减少缺失语言、英文残留、链接错误和日期遗漏
既有 SaaS 的小修复	可编辑目录、测试命令、数据库变更审批、日志要求	避免顺手重构和危险 migration
团队代码审查	严重度格式、文件行号、复现步骤、测试缺口	审查结果更容易转成 issue 或 PR comment

多语言文章最容易出错的是“文件都有，但内容不对”。例如中文、韩文、印尼文文件存在，却仍然是英文正文。CLAUDE.md里明确 locale 目录和检查方式，可以让 Claude Code 在一开始就按组处理。

SaaS 修复的关键是范围。小 bug 不应该顺便重写认证、计费或数据库层。把“先读相关文件、只改请求范围、跑对应测试、数据库变更先询问”写清楚，比笼统要求“保持质量”更有用。

团队审查则需要输出格式。要求 Claude Code 给出 severity、file、line、impact、reproduction、test gap，审查才不会变成泛泛的赞同。需要脚本化运行时，可以参考官方CLI reference。

常见坑和避免方法

第一个坑是把CLAUDE.md写成愿望清单。“安全地实现”“保持高质量”“不要破坏功能”都太抽象。要改成可验证的句子，比如“运行npm run build”“不编辑reports/”“description 不超过 120 字符”。

第二个坑是写进秘密信息。API key、客户名、内部 dashboard、未公开收入数据都不应该进入CLAUDE.md。正确写法是描述处理规则：秘密在环境变量里，不打印，不在总结里复述，打开相关文件前先询问。

第三个坑是命令过期。项目从 Yarn 换成 npm、从 Jest 换成 Vitest、从 Next.js 换成 Astro 后，如果CLAUDE.md不更新，Claude Code 会很自信地执行错误命令。每次工具链变化后，先改这个文件。

第四个坑是把它当成 review 的替代品。CLAUDE.md能要求验证，但不能证明验证真的完成。让最终回复包含验证命令、结果、修改文件、未覆盖风险，才能形成可追踪的工作记录。

建议的导入顺序

先用本文模板写一个 30 行左右的文件。接着用三个小任务测试它：一篇文章更新、一个 UI 文案修正、一次代码审查。只有当真实任务暴露出重复错误时，再增加一条规则。最后，把必须强制执行的边界移到 settings、CI、branch protection 或部署审批。

这样做也更适合商业站点。文章、产品卡片、购买链接、咨询表单都是转化路径。Claude Code 修改正文或布局时，如果没有检查 CTA，流量还在，收入可能已经悄悄断掉。把 products 和 training 链接检查放进完成条件。

实际维护时，我建议给CLAUDE.md增加一个很短的审查清单。第一，命令是否仍然可运行。很多仓库最初写的是npm test，后来测试命令拆成npm run lint、npm run typecheck和npm run test:unit，文件却没有更新。第二，编辑范围是否和当前任务匹配。如果多个 worker 同时处理不同 slug，范围就不能写得太宽。第三，禁止事项是否写清楚。比如不生成报告、不提交、不推送、不部署，这些都应该出现在工作规则或完成条件里。

还要记录规则存在的原因。只写“不要编辑 reports”容易被后来的维护者删掉；写成“reports 由审计脚本生成，本任务不允许更新报告”就更清楚。CLAUDE.md不是越严越好，而是要让下一位开发者和下一次 Claude Code 会话都知道边界为什么存在。

还有一个实用做法：不要把很长的 review prompt 放进主CLAUDE.md。每天都要加载的规则和偶尔使用的审查模板不是一回事。如果审查文字很长，可以放到.claude/commands/或单独的模板文档里。主文件只保留一句原则：review 输出必须包含严重度、文件、行号、影响、复现和测试缺口。这样既节省 context，也保留了质量标准。

判断一条规则是否该留下，可以问一个问题：下一位维护者读完后，行动会不会改变？如果不会，就删掉；如果会影响验证、审批、编辑范围或最终报告，就保留。这个标准能让文件长期保持轻量，而不是变成无人阅读的仓库口号。

对小团队来说，这个标准也能减少争论：规则不是为了显得严格，而是为了让实际交付更可预测。

这也是最容易坚持的改进方式。

个人使用可以从ClaudeCodeLab 产品里的模板和清单开始；团队需要权限、审查门禁、培训材料和仓库专用规则时，使用Claude Code 培训与咨询会更省时间。最好的CLAUDE.md不是最长的，而是能阻止下一次重复错误的那一版。