我的CLAUDE.md编写实践：从Claude Skills中学习分层架构思路

本文参考了一篇关于如何编写优秀的CLAUDE.md的前沿博客，并结合了我个人的实践经验，分享我的CLAUDE.md结构模板和分层架构思路。

CLAUDE.md结构模板

.claude/
├── CLAUDE.md           # Core principles (~60 lines)
└── docs/
    ├── nginx.md        # Task-specific documentation
    ├── dev-server.md
    ├── mcp-*.md        # MCP tool references
    └── ...

作为一名无代码基础的vibe coder小白，我在小鸡上使用 Claude Code cli 有好几个月了，主要处理办公文件、开发自用小脚本等，踩过不少坑，也逐渐摸索出了一套适合自己的工作流。

虽然很多大佬分享过很专业的CLAUDE.md，如经典的“你是Linus Torvalds…”，但我认为不同人群使用Claude的需求不同，过分复杂的主提示词可能会在处理简单任务时分散注意力。因此，我选择因地制宜，分享我的思路。

CLAUDE.md的重要性

LLM本质上是无状态的，每次对话开始时，它对你的代码库一无所知。而CLAUDE.md是唯一一个在每次会话中自动注入上下文的文件，相当于给Claude的"入职培训手册"。但这个手册不能太厚，否则留给自定义指令的空间有限。

一开始我将所有东西都塞进CLAUDE.md，结果发现效果并不好。

从Skills学到的灵感：主干精简，按需展开

Skills的设计思路给人很大启发。主入口只放一个精简的描述，说明这个skill是干什么的、什么时候触发。真正的详细内容放在SKILL.md里，只有当这个skill被激活时才会加载进上下文。这就是"渐进式披露"的思路：主文件只放关键信息和索引，详细内容分散到子文档里，需要时再读取。

我将这个思路迁移到自己的小鸡环境的CLAUDE.md上。主文件大约60行，只包含：VPS环境基本信息、技术栈偏好、代码风格原则、工作流程概述、以及一个文档索引表。具体的操作细节，全部放在/root/.claude/docs/目录下的独立文件里。

分层架构的好处

首先是主上下文保持清爽。日常写代码时，Claude不需要知道Nginx SNI分流的细节。只有当我说"帮我加个子域名"时，它才会去读nginx.md。

其次是迭代方便。随着使用，我会不断发现需要补充的内容。如果都写在主文件里，很快就会变成一团乱麻的补丁。现在我只需要更新对应的子文档，主文件基本不用动。

最后是关注点分离。Nginx的配置逻辑和Codex MCP的调用方式是完全不相关的两件事，没必要放在一起。分开之后，每个文件都更容易维护。

一些体会

保持精简：主文件最好控制在60行以内，只提通用信息、代码风格、技术栈约定、子文件路径等，不写细节；docs/下的子文件则可以看情况展开写。
路径用绝对路径：所有的文档引用都用绝对路径，比如/root/.claude/docs/nginx.md而不是./docs/nginx.md。Claude经常需要在不同目录下工作，相对路径容易出问题。
子文档要自包含：每个子文档应该能独立阅读，不需要依赖主文件的上下文，不能假设读者已经看过主文件。

结语

CLAUDE.md不是写一次就完事的东西。它需要随着你的使用不断迭代，慢慢变成真正符合你工作习惯的配置。分层的思路能帮你保持主文件的精简，同时又不丢失需要的细节。希望这些经验对大家有帮助！

最后展示一下我的CLAUDE.md全文，可以用做模板参考。也要感谢大佬们介绍的gemini/codex mcp协作工作流，实际使用时真的帮助很大。

我的CLAUDE.md编写实践：从Claude Skills中学习分层架构思路