claude.md 怎么写才有用：让 Claude Code 更懂项目的实战指南

先说结论

claude.md 不是提示词仓库。

我更愿意把它当成一份项目协作说明书：告诉 Claude Code 这个项目怎么跑、哪些地方能改、哪些地方别碰、改完怎么验证、什么情况必须停下来问人。

写得好的 claude.md，不一定很长，但一定具体。

它的目标不是让 Claude Code “变聪明”，而是减少它在陌生项目里的猜测空间。

如果你正在比较 Claude Code、Cursor 这类 AI 编程工具，可以先看这篇工具选型文章：

Claude Code vs Cursor：2026 年到底该选谁？

如果你已经决定用 Claude Code，下面才是更关键的问题：怎么让它真的理解你的项目。

为什么很多 claude.md 没什么用

我见过不少 claude.md 会写成这样：

你是世界顶级工程师。
你要认真思考。
你要写优雅代码。
你要保持简洁。

这些话不是完全没用，但性价比很低。

因为 Claude Code 真正缺的通常不是“通用编程常识”，而是这个项目里的局部知识：

• 这个仓库是做什么的
• 哪些目录是当前任务常改的
• 哪些文件一改就容易出事故
• 常用验证命令是什么
• 发布后要不要回填链接
• 哪些内容不能进入公开文章
• 敏感信息该怎么处理

这些信息越具体，Claude Code 越稳定。

我现在只写 5 类信息

我自己的经验是，claude.md 先写这 5 类就够了：

1. 项目边界
2. 常用命令
3. 代码和内容规范
4. 验证方式
5. 禁止事项

后面如果项目变复杂，再补充特殊流程、部署说明、数据口径和长期记忆路径。

1. 项目边界：先告诉它哪里能动，哪里不能动

Claude Code 最大的问题不是不会写代码，而是它刚进项目时没有边界感。

所以我会在 claude.md 里先写：

这个仓库是一个内容站点，主要目标是维护文章、工具页、GEO 外链矩阵和长期复盘文档。

优先修改：
- src/content/posts/
- docs/memory/
- scripts/

不要随便修改：
- 已发布文章的 slug
- 历史归档文件
- 与当前任务无关的页面样式
- 用户没有要求的配置文件

这段话的价值很直接：它会降低“顺手优化一堆无关文件”的概率。

对 coding agent 来说，知道哪里不能碰，往往比知道哪里能碰更重要。

2. 常用命令：让它不用猜怎么验证

很多项目里，Claude Code 改完之后最容易卡在验证环节。

它可能不知道：

• 怎么 build
• 怎么跑测试
• 怎么检查内容
• 怎么验证外链
• 哪个命令是便宜验证，哪个命令是完整验证

所以我会直接写：

常用命令：

npm run build
npm run validate:content
npm run geo:validate

验证优先级：
1. 内容或 frontmatter 变更后，先跑 npm run validate:content
2. 外链矩阵和 UTM 变更后，跑 npm run geo:validate
3. 页面结构变更后，跑 npm run build
4. 如果验证跑不了，要说明原因，不要直接说完成

这比写一句“请保证代码质量”有效得多。

因为它给的是可执行动作。

3. 代码和内容规范：写本项目的习惯，不写空话

claude.md 里最该避免的是泛泛而谈。

比如这些话，对实际执行帮助有限：

请写高质量代码。
请遵循最佳实践。
请保持文章专业。

我更倾向写成本项目真实习惯：

项目习惯：

- 优先沿用现有文件里的 frontmatter 结构
- 不要为了一个小需求新增复杂抽象
- 修改脚本时保持输出字段稳定
- 文件路径要写完整，方便用户直接打开
- 新一轮外链内容必须先按日期建目录
- md、assets、docx 都放到同一天目录里

这种信息很有用，因为它不是网上都能查到的通用建议，而是这个项目里的协作规则。

Claude Code 读到之后，下一次做文章、封面、外链矩阵、数据回填，就不需要每次重新解释。

4. 验证方式：告诉它什么才算完成

如果不写完成标准，Claude Code 很容易“改完文件就说完成”。

但在真实项目里，完成不只是文件变了。

比如内容站点里，完成可能包括：

• 文章已创建
• frontmatter 合法
• 内链能打开
• 目标 URL 已回填
• 外链效果台账已更新
• 能跑的验证已经跑过
• 不能验证的缺口已经说明

所以我会写：

完成标准：

- 能跑验证就必须跑验证
- 如果没法跑，要说明原因
- 发布类任务要回填外部链接
- GEO 任务要更新 docs/memory/geo-campaigns.md
- 引流效果要更新 docs/memory/geo-referral-effect-ledger.md
- 上游 PR / issue 要更新 docs/memory/upstream-contributions-zh.md

这段的作用，是把“完成”从一句主观判断，变成一组可检查动作。

长期做站点、GEO、开源贡献记录时，这一点非常重要。

5. 禁止事项：把历史坑点提前写死

我会专门写一个禁止事项区。

例如：

禁止事项：

- 不要删除用户已有改动
- 不要重写无关模块
- 不要在公开文章里放内部任务说明
- 不要把 token、cookie、appSecret 写进文档
- 不要为了外链硬塞链接
- 不要把平台发布后的回填说明复制到正文

这个区特别适合记录历史事故。

比如你做外链文章时，正文里不能出现“发布后把 URL 发给我，我会回填到某文件”这种内部协作说明；做开源 PR 记录时，可以写公开链接和状态，但不能写私有凭证。

这些不一定是 Claude Code 天然知道的。

写进 claude.md，它下一次就更稳。

一个可以直接改的最小模板

如果你只想先用起来，可以从这个版本开始：

# Project Notes

## Goal

这个项目主要用于维护 Kunpeng AI 内容站点、GEO 外链矩阵、上游贡献记录和长期复盘文档。

## Important Paths

- src/content/posts/：主站文章
- docs/memory/：长期记忆、矩阵记录、验证台账
- docs/memory/outreach-drafts/YYYY-MM-DD/：每轮外链草稿和素材
- docs/memory/upstream-contributions-zh.md：上游 PR / issue 中文台账
- docs/memory/geo-campaigns.md：GEO campaign 总记录
- docs/memory/geo-referral-effect-ledger.md：外链引流效果追踪

## Commands

- npm run validate:content
- npm run geo:validate
- npm run build

## Rules

- 每次新一轮外链，先按日期建文件夹
- md、assets、word 都放到同一天目录下
- 发布后必须回填外部 URL
- 不能把内部发布说明放进平台正文
- 不能泄露 token、cookie、appSecret
- 不要改无关文件

## Definition of Done

- 文件已保存到正确路径
- 外部链接已回填
- 能验证的已验证
- 不能验证的要说明缺口

这不是万能模板，但它比一大段抽象角色设定更容易产生实际效果。

claude.md 和 README 有什么区别

我的理解是：

• README 主要给人看
• claude.md 主要给 coding agent 看

README 可以介绍项目背景、安装方式、贡献方式。

claude.md 更应该写执行细节：

• 做任务时优先看哪里
• 哪些命令能验证
• 哪些目录不能乱动
• 什么时候要更新台账
• 什么内容不能公开

它不需要漂亮，但要像项目里的老同事一样可靠。

怎么持续进化 claude.md

不要一次性把 claude.md 写成百科全书。

更好的方式是：每次 Claude Code 犯了一个可复用的错误，就补一条规则。

例如：

• 它忘了回填外部链接，就补“发布后必须回填 URL”
• 它把内部说明复制进正文，就补“内部任务说明不能进入公开内容”
• 它改了无关文件，就补“只改当前任务相关文件”
• 它没有跑验证，就补“能跑验证就必须跑”

这样写出来的 claude.md 才会越来越贴近你的真实项目。

它不是一次性文档，而是项目和 agent 协作出来的长期记忆。

最后

如果只能记住一句话，我会说：

claude.md 的核心不是提示 Claude Code 变成谁，而是告诉它这个项目真实怎么协作。

好的 claude.md 应该像一个熟悉项目的人在旁边提醒：

这个目录能改。
那个文件别碰。
这个命令能验证。
这个坑以前踩过。
这个链接发布后要回填。

当它能做到这一点，Claude Code 的效率会明显上一个台阶。