[AI书房] 第8章 claude.md：编写智能体指令手册
Claude Code完全掌握
Claude Code完全掌握
第8章 claude.md：编写智能体指令手册
金京镇
引入
新招的员工第一天上班。推门走进办公室，没人带他熟悉环境，只丢下一句「干活」。洗手间在哪儿、主要客户的联系方式放在哪儿、公司的语气风格是什么，他一概不知，就这样开始写邮件了。写出来的东西，不离谱才怪。第一次在新项目里启动Claude Code，情形和这一模一样。
智能体打开文件夹，最先找的是一个文件：claude.md。如果这个文件不存在，智能体就跟那位没人带的新员工没有区别。
系统提示词的作用
如果你在n8n里搭过AI智能体，应该见过节点设置面板里那个填写系统提示词（System Prompt）的输入框。如果你在ChatGPT里创建过自定义GPT，应该有在「Instructions」标签页里写角色和规则的经历。claude.md扮演的就是同样的角色。
名字不同，本质相同。它是智能体在读取用户消息之前，必定先读的一份文档。
我们沿着运行顺序走一遍。用户向Claude Code发送一条消息。智能体在处理这条消息之前，先把项目根目录下的claude.md文件整个读进来。读完之后，才去看用户的消息，然后生成回复。这个顺序每次都一样。每次开启新对话、每次执行 /clear 之后，智能体都从claude.md读起。
含义很明确：写在claude.md里的内容，就是贯穿智能体全部行为的基准线。在里面写上「所有回复使用韩语」，智能体就用韩语回答。写上「创建Python脚本时必须包含错误处理」，智能体就不会漏掉try-except代码块。
[图8-1] 展示智能体处理消息顺序的流程图：读取claude.md → 确认用户消息 → 必要时浏览文件 → 生成回复]
应该写什么
claude.md里需要放的信息，大致分为三个层次。
是什么（What）：项目的身份。这个项目是做什么的、技术栈是什么、核心依赖包或技能有哪些，都要写清楚。看一个实际的例子：
# Executive Assistant You are the user's executive assistant. Your job is to help them spend less time on operations, people management, and admin, so they can focus on learning AI tools and making YouTube videos. This is their #1 priority. Everything else supports it.
就这么一段话，智能体的角色和用户的首要目标全交代了。
为什么（Why）：每个组成部分存在的目的。如果只写「tools文件夹里放着Python脚本」，智能体知道有这么个文件夹，但不知道为什么要先去看它。换成「收到新任务时先检查tools文件夹，里面可能已经有现成的工具」，智能体的行为就不一样了。
怎么做（How）：你期望智能体遵守的工作方式。比如「出现错误时，修改脚本之后，在工作流文档中补充该错误的应对方法」，这类行为规则就属于这一层。
不应该写什么
不要把全体团队成员的简历塞进去。不要把项目的全部会议纪要复制粘贴进去。不要把所有API端点的详细文档放进去。
原因在前面章节讲过的token。claude.md在每次对话开始时被整个读入。如果文件有500行，每次就有500行对应的token占据上下文窗口。为了回答一个问题，对话刚开始，上下文的很大一部分就已经被系统提示词吃掉了。
规则很简洁：claude.md里只放智能体每次都需要知道的内容。偶尔才需要的信息，放到单独的文件里，在claude.md中标注那个文件的位置就好。
150到200行原则
那么claude.md的合适长度是多少？
实战中验证过的基准是150行到200行之间。在这个范围内，项目身份、核心规则、文件位置指引全都装得下。有一个真实案例：智能体助理项目刚搭建完时，claude.md大约87行。随着项目变大，技能和工具不断加入，参考文件越来越多，行数自然向150行靠拢。
一旦超过200行，就要警惕了。到了那个节点，claude.md里一定有些内容，面对「真的需要每次都读吗」这个问题时，答案是「不需要」。那些内容应该拆到单独的文件里。
随着时间推移，项目会加入新技能、新参考文档，规则也会越分越细。claude.md自然跟着膨胀。这时候需要的是路由策略。
路由策略：从claude.md指向其他文件
打开智能体助理项目的claude.md，中间部分能看到这样一段内容：
## Quick Reference - About Me → read context/me.md - Business details → read context/work.md - Team info → read context/team.md - Current focus → read context/current-priorities.md - Project: Website Launch → read projects/website-launch/README.md - Project: West Coast Expansion → read projects/west-coast-expansion/README.md
这就是路由（Routing）。claude.md本身不包含「用户是谁」的详细信息，只有一句指引：「想了解用户信息，去读这个文件。」智能体只在用户的问题涉及个人信息时，才去读context/me.md。不相关就不读。
这样一来，每次固定消耗的token，只有claude.md里那几行简短的指引文字。
用数字来看路由的效果。把用户档案、业务信息、团队信息、优先事项、项目说明全塞进claude.md，很容易超过500行。用了路由之后，claude.md保持在100到150行的水平，智能体只在需要的时候才去加载对应文件。上下文窗口的剩余空间因此大幅增加。
下面是一些适合作为路由目标的文件示例：
[图8-2] 以claude.md为中心节点，me.md、work.md、team.md等为辐射节点的Hub-and-Spoke架构图]
项目成长时更新claude.md的习惯
claude.md不是写一次就完事的文档，它跟项目一起呼吸。
首次生成：/init 命令
如果现有项目里还没有claude.md，执行 /init 命令。智能体会扫描项目的文件夹结构和代码，自动生成一份claude.md草稿。不算完美，但比从空白文件起步快得多。浏览一遍草稿，补上缺失的规则，删掉多余的部分就行。
日常更新
添加了新技能或新工作流之后，直接告诉智能体就好。「我刚加了一个brand-assets文件夹。帮我更新claude.md，写上如果需要logo或品牌指南就去那个文件夹找。」智能体会打开claude.md，把相关内容加进去。这个习惯积累下来，claude.md就会变成一张准确反映项目当前状态的地图。
定期压缩
项目运行几周、几个月之后，claude.md里累积的条目开始突破200行。这时候可以这样跟智能体说：「claude.md有点长了。按照现在的实际情况整理一下，不再使用的工具和项目引用删掉，相似的规则合并起来。」智能体会分析文件并做出整理。检查一遍结果，确认无误后批准即可。
claude.md与.claude/目录的关系
项目根目录下，除了claude.md，有时还会出现一个名为.claude的隐藏目录。这个目录里存放的是沟通风格之类的细分规则文件。如果说claude.md是大框架层面的指引，.claude里的文件就是辅助性的细则。
项目根目录/ ├── CLAUDE.md ← 核心指引（150~200行） ├── .claude/ │ └── rules/ │ └── communication-style.md ← 细分风格规则 ├── context/ │ ├── me.md │ ├── work.md │ └── team.md ├── workflows/ ├── tools/ └── .env
[图8-3] 项目文件夹结构中claude.md、.claude/目录与context文件夹之间关系的树状结构示意图]
概括来说，claude.md就是智能体的岗位说明书。它定义角色，列明核心规则，标注详细信息所在的文件路径。篇幅控制在150到200行以内。项目变了，它也跟着更新。
我们已经整理好了智能体是谁、记住什么、遵循哪些规则。可是智能体再聪明，如果没有与外部世界交互的手段，能做的事终究有限。发邮件、抓取网页信息、往日历里添加日程，这些都需要给智能体装上「手」。
人工智能专家 金京镇 律师
AI法律政策专家 · 前国会议员 · 著有多部作品
如果这本书曾在您身边停留片刻，请支持我们，让下一个故事得以问世。
（自愿赞助账户：农协 302-1096-0948-81 户名：金京镇）