内容型知识库CLAUDE.md编写全攻略：让Claude Code更懂你的项目

1. 为什么内容型知识库项目需要CLAUDE.md

1.1 先搞清楚CLAUDE.md到底是什么

CLAUDE.md 是放在项目根目录下的一个 Markdown 文件，专为 Claude Code（Anthropic 的终端 AI 编程助手）提供项目级上下文。你可以把它理解为一份“项目说明书”：AI 每次进入项目时都会自动读取它，从而快速了解这个项目是干什么的、目录怎么组织、有哪些约定、哪些事情绝对不能做。

很多人一听到 CLAUDE.md 就说“这不就是给 AI 写文档吗”，这么理解没错，但格局小了。它不只是文档，而是一份“可执行的规范”。普通 README 是给人看的，CLAUDE.md 是给 AI 看的操作手册。两者面向的读者不同，写作思路自然也不一样。

这里要先澄清一个容易混淆的点：CLAUDE.md 和 .cursorrules、AGENTS.md 这类文件功能上有重合，但服务对象不同。.cursorrules 主要针对 Cursor 编辑器，AGENTS.md 是多个 AI 工具通用的规范格式，而 CLAUDE.md 是 Claude Code 的专属配置。如果你同时用多个 AI 工具，完全可以各写各的，或者以其中一份为核心，其他文件通过引用方式节省维护成本。我的习惯是：项目根目录放 CLAUDE.md 作为主文件，配合 .claude/ 目录下的辅助文件使用，信息不重复，维护也轻松。

1.2 内容型知识库和纯代码项目的差异在哪里

CLAUDE.md 的编写方式，很大程度上取决于项目类型。纯代码项目（比如一个后端服务、一个前端应用），更关注技术栈、接口定义、测试命令、部署流程；而内容型知识库项目，比如技术文档站、个人博客、产品帮助中心、API 文档仓库，核心资产是内容本身，代码通常只是构建工具。

这两类项目，AI 需要掌握的“规矩”完全不一样。

纯代码项目里，AI 最怕的是改坏逻辑；内容型项目里，AI 最怕的是搞乱内容结构、破坏元数据规范、写出风格不一致的文章。所以内容型知识库的 CLAUDE.md，重点不是告诉 AI“我们的框架是什么”，而是告诉它“我们的内容长什么样、怎么组织、怎么才算合格”。

举个实际例子：一个纯代码项目，CLAUDE.md 里写“使用 pnpm 安装依赖”“运行 pnpm test 执行测试”就够了；但一个知识库项目，你需要写清楚“文章放在哪个目录”“front matter 必须包含哪些字段”“文章标题用什么命名规则”“内部链接怎么写”“图片放哪里”。这些看似琐碎的规则，恰恰是 AI 能稳定产出内容的关键。

1.3 一份合格的 CLAUDE.md 长什么样

我经手过不少内容型项目的 CLAUDE.md，写得好和写得差，差距非常明显。写得差的典型表现是：只有两三句话，比如“这是一个知识库项目，使用 VitePress 构建，请遵守已有风格”。这种配置约等于没有配置，AI 进来后还是一头雾水。

一份能真正干活的内容型 CLAUDE.md，至少应该包含六块：

• 项目概览：项目定位、技术栈、目录结构
• 内容组织规范：文章存放位置、命名规则、目录层级
• 写作规范：风格、格式、术语、元数据
• 常用命令：本地预览、构建、发布
• 工作流定义：从选题到发布的标准流程
• 约束条件：不能动什么、必须遵守什么

这六块内容不是堆砌，而是有条理的。AI 读取时是顺序理解的，前面讲清楚背景，后面讲清楚规则，最后讲清楚边界。顺序乱了，AI 的理解也会乱。

2. 动手之前：三张清单帮你理清思路

2.1 第一张清单：项目现状盘点

在写 CLAUDE.md 之前，别急着动笔。我每次都会先花半小时把项目摸一遍，回答最基本的几个问题：

• 项目是什么类型的知识库？技术文档、个人博客、产品手册还是混合型？
• 内容用什么格式存储？Markdown、MDX、还是 AsciiDoc？
• 有没有使用框架？VitePress、Docusaurus、Hugo、MkDocs 还是直接用 Git 仓库管理？
• 内容是怎么组织的？按主题、按日期、按产品模块？
• 有没有现成的写作规范或模板文件？

这些问题的答案，直接决定 CLAUDE.md 的骨架。你可以在项目根目录执行一条命令，把顶层结构列出来：

bash复制find . -maxdepth 2 -type d | sort

看一眼输出，你就能快速判断出这个项目的目录组织逻辑。我见过不少人省掉这一步，结果 CLAUDE.md 里写着错误的目录名，AI 照着规范操作反而搞乱了项目。盘点这一步不亏。

2.2 第二张清单：读者画像

CLAUDE.md 的读者只有 AI 一个吗？不是。虽然它名义上是给 Claude Code 看的，但在团队协作场景下，人类成员也会读它。这个区别决定了写作语言的正式程度。

如果你一个人维护知识库，那 CLAUDE.md 可以写得随意些，像给自己做笔记一样。但如果是多人协作，这份文件就是团队共识的载体，写的时候要克制、准确，尽量避免模糊表述。

我在实际项目中的判断标准是：如果这份文件要参与代码评审（Pull Request Review），那么它必须达到“人类也能轻松读懂”的标准；如果只是个人项目，则优先保证“AI 能读懂”即可。两者的篇幅差距很大，前者可能需要更全面的规则和解释，后者可以精简、直接。

2.3 第三张清单：高频操作汇总

观察一下你平时最常让 AI 帮你做什么。内容型知识库项目里，高频任务通常是这几类：

• 根据某个主题新写一篇文章，并放入正确目录
• 为已有内容补充示例、修订错误
• 检查全文格式、修正 front matter 缺字段
• 批量更新内部链接、图片路径
• 自动生成文章索引、归档页面
• 翻译内容或调整文案语气

把高频任务列出来，你就知道 CLAUDE.md 的规则应该往哪个方向倾斜。比如我发现自己经常让 AI 做“检查 front matter 是否完整”，那我在规范里就专门加了一条“所有文章必须包含 title、description、date、tags 四个字段，missing 时补充，不确定的字段值宁可留空也不要猜测”。这个规则一写，后续的返工率明显下降。

3. 逐段编写：CLAUDE.md 的六大核心模块

3.1 项目概览：让 AI 三句话内理解项目

项目概览放在 CLAUDE.md 的最前面，作用是让 AI 在读取后续细节之前，先建立整体认知。不要写成长篇大论，三到五句话足矣。

一个比较通用的模板是：

markdown复制# 项目概览

本项目是一个以 Kubernetes 为主题的 **内容型知识库**，使用 VitePress 构建并部署为静态站点。
内容以 Markdown 格式存储在 `docs/` 目录下，按主题分为入门、实践、参考三大板块。
本仓库的目标读者是公司内部研发团队，内容要求：技术准确、语言简洁、可操作性强。

这段话虽然短，但信息密度很高。AI 读完之后，至少知道：项目类型（内容型知识库）、技术栈（VitePress）、内容位置（docs/）、内容分类（入门/实践/参考）、读者群体（内部研发团队）、写作要求（准确、简洁、可操作）。

我建议在项目概览里避免写“XX 系统”或“XX 平台是公司核心产品”这类空话，AI 用不上。把篇幅留给有区分度的内容。

3.2 目录结构与内容组织规范

目录结构是内容型知识库 CLAUDE.md 里最容易写废的模块。很多人把整个 tree 命令的输出原封不动粘进去，这属于典型的过度设计。AI 不需要了解每一个文件，它需要的是目录的“组织逻辑”。

正确的写法是描述规则，而不是罗列路径。举个例子：

markdown复制# 目录结构

- `docs/index.md`：站点首页，内容简短，只做导航
- `docs/guide/`：入门教程，按阅读顺序编号命名（01-xxx.md, 02-xxx.md）
- `docs/practice/`：实践案例，每个案例一个子目录，包含 README.md 和配套资源
- `docs/reference/`：参考手册，按组件或 API 命名，不编序号

写入新内容时，先判断属于哪个板块，再放入对应目录。拿不准时优先问用户，不要自行新建目录。

这里面有个关键的细节：我明确写了“拿不准时优先问用户，不要自行新建目录”。这是内容型项目的常见痛点——AI 为了完成任务，经常自作主张创建新目录，导致知识库结构越用越乱。CLAUDE.md 里加上这一条，能省掉后面大量整理成本。

3.3 内容写作规范与风格约束

这一部分是内容型知识库 CLAUDE.md 的重头戏。写多少都不嫌多，但前提是每一条都有实际约束力，而不是口号式表达。

我通常会把写作规范拆成几个小项：

格式与结构

• 每篇文章必须有明确的 H1 标题（与 front matter 的 title 保持一致）
• H2 作为主要章节，H3 为子章节，不要跳级
• 段落之间空一行，代码块标注语言类型
• 列表项使用 - 而不是 *，保持全仓库一致

风格与语气

• 使用简洁、专业的中文表达，避免口语化和夸张修辞
• 对技术名词的处理：首次出现时给出全称和缩写，如“Kubernetes（简称 K8s）”
• 不要使用第一人称描述技术决策，除非引用的原文确实是个人观点

内容关联规则

• 内部链接优先使用相对路径：[安装指南](../guide/01-intro.md)
• 禁止引用外链图片，图片统一放在同目录 images/ 下
• 新文章需要关联至少一个已有页面，避免出现孤立内容

这些规则不是凭空想出来的，很多是从实际返工中总结的。比如“H1 标题必须和 front matter 的 title 保持一致”，是因为我发现 AI 生成的文章经常标题和页面标题对不上，搜索引擎索引时会出问题。

3.4 常用命令与构建流程

内容型项目虽然以内容为主，但还是有几个高频命令需要写清楚。如果项目里没有自动化脚本，也要明说“项目没有构建脚本，只需要直接编辑 Markdown 文件”。

我以一个典型的 VitePress 知识库为例：

markdown复制# 常用命令

- 安装依赖：npm install
- 本地预览：npm run docs:dev（默认端口 5173）
- 构建站点：npm run docs:build
- 代码检查：npx markdownlint 'docs/**/*.md'

修改内容后，必须执行 markdownlint 检查，确认无格式错误后再提交。

写得多了你会发现，“构建流程”这个模块对 AI 来说，最关键的信息其实是两条：改完内容以后要不要运行检查、检查的命令是什么。剩下那些安装命令，AI 大多数时候都能根据 package.json 自己推断出来，写不写影响不大。

3.5 工作流定义：从选题到发布

如果你希望 AI 不只是“写一段内容”，而是能完整参与内容生产流程，那就需要在 CLAUDE.md 里定义工作流。

我习惯用一段文字加步骤列表来描述，比如：

markdown复制# 新增文章的标准流程

1. 明确文章主题和目标读者，输出标题和摘要，等待用户确认
2. 根据主题判断所属板块，放入对应目录
3. 创建 Markdown 文件，补齐 front matter 字段
4. 撰写正文，遵守本文件的写作规范
5. 检查内部链接、图片路径和代码块标注
6. 运行 markdownlint 检查格式，修复所有告警
7. 提交前列出变更摘要，等用户确认后执行 git commit

这套流程的核心是“每到一个关键节点，先和用户确认再继续”。AI 自动化程度太高，有时候反而坏事。让它在开始、结束这样的节点停下来确认，能有效降低返工概率。

3.6 约束条件与禁区

约束条件模块是 CLAUDE.md 的“安全带”，它告诉 AI 哪些事情绝不能做。针对内容型知识库，我整理过一份高频禁区清单：

• 不得删除或重命名已有文件，除非用户明确要求
• 不得擅自修改他人文章的核心观点，只可修正错别字和格式问题
• 不得自动生成 front matter 中不确定的字段值（如 date）
• 不得把多个相关主题合并成一个新页面，除非用户明确要求
• 不得在内容中插入未经确认的技术结论或数据

约束条件写得越具体越好。“不要乱改文件”这种说法太模糊，AI 不知道怎么执行；改成“不得删除或重命名已有文件，除非用户明确要求”之后，AI 的判断逻辑就清晰多了。

4. 内容型项目的专属配置技巧

4.1 Front Matter 元数据模板统一

内容型知识库项目里，front matter（Markdown 文件头部的 YAML 元数据）是高频出问题的地方。AI 生成文章时，经常漏字段、写错标签，或者使用不一致的日期格式。

我建议在 CLAUDE.md 中直接放一个 front matter 模板，并明确字段规则：

yaml复制---
title: 文章标题（必填）
description: 一句话描述，控制在 100 字以内（必填）
date: 发布日期，格式 YYYY-MM-DD（必填，不确定时问用户）
tags:
  - 标签1（必填，至少一个）
draft: false (可选，草稿状态为 true 时不发布)
---

为了确保规则执行到位，可以再补一句说明：“如果原文没有 front matter，需要新建时，全部字段按模板补全；不确定的字段值先问用户，不要猜测。”

这个模板写进去之后，AI 产出的文章质量会稳定很多。因为 front matter 不仅影响页面显示，还影响检索、归档和 RSS 生成，缺一个字段整个站点可能就出 bug。

4.2 内容关联与链接维护规则

知识库项目最怕内容孤立。一篇文章写完之后谁也不链接它，它也不链接别人，时间一长就会变成信息孤岛。

CLAUDE.md 里应该明确链接维护的规则。我的建议是写入两条：

• 新文章必须包含至少一个指向站内其他页面的链接，同时建议检查是否需要在已有相关页面中加入指向新文章的链接
• 当文章标题变更导致链接失效时，需要同步搜索站内所有引用该标题的链接并更新

第二条尤其重要。内容型项目重构标题是家常便饭，但很多人在改完标题后没有同步更新链接，导致站内出现大量 404。如果 CLAUDE.md 里规定 AI 在检测到标题变更时自动更新引用，这些问题就能在源头避免。

4.3 多语言与国际化处理

如果你的知识库要支持多语言（中英双语、或者简繁共存），这部分配置更要写细。我维护过的一个知识库就踩过坑：AI 生成新文章时只写了中文，英文目录结构里缺了对应文件，导致导航栏出现空链接。

多语言项目的 CLAUDE.md 里，至少要明确：

• 内容按语言存放在不同目录：docs/zh/、docs/en/
• 新增文章时，需要判断是否同步创建其他语言版本；如果不创建，要在原文章 front matter 中标注 untranslated: true 标记
• 翻译时保留原文代码块和链接，只翻译叙述性文字

这些规则能让 AI 在多语言场景下表现得像熟悉项目的老成员，而不是每次都要你提醒。

4.4 与 Git 工作流的配合

内容型知识库通常也用 Git 管理，但它的提交习惯和纯代码项目不同。纯代码项目讲究提交粒度细、信息规范，内容型项目更需要关注的是“提交前是否做了格式检查”、“是否误提交了构建产物”、“文件移动是否符合目录规则”。

CLAUDE.md 中建议加入类似这样的约定：

markdown复制# Git 提交约定

- 提交信息格式：`docs: 新增 Kubernetes 入门教程（#12）`，类型用 docs，如果修改了构建配置则用 build
- 提交前运行 markdownlint 检查
- 不要提交 `node_modules/`、`dist/`、`.vitepress/dist/` 等构建产物
- 一次提交只处理一个主题，不要把文章新增和无关的配置修改混在一个提交里

这些约定帮助 AI 在执行 git 操作时保持规范性，减少人工审核负担。

5. 调试与迭代：让 CLAUDE.md 真正生效

5.1 静态检查：写完之后先过一遍审

CLAUDE.md 写完不等于万事大吉。我建议做一次静态检查，重点看三件事：

第一，信息是否一致。比如目录结构部分写了“docs/guide/ 目录下按编号命名”，但示例文件名写的是 intro.md，这就产生了矛盾。AI 读到互相冲突的规则，往往会自己挑一条执行，最后结果难以预料。

第二，表述是否有歧义。“内容要简洁”这种话就是典型的歧义表达，AI 无法判断“简洁”到底是多简洁。改成“正文段落控制在 2 到 5 句，单句不超过 40 字”才算有约束力。

第三，是否遗漏了高频场景。翻一下你最近两周让 AI 做的事，如果有些任务在 CLAUDE.md 里完全没覆盖到，说明规范还不够全。比如你经常让 AI 生成文章摘要，但规范里没写摘要的字数要求，AI 就会自由发挥。

5.2 动态测试：用小任务验证效果

静态检查通过后，真正有效的验证方式是派几个小任务给 Claude Code，观察它的表现。这个方法类似程序员写单测：用几个典型场景去测 CLAUDE.md 是否真的被 AI 理解并执行了。

我常用的测试任务有三个：

• 任务一：“在 practice 目录下新建一篇文章，主题是《如何用 Helm 部署应用》，先给出标题和摘要，等确认后再继续。”重点看 AI 是否遵守了“等待确认”的流程。
• 任务二：“检查 docs 目录下所有文章的 front matter，列出缺字段的文件清单。”重点看 AI 是否理解字段规范。
• 任务三：“写一段 50 字左右的 description，用在这篇文章里。”重点看 AI 是否遵守字数限制。

如果测试结果不理想，不要急着改 CLAUDE.md 的措辞，先想想是规则没写清楚，还是 AI 漏读了某个部分。有时候把规则从“创建新文章时”改成“创建新文章或修改已有文章时”就能解决问题。

5.3 版本管理与更新节奏

CLAUDE.md 和其他代码文件一样，需要版本管理。我建议在文件开头加一个“最后更新”标注，这样你在检查时一眼就能看出这份规范是否过期。

markdown复制# 最后更新：2025-06-10
# 版本：v2.1

更新节奏上，不需要刻意追求频繁。我的习惯是：每次发现 AI 因为缺少规则而犯错时，当场补充一条；每两周快速过一遍全文件，删除已经不适用的条目。这样既不会让文件无限膨胀，也能保持规则与项目现状同步。

另外，CLAUDE.md 不需要紧跟框架版本升级而修改。比如 VitePress 从 1.x 升到 2.x，只要内容组织方式没变，这条规则就不用动。真正需要更新的是那些和项目实际操作强相关的部分，比如目录结构调整、命令变更、规范修订。

6. 内容型知识库项目的避坑经验

6.1 五个常见坑

第一个坑：把 CLAUDE.md 写成项目说明书。有人把 README 的内容复制过来，再加一句“请遵守项目文档”，这样的文件对 AI 帮助不大。CLAUDE.md 的核心是规则和流程，不是背景介绍。

第二个坑：规则来自“理想”，而不是“现状”。你写“所有文章必须有 3 个以上标签”，但仓库里一半文章都只有 1 个标签，AI 一执行就把所有文章都改了，改完 diff 大到你不想 review。初次编写时，规则要基于现状，理想规范可以写成“渐进目标”，分阶段执行。

第三个坑：规则之间互相冲突。前面说“日期格式为 YYYY-MM-DD”，后面又说“日期字段若缺失则自动使用文件名中的日期”，这就是冲突。AI 遇到冲突时，通常会取最后一条规则，但结果是不可控的。

第四个坑：只写了 CLAUDE.md，没有配套的本地配置。比如你没有配置 markdownlint，却在 CLAUDE.md 里要求 AI 运行 markdownlint，AI 执行时会报错。规范里提到的工具，项目里一定要真的存在。

第五个坑：文件太长，AI 抓不住重点。CLAUDE.md 不是越长越好，超过 500 行时建议拆分成多个文件，把细节规则放到 .claude/commands/ 或 CLAUDE.local.md 里，主文件只留核心约束。

6.2 排查思路：AI 不听话时怎么调

很多人的第一反应是“这个 AI 不好用”，但我发现大多数问题出在 CLAUDE.md 描述不清晰。这里分享一套自己用的排查思路：

先复现问题，确认 AI 在什么场景、什么指令下表现不符合预期。然后打开 CLAUDE.md，找到与该场景相关的规则，检查表述是否明确。如果规则里出现了“应该”“可以”“尽量”这类弹性词，AI 大概率会在执行时打折扣。最后，把弹性词改成硬性约束，并补充一句“除非用户明确同意，否则必须按此执行”。

举个例子，原来写“文章标题尽量使用动词开头”，AI 执行结果经常不稳定。改成“文章标题一律使用动词开头，疑问句除外”之后，效果就稳定多了。这个细节看起来很小，实际对一致性影响非常大。

6.3 进阶建议：把 CLAUDE.md 越用越顺手

最后说几个我自己实践下来很有效的进阶用法。

一个常用做法是配合 .claude/commands/ 目录，把高频任务做成命令模板。比如写一个 new-post.md 命令，里面包含新增文章的完整流程，AI 收到 /new-post 指令后会自动按流程执行。这样 CLAUDE.md 只需要定义规则，命令文件负责编排流程，各司其职。

另一个做法是让 CLAUDE.md 具备自我修复能力。我见过有人在 CLAUDE.md 里加了一条规则：“当用户反馈你的输出不符合预期时，先自查 CLAUDE.md 中是否有相关规则；如果没有，建议补充一条并说明理由。”这个做法把纠错过程变成了动态完善规范的过程，CLAUDE.md 会越用越贴合项目。

根据我个人经验，CLAUDE.md 真正发挥作用的时间点，往往是写完一周之后。一开始写的时候你觉得什么都在里面了，实际跑几个任务才发现不少没覆盖的地方。不要等，每次发现 AI 理解有偏差，就当场补一条规则，一次一条，慢慢迭代。我自己的知识库 CLAUDE.md 从 v1.0 到现在 v3.2，中间经历过方向性调整，这就是在持续使用中不断沉淀下来的结果。你的项目也值得这样的过程。