陆牙1. 为什么内容型知识库项目更需要一份CLAUDE.md
1.1 内容型知识库项目到底特殊在哪
先把这个概念说清楚。我在这里聊的"内容型知识库项目"，指的是以内容生产、组织、维护为核心工作的项目——典型形态包括技术文档站点、产品帮助中心、团队内部 Wiki、博客系统、课程笔记仓库等等。这类项目有一个共同特征：主要代码量不大，但 Markdown 文件、图片资源、frontmatter 元数据、目录结构、链接关系这些内容资产占了项目体量的绝大部分。
很多人会觉得，内容型项目代码少，CLAUDE.md 似乎没什么好写的。这个想法我一开始也有，实际做下来发现完全相反。纯代码项目里，Claude 可以通过读代码本身理解逻辑，但内容型项目里，文章与文章之间的关系、术语的使用边界、写作风格的统一要求、frontmatter 字段的语义，这些信息全部是"隐性知识"，代码里根本看不出来。
举个具体的例子。一个技术文档库里，"部署"这个词可能在不同文章里有三种用法：指产品本身的部署操作、指文档站点的构建部署、指某篇教程里示例服务的部署。如果 CLAUDE.md 里不写清楚术语边界，Claude 在帮你改文章、生成新文档时就会来回漂移，甚至把两个概念混着用。这种问题在纯代码项目里几乎不会出现，但在内容项目里极其常见。
再比如写作风格。内容型项目最怕的就是一半文章是"你"开头的教程口吻，另一半是"用户"开头的产品说明口吻，读起来像两个不同的人写的。人工团队可以用审校流程来控制，AI 参与内容生产时，你必须在 CLAUDE.md 里把语气规范写死，否则每次生成都会自由发挥。
所以我这篇想分享的，是给这类项目写 CLAUDE.md 的完整思路和实操过程。这是这个系列的第 2 篇，上一篇我们把知识库的目录骨架和整体信息架构搭好了，这一篇集中解决"如何让 AI 协作符合这个知识库的规矩"的问题。
1.2 CLAUDE.md 在这个场景里解决了什么问题
CLAUDE.md 本质上是给 Claude Code 这类终端 AI 编程工具看的项目说明书。它写在仓库里，Claude 每次在这个项目里工作时会自动读取，相当于给 AI 一个"当前项目的上下文快照"。
在内容型知识库场景下，它解决的痛点非常具体。首当其冲的是上下文断层：知识库项目动辄几百个 Markdown 文件，每次会话都不可能把所有内容塞进上下文里，Claude 需要一份"地图"告诉它项目里有什么、各目录干什么用、写新内容应该遵循什么格式。没有这份地图，AI 就只能靠猜，猜出来的东西大概率和你既有内容的风格、结构不一致。
其次是无形的规范传递。人工编辑看一眼已有的两篇文章就能模仿风格，但 AI 不行。它需要你把语气、标题层级、frontmatter 字段、链接写法、图片存放规则一条条写清楚。CLAUDE.md 就是承担这个信息传递的载体。
还有一个很容易被忽略的价值：CLAUDE.md 对项目成员同样有用。它相当于把散落在团队脑子里的约定固化成了文档。新成员看一遍就知道怎么写文章、怎么起文件名、怎么跑构建命令。等于一份配置文件兼任了团队知识库的"入口文档"。
一句话总结：内容型项目的 CLAUDE.md，核心不是告诉 AI"代码怎么编译"，而是告诉它"内容怎么生产、怎么组织、怎么维护"。理解了这一点，后面所有的结构设计和内容编写都有方向了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 动笔之前：先想清楚 CLAUDE.md 的结构和边界
2.1 一份能落地的 CLAUDE.md 该包含哪些模块
直接抄作业的话，我在内容型项目里常用的 CLAUDE.md 结构是这样八个模块：
| 模块 | 作用 | 优先级 |
|---|---|---|
| 项目概览 | 一句话说明项目是什么、定位是什么 | 必写 |
| 常用命令 | 启动、构建、预览、检查命令 | 必写 |
| 目录结构 | 各目录的职责和内容类型 | 必写 |
| 内容写作规范 | 语气、句式、术语、标题风格 | 必写 |
| frontmatter 约定 | 字段定义、取值规则 | 必写 |
| 文件与链接管理 | 命名规则、图片存放、链接写法 | 强烈建议 |
| 典型工作流 | 新增文章、批量修改、发布前检查 | 强烈建议 |
| 常见禁忌 | 明令禁止的操作和表达 | 建议 |
这个顺序不是随便排的。它的逻辑是"先让 AI 知道这是什么，再告诉它怎么做，最后告诉它什么不能做"。项目概览在最前面，是因为 Claude 读取 CLAUDE.md 时是顺序理解的，先建立整体认知，后面的具体规则才有着落点。
内容写作规范那一块我要多说一句。很多人写 CLAUDE.md 会漏掉它，或者在代码项目里完全不需要它，但内容型项目里它恰恰是最核心的部分。你可以把这一节理解成"给 AI 看的编辑部手册"——它决定了 AI 生成内容是像你团队的人写的，还是像一段机器人文案。
2.2 内容项目与纯代码项目的编写差异
我在写这份 CLAUDE.md 之前做过一个纯 Node.js 项目的配置文件，两相对照，差异比我想象中大得多。
纯代码项目的 CLAUDE.md，重点通常是构建命令、测试命令、架构说明、代码风格、依赖管理约定。这些信息大多可以从代码里推断出来，CLAUDE.md 更多是起到"快速校准"的作用。而内容型项目的 CLAUDE.md，写的很多东西是代码里完全没有的：语气规范、术语表、frontmatter 语义、文档间的层级关系。
举一个很实际的差异。代码项目里你写"变量命名用 camelCase"，AI 完全能执行，因为语法规则是明确的。但内容项目里写"文章语气要专业且亲切"，这就不是一个能直接执行的要求——"专业"和"亲切"都是模糊词。你必须给例子、给句式模板、给推荐的开头写法，AI 才知道具体要什么。
所以我的结论是：内容型项目的 CLAUDE.md 不能只写规则，还必须带示例。每一条抽象规范后面都跟着一个"正确示例"和"错误示例"，双管齐下。这一点我会在后面的实战编写里展示具体写法。
另外，内容项目的 CLAUDE.md 需要定期跟随内容演进做版本更新。代码项目里模块结构相对稳定，但知识库的内容主题、文章分类会不断增长和调整。我第一次写好的目录结构说明，三个月后就有一半需要更新了。建议把"CLAUDE.md 与目录结构同步维护"写进自己的例行清单里。
2.3 文件放哪、怎么生效：根目录与子目录的策略
CLAUDE.md 的生效机制值得先说清楚。根目录的 CLAUDE.md 对整个项目生效，子目录里如果再放一份 CLAUDE.md，那么 Claude 在这个子目录范围内工作时，子目录文件的优先级更高。这个机制对内容型知识库项目特别有用，因为知识库天然是分板块的。
我在实际项目里用到了层级拆分。根目录放一份全局 CLAUDE.md，写所有板块通用的规则（通用写作规范、构建命令、术语表）；然后在两个内容密集的子目录里各放了一份更细的 CLAUDE.md，比如"API 参考"目录下规定函数文档必须包含参数表、返回值说明、示例代码三段式，"最佳实践"目录下规定每篇文章必须有背景、方案对比、结论三个部分。
这样拆的好处是避免一份文件过于臃肿。如果所有板块的特殊规则都堆在根目录那份里，文件会越来越长，Claude 每次读取都要消耗大量上下文。把通用的留在上层、特殊的分散到底层，既保证了信息的完整，又控制了单次读取的体量。
还有一个实操细节：CLAUDE.md 里可以通过 @路径 引用其他文档，也可以用 # 相对路径 的方式导入其他 Markdown 文件。如果你有非常详细的术语表或写作规范，不一定要全塞进 CLAUDE.md 本身，可以在里面用引用的方式指过去。我建议把超过 30 行的细节性内容单独放文件，CLAUDE.md 里只留要点和引用链接，这样结构更清爽。
3. 实战编写：从零写出一份可用的 CLAUDE.md
3.1 项目概览与术语表怎么写
项目概览要短、要准。我的写法是四句话以内交代清楚：项目做什么、内容主要面向谁、技术栈是什么、最核心的内容板块有哪些。第一版我写得太啰嗦，列了十几条背景信息，实际效果很差，AI 抓不住重点。后来压缩成三句话，效率反而高了。
下面是我在内容型知识库项目里用的概览模板，可以直接参考：
markdown复制# 项目概览
这是一个面向开发者的技术知识库项目，使用 VitePress 构建，内容以 Markdown 文档为主。
项目覆盖以下板块：快速上手、API 参考、最佳实践、故障排查、版本迁移。
内容目标是帮助用户在 5 分钟内找到问题对应的解决方案。
注意"内容目标"那一句。这句话看起来不起眼，但它是后面很多规则的总纲。比如 Claude 在生成文章时如果犹豫该往深了写还是往浅了写，"5 分钟找到方案"这个定位会引导它做取舍。
术语表是我的血泪教训换来的。以前没写术语表，Claude 生成的文章里"知识库"有时候指代我们这个文档站点本身，有时候指代用户自己搭建的业务知识库，读者经常被绕晕。后来我在 CLAUDE.md 里单独开了一节术语表，把高频且容易混淆的词全部罗列清楚：
markdown复制# 术语表
- 知识库：特指本项目（技术文档站点），不用于指代用户业务。
- 项目：除非特别说明，均指该知识库项目本身。
- 应用/服务：指用户通过文档学习后要部署的产品。
- 模块：指应用中相对独立的可插拔功能单元。
术语表的价值在于，它给 AI 建立了一个"语义锚点"。后续写任何内容时，遇到这些词就按这里的规定用。我也建议术语表条目不超过 20 条，只收录真正高频、真正容易混淆的，否则 AI 记不住，维护成本也高。
3.2 内容写作规范与语气设定的实操写法
这是整份 CLAUDE.md 里我最用心写的一节，也是实测下来效果提升最明显的一节。
我写到语气时一开始只写了一句话："使用专业、简洁、友好的语气。"结果 AI 生成的初稿要么太正式像官方公告，要么太随意像聊天记录。后来我把规范拆成了可执行的三层：语气倾向、句式习惯、具体示例。
语气倾向可以这样写：
markdown复制# 写作规范
## 语气
- 整体语气：专业、直接、克制，不用夸张形容词，不写"非常简单""强烈推荐"这类无信息量的表述。
- 称呼读者：使用"你"，避免使用"用户"或"使用者"作为主称呼。
- 禁止出现"请注意""值得注意的是"这类无意义的提醒开头。
句式习惯这个点是从编辑朋友那里学来的。中文技术文档最容易写得啰嗦的地方是"冗余的前置铺垫"。我在 CLAUDE.md 里直接给规则：
markdown复制## 句式
- 每段开头第一句话必须是本段的核心结论。
- 因果、转折关系的句子不超过一行半。
- 优先使用主动语态，如"系统会生成日志"，避免"日志会被系统生成"。
- 一段文字只讲一个主题，超过 6 行必须拆分。
示例部分我建议做成表格式的对照，AI 对这种"对的 vs 错的"比对格式理解得最快：
| 场景 | 正确 | 错误 |
|---|---|---|
| 描述操作 | 打开配置文件，修改 port 字段。 |
我们需要先将配置文件打开，然后对 port 字段进行一个修改的处理。 |
| 说明限制 | 免费版最多创建 3 个项目。 | 请注意，免费版在项目创建数量方面存在一定限制。 |
| 开头引言 | 本文介绍如何部署应用。 | 在当今的技术环境中，应用部署是一个非常重要的课题…… |
最后我在写作规范里加了一条硬性原则：所有新生成的文章，必须先在项目里找一篇同板块已有的文章作为风格参照。这条规则对 AI 特别有效，因为模仿比抽象理解风格要简单得多。引导词可以写成"参照 docs/best-practices/ 目录下已有文章的层级结构和段落长度"。
3.3 目录结构、命名规则与 frontmatter 约定
内容项目的命脉就是组织和元数据。Claude 要能在庞大的目录树里找对位置、生成符合格式的文章，这两块必须写得非常明确。
目录结构部分我直接列出真实的目录树，并在每个关键目录后面附上注释：
markdown复制# 目录结构
docs/
├── guide/ # 快速上手与概念说明，给第一次接触产品的用户
├── api/ # API 参考，按模块分子目录，每个模块一份 index.md
├── best-practices/ # 最佳实践，每篇解决一个具体场景问题
├── troubleshooting/ # 故障排查，标题统一用"问题现象"命名
└── migration/ # 版本迁移指南，按版本号命名
注意每个目录后面的用途说明，我会刻意写清楚"给谁看"。这能帮 AI 判断新文章应该放哪个目录。比如 AI 要生成一篇关于"部署失败"的文章，看到 troubleshooting 目录的定位后，就能正确归位。
命名规则往往是新人最容易踩坑的地方。我在项目里定的规则是：文件名全部小写，用短横线连接；概念性文档用主题词命名（如 deployment-overview.md），操作手册用动作开头命名（如 deploy-from-source.md）。这个约定写进 CLAUDE.md 之后，AI 新生成的文件名基本不需要人工改名了。
frontmatter 约定我用了表格来写，因为字段多、取值规则多，表格最清晰：
markdown复制# frontmatter 约定
每篇文档顶部必须有 YAML frontmatter，字段如下：
- title: 文档标题，不超过 20 个汉字
- description: 一句话概述内容，用于 SEO 和列表页展示，不超过 50 个汉字
- tags: 2~5 个标签，使用小写短横线格式
- date: 日期，格式 YYYY-MM-DD，仅在首发时添加
- updated: 最近更新日期，内容有实质修改时更新
同时我会加一条规则：修改现有文章时，不得擅自删除原有 frontmatter 字段，只允许调整 updated 和 description。这条限制防止 AI 在批量修改时把别人精心维护的元数据弄丢了。
3.4 构建、校验与发布命令
命令这一节看似简单，但有一个常见问题：命令写得不够全。很多人只写"构建命令"和"启动命令"，但内容型项目里真正高频的是内容检查类命令。
我在 CLAUDE.md 里把命令分成三组。第一组是本地操作：npm run docs:dev 启动本地预览、npm run docs:build 构建生产版本。第二组是内容校验：npm run check:links 检查文档内外部链接是否失效、npm run check:spelling 检查拼写。第三组是发布相关：npm run deploy 发布到服务器、npm run preview 预览构建产物。
第三组容易被忽略，但对内容项目来说很关键。链接检查尤其重要——知识库里的文档互相引用非常多，改个文件名就可能造成几十个死链。有了 check:links 这个命令，AI 在改完一批文档后会提示我跑一遍检查。
我在命令这一节还会补充一条"顺序约定"：
markdown复制# 命令
- 所有命令在项目根目录执行。
- 修改内容后，提交前必须运行 `npm run check:links`。
- 如果命令报错，不要忽略，先排查报错信息再继续。
这条约定看起来像废话，实际上非常有用。AI 在长时间任务中有时会忘记中间的检查步骤，写死顺序能把它的工作流拉回到轨道上。
3.5 典型工作流与验收标准
CLAUDE.md 里最好包含几个"端到端工作流"的描述，因为用户的很多需求其实只有几类。比如我在项目里写了三个典型场景：新增一篇文档、批量更新文档中的某个术语、重命名一个文档文件并修复所有引用。
拿新增文档举例，工作流写清楚总比让 AI 即兴发挥好：
markdown复制## 新增文档
1. 根据内容主题确定文档所属板块目录，先查看该目录下是否有相同主题的文档。
2. 新建文件，文件名遵循命名规则，放在对应目录。
3. 编写 frontmatter，字段参考 frontmatter 约定。
4. 文章结构遵循该板块的模板（api 目录的文档必须包含参数表、返回值、示例）。
5. 在文末补充相关链接（相关文档、参考文档）。
6. 在 docs/.vitepress/config.mjs 的侧边栏配置中登记新文档。
第六步是最容易漏的。很多内容生成工具会把文档写出来，但忘了登记到站点配置，导致 URL 访问不到。把这一步写进工作流，能让 AI 在完成任务时把"文档被站点收录"作为完成标准之一。
验收标准我单独列了一小节。内容是：任务完成后，AI 要自查五项——文件路径是否正确、frontmatter 是否完整、链接是否可访问、语气是否符合规范、是否已登记到侧边栏。这五个检查项我在每次对话结尾都会让 AI 过一遍，实践证明能拦截掉大部分低级错误。
4. 迭代过程中踩过的坑与排查技巧
4.1 子目录规则覆盖根目录规则时要注意什么
层级配置用起来爽，但踩坑也踩得莫名其妙。我有一次在根目录 CLAUDE.md 里规定了文章标题层级必须从二级标题开始，但 api/ 子目录的 CLAUDE.md 里写的是"函数文档说明部分的标题用三级标题"，结果 AI 在生成 API 文档时把整篇文档的标题都降了一级，正文结构乱了。
排查下来发现是优先级导致的。子目录文件里的规则优先级更高，AI 会在处理子目录任务时更倾向遵循子目录的规则，哪怕这条规则本意只是局部适用。这其实指出了层级拆分时需要立的一条规矩：子目录 CLAUDE.md 里只写与根目录规则不冲突的"补充规则"，如果确实需要覆盖根目录的某条规则，必须在子目录文件里明说"本节覆盖根目录的 XX 规则，适用于本目录内的全部文档"。
我自己后来习惯是在根目录 CLAUDE.md 末尾加一段提示："子目录另有约定的，以子目录为准，但子目录未覆盖的规则仍然适用。"这样写能帮 AI 建立更全面的规则认知框架。
4.2 一次性塞太多规则导致上下文浪费
这个坑是我写过第二版之后发现的。当时我把写作规范写到了四十多条，包括标点符号用法、数字写法、中英文混排空格规则等等每一条都写得非常细。结果 AI 每次会话光处理 CLAUDE.md 就要消耗大量上下文，留给真正内容的预算反而少了，任务的响应质量明显下降。
后来我做了"瘦身手术"，把四十多条砍到十五条以内，保留下来的都是有明确实际价值的：语气方向、开头写法、段落长度、示例格式、术语使用。像标点符号这种 AI 本身处理得差不多的内容直接删掉，中英文混排空格规则挪到了一篇单独的 style-guide.md 里，通过 # style-guide.md 的引用方式按需加载。
这个经验我建议所有写 CLAUDE.md 的人都记下来：配置文件不是越长越好，而是要控制"基础加载量"。核心规则控制在 15 条以内，细节放子文件按需引入，这是我在内容和效率之间找到的平衡点。
4.3 怎样判断一份 CLAUDE.md 写得好不好
判断标准不需要多复杂，我在实操中就看三点。
第一，让 AI 生成一篇全新文章，看它是否需要大量人工修正。如果生成的初稿能直接进入审校环节，说明 CLAUDE.md 有效；如果从结构到语气都要大改，优先怀疑是 CLAUDE.md 写得不够明确，而不是 AI 能力问题。
第二，看 AI 在不同时间、不同会话里生成的文章是否保持一致的风格和结构。内容型项目最怕风格漂移，如果两份同板块的文章读起来风格差异大，大概率是 CLAUDE.md 的规则还有模糊地带。
第三，看 AI 是否能自主完成"查漏"工作。比如你让它修改某个文章的标题，它有没有主动更新侧边栏配置、有没有检查引用该文章的链接。如果这些辅助动作经常漏，说明 CLAUDE.md 里的工作流没有写清楚完成标准。
我还发现一个小技巧：每个季度把 CLAUDE.md 完整重读一遍，对照最近三个月 AI 生成内容的实际表现，找出那些"写了很多但没被遵循"或者"没写但经常出问题"的地方，针对性地增删修改。配置文件是活物，需要持续维护，不是写完就能一劳永逸的。
5. 几个我总结出的进阶技巧
5.1 在 CLAUDE.md 里埋"反例"比只写"正例"更有效
前面提到过示例对照表，这里我想展开讲一下"反例"的独特价值。我在实际测试中有一个很深的感受：AI 对"不要做什么"的记忆往往比"应该做什么"更深刻。比如我写"不要用'非常简单'这类夸大的形容词"之后，新生成的文章里基本看不到这个词了；但只写"使用专业克制的语气"的时候，它还是会时不时滑向夸大。
所以我现在写每条关键规则时，都会配合一条明确的反例。并且反例最好贴近真实场景，比如 "像'仅需三步即可完成部署，极其方便'这种表述是不允许的，应改写为'部署需要三个步骤'"。这种具体的对比能让 AI 在生成时形成更清晰的边界。
5.2 按任务类型把 CLAUDE.md 分段写成"可检索的索引"
内容型项目里，AI 的使用场景无非那么几类：写新内容、改旧内容、整理目录、检查链接、生成摘要。我后来把 CLAUDE.md 按这些任务类型组织了段落，每段开头用很直白的短句标明适用范围，比如"适用于新增文档时""适用于修改已有文档时"。
这样写的好处是 Claude 能更快定位到与当前任务相关的章节，而不是把整个文档一刀切地全部应用。如果你发现 AI 在某个任务里规则响应得不准，可以先检查是不是 CLAUDE.md 里的相关规则写在了不合适的段落里。
5.3 为 AI 预留"提问规则"
最后一招是在 CLAUDE.md 里显式约定：如果任务要求不明确，AI 应该先提问澄清关键信息，而不是自行假设。尤其内容项目中，新文档的读者对象、篇幅、放置的板块如果没有明确，AI 擅自决定经常会跑偏。
我的写法是加一条规则："新增文档时，如果用户没有明确指定文档所属分类和目标读者，先列出 2~3 个候选分类让用户选择，再进行内容编写。"这条规则帮我节省了大量返工时间，也避免了 AI 过度自信的毛病。
6. 写在最后的一些体会
从第一版只有五行的粗浅配置，到现在这份能覆盖内容生产全环节的 CLAUDE.md，中间迭代了很多次。我个人最大的体会是：CLAUDE.md 不是一个一次性的技术配置，它更像是内容团队的编辑手册，需要随着项目的成长持续打磨。
如果你正准备给内容型知识库项目写第一份 CLAUDE.md，我的建议是从小做起，先写项目概览、目录结构、写作规范和常用命令这四块基础内容，跑通一两个实际任务后，再根据暴露出来的问题逐步补充。不要一开始就追求大而全，因为你以为需要写的很多规则，可能实际项目中根本用不到；而真正影响内容质量的隐性规范，只有在实际生产中才会暴露出来。
另外分享一个小技巧：每一项规则被写进 CLAUDE.md 之前，先问自己一个问题——"如果 AI 没看到这条规则，生成的内容会不会出问题？"如果答案是"会"，才值得写；如果只是锦上添花，就优先砍掉。这样能让配置始终保持高信息密度。
内容型知识库项目的工作流里，人与 AI 的协作会越来越普遍，CLAUDE.md 就是双方对齐认知的那个接口。把这个接口打磨好，后续所有内容生产的效率和质量都能明显上一个台阶。