我把所有 claude code 配置开源了
半年前我在项目根目录放了第一个 CLAUDE.md。起因很简单：每次开工都要跟 AI 解释一遍「这个项目是干嘛的」，太烦了，那就写个文档让它自己读。最开始就几十行，列了技术栈、目录结构、几个编码约定。后来这个文件越写越厚，周边又长出了 skills 和 MCP 配置，最后我把整套东西开源了。这篇讲一下这套配置是怎么长出来的，里面都有什么。
CLAUDE.md 是怎么长起来的
一开始它就是个 README 加强版。后来发现可以往里加代码风格、测试命令、git 规范，加完之后 AI 写出来的代码明显更贴项目风格。再后来把常见任务的标准流程也写进去：怎么新建一个 API 端点，怎么写数据库迁移，怎么处理错误。写到这个程度它基本上就是一本操作手册了，一本告诉 AI 怎么干活的手册，早就不是项目简介那个范围了。
有一次换模型，我才真的意识到这个文件有多值钱。新模型第一次打开这个项目，自己把 CLAUDE.md 读了，第一句话就是：「我了解了，这是一个 Nobelium 博客，你用特定方式组织 posts，生成 metadata 要跑 build-posts-index。开始前需要跑 npm test 对吗？」这轮对齐，换任何一个人类接手我的项目也得做一遍，一般得聊上一阵才能聊明白。现在这些东西就压在几行文字里，新模型进来自己读一遍就对齐了，人来读其实也一样。
skills 把模糊需求拆成精确步骤
skills 是 CLAUDE.md 的自然延伸。「写一篇博客」是个很模糊的需求，但在我的环境里它被拆成了精确步骤：选 series 目录、写 frontmatter、加图片引用、跑 build-posts-index、跑 npm test、最后跑 npm run build 验证。每个 skill 就是一份完整的执行手册，或者说一份 SOP，输入什么、产出什么、怎么校验、失败了怎么处理，都写在里面。
我觉得 skill 最实用的场景是 onboarding。新同事加入，不用我再口头讲一遍「这个项目怎么改」了，直接丢一个 skill 过去，AI 带着他走一遍就行，等于讲解这一步也交给 AI 了。
MCP 给 AI 外部能力
CLAUDE.md 给的是项目 context，skills 给的是操作流程，MCP（Model Context Protocol）给的是外部能力。我的配置里接了十几个 MCP 服务：GitHub（读 PR、issues，还能收 notifications）、文件系统（读写本地文件）、Tavily（网页搜索）、Playwright（浏览器测试），等等。等于给 AI 接了一圈感官。
三层配置各司其职——CLAUDE.md 给项目 context、skills 给操作流程、MCP 给外部能力，一起喂给 AI
单个工具没什么好讲的，有意思的是组合起来用。比如我跟 AI 说「查一下本周的 issues，有明确解决方案的，切分支、写代码、跑测试、提 PR」，它能自己走完全流程：项目 context 在 CLAUDE.md 里，操作流程在 skills 里，执行工具 MCP 都给了。这种活我以前要么自己挤时间做，要么干脆排不上，反正现在就是跟它说一句话的事。
一句话丢给 AI，它就自己走完切分支、写代码、跑测试、提 PR 的全流程
开源之前想了挺久
决定开源的时候犹豫了一阵。一方面这是非常个人的东西，编码习惯、项目结构偏好、甚至一些吐槽都在里面，挺私人的；另一方面很多人想用 claude code 但不知道从哪下手，官方文档讲的是功能，不讲怎么让 AI 理解你的项目。最后的决定是把敏感信息去掉，把框架和方法论留下来。
仓库里有：全局 CLAUDE.md 模板、skills 的目录结构、MCP 配置、还有几个示例的项目级 CLAUDE.md。重点是「怎么做的思路」，不是我的特定配置。
发出去之后收到的反馈比预期多。有人说「原来 CLAUDE.md 可以这样写」，也有人说 skills 这个思路让他把自己的工作流重新想了一遍。反正我自己的感受是，会写 prompt 这件事没大家想的那么重要，感觉 AI 干不好活，多数时候是因为它不了解你的 context——项目是干嘛的它不知道，你那些约定和偏好它也不知道。这些东西写下来给它，它就知道了。
CLAUDE.md 里具体写什么
具体的写法大概是这样的：信息密度最重要，AI 会反复读这个文件，每多一行都有 token 成本。我按优先级组织：项目概述 4-5 行，然后是技术栈、编码约定、验证流程、常见任务。能查到的不写，会变的信息也不写。就跟给新同事做 5 分钟 onboarding 一样，给方向和规则就够了。
验证流程这块是反复踩坑之后才加的。「写完代码要跑什么验证」这件事我以前经常忘，写进 CLAUDE.md 之后 AI 每次都会提醒我。很小的一个细节，省了很多次回滚。
这套东西还在变
skills 的粒度我还在调，拆太粗执行不稳定，拆太细维护成本又上来了。MCP 接哪些也还在收敛。开源以来收到了一些很不错的 PR 和讨论。仓库在下面，感兴趣可以直接翻。