第 3 篇：规则分层——用 docs/ 文档体系实现渐进披露

📌 本篇核心目标：学会把"一个膨胀的 CLAUDE.md"拆解为"一个精简的主文件 + 一套专项文档"，掌握 6 份 docs/ 文档各自的职责边界，以及如何让 Claude 按需加载而非全量灌入。

当你的 CLAUDE.md 开始变胖

如果你按照第 2 篇的方法写好了 CLAUDE.md，并且真的在项目中用了一段时间，你一定会遇到这个问题：

它开始膨胀了。

你用 # 补了几条新规则。某次 Claude 改错了构建脚本，你加了一段构建流程说明。分类体系调整过一次，你补了一段详细的分类规则。有人问你"内容文件的 frontmatter 到底有哪些字段"，你把完整的字段清单也塞了进去。

两个月后，你的 CLAUDE.md 从最初的 50 条信息膨胀到了 150 条。

然后你发现一个尴尬的情况：Claude 开始选择性忽略一些规则了。

不是因为它"叛逆"，而是因为——回忆第 1 篇讲的"指令预算"概念——当信息量超过阈值后，Claude 对所有规则的遵守力度都会均匀下降。你精心写的 slug 保护规则，和你顺手加的构建步骤说明，在 Claude 眼里没有明显的优先级差异。它们都被淹没在了一大堆文本里。

这不是 CLAUDE.md 的问题，而是你的信息架构出了问题。

解决方案不是"删掉一些规则"——那些规则可能确实重要。解决方案是换一种组织方式。

渐进披露：一个你应该学会的信息架构思路

"渐进披露"（Progressive Disclosure）不是一个新概念。它在产品设计中被广泛使用——

手机设置页面不会一次性把 200 个选项全部展开；它先给你 10 个大类，你点进去才看到子选项。

技术文档站不会把所有 API 堆在首页；它先给你一个导航，你根据当前任务找到对应的文档。

CLAUDE.md 也应该用同样的思路。

核心原则

主文件（CLAUDE.md）        只放核心、高频、长期有效的规则
    │
    │  "处理 XX 任务前，请查看 docs/XX.md"
    │
    ▼
专项文档（docs/*.md）       放某一类任务的完整规则和细节

CLAUDE.md 是入口，不是仓库。

它的作用是：

1. 承载 Claude 每次都需要知道的基础规则
2. 告诉 Claude "某类任务的详细规则在哪个文件"

当 Claude 遇到一个具体任务——比如"新增一个 frontmatter 字段"——它先从 CLAUDE.md 中知道"内容结构相关的规则在 docs/content-rules.md"，然后读取那份文档，获得完整的指导。

这样做的好处：

主文件保持精简。 信号密度高，Claude 不会因为信息过载而"选择性失忆"。

专项文档可以写得很详细。 因为它只在相关任务时被加载，不会占用无关任务的上下文空间。

不同任务获得不同深度的指导。 改一行正文和改整个数据结构，需要的规则量完全不同。

维护更容易。 内容规范变了，你只改 docs/content-rules.md，不用在 CLAUDE.md 里大段修改。

内容型知识库项目需要哪 6 份文档

不是每个项目都需要同一套文档。但对于内容型知识库项目，以下 6 份文档覆盖了最高频的协作场景：

docs/
├── content-rules.md      ← 内容文件怎么写、怎么命名、字段怎么用
├── data-schema.md        ← 有哪些数据实体、字段含义、实体关系
├── build-process.md      ← 内容怎么变成页面、构建链路是什么
├── testing.md            ← 改完东西后怎么验证
├── code-conventions.md   ← 项目特有的代码约定
└── deployment.md         ← 怎么发布、发布前后检查什么

下面逐一拆解每份文档的职责、应该写什么、不该写什么、以及它和 CLAUDE.md 的关系。

第 1 份：docs/content-rules.md

这份文档的核心使命

回答一个问题：在这个项目里，一篇"合格的"内容文件应该长什么样？

它管的是内容的"形式规范"——不是内容写什么（那是编辑的事），而是内容的文件结构、命名方式、字段规则、分类标签使用规则。

应该覆盖的核心内容

1. 文件命名规范

## File Naming Rules

- 文件名使用小写英文，单词间用中划线 `-`
- 文件名应反映内容主题，清晰可读
- 不使用空格、中文文件名或无意义缩写
- slug 应与文件名一致或直接映射

这几条看起来简单，但它们防住了一个常见问题：Claude 新增内容时用了不符合项目规范的文件名，导致后续排序、路由或检索出问题。

2. Frontmatter 完整定义

这是这份文档最重要的部分。在 CLAUDE.md 里你只写了一句"必须包含 title, slug, category, tags, date, draft"。但在 content-rules.md 里，你需要展开每个字段的含义和使用规则：

## Frontmatter Schema

### 基础字段（必填）
- `title`: 页面标题，用于详情页标题和列表展示
- `description`: 内容摘要，用于列表卡片和 SEO 描述
- `slug`: 唯一访问标识，决定页面 URL
- `category`: 主分类，用于导航和聚合页
- `tags`: 标签数组，用于检索和相关推荐
- `date`: 发布时间
- `draft`: 是否为草稿（true 时不进入正式发布流）

### 扩展字段（可选）
- `updated`: 更新时间
- `featured`: 是否推荐内容
- `order`: 排序权重
- `related_articles`: 相关内容 slug 数组

### 字段使用规则
- 扩展字段使用前需确认页面模板和构建脚本是否支持
- 不要为单篇内容发明新字段
- 新增字段前，先检查是否有现有字段可以复用

3. 分类和标签规则

## Category Rules

- category 表示主分类，每篇内容只属于一个 category
- 使用已有分类名称，当前项目分类包括：
  - 政策解读
  - 备考指南
  - 考情速递
  - 常见问题
- 新分类上线前需确认是否有对应聚合页和导航入口

## Tag Rules

- tags 用于检索和横向聚合
- 标签简洁明确，不超过 5 个
- 同义词只保留一个写法（如"教资"和"教师资格证"统一用"教师资格证"）

把分类名直接列出来，是这份文档最有价值的部分之一。Claude 看到明确的清单，就不会自己发明新分类名。

4. Slug 变更规则

## Slug Rules

- slug 必须唯一
- 已发布内容的 slug 不可修改
- 若必须修改，需同步检查：页面路由、列表聚合、搜索索引、内链引用、sitemap

5. 不同内容类型的模板建议

## Content Types

### Articles（文章）
适合：政策解读、考情分析、深度讲解
推荐正文结构：背景引入 → 核心内容 → 注意事项 → 总结

### FAQ（常见问题）
适合：高频短问答
推荐结构：问题 → 直接回答 → 补充说明

### Guides（指南）
适合：操作流程、备考路径
推荐结构：目标说明 → 分步骤讲解 → 注意事项

这份文档和 CLAUDE.md 的关系

CLAUDE.md 里关于内容的规则，只保留最核心的几条（frontmatter 必填、slug 不能改、分类一致性）。其他所有关于"内容文件怎么写"的细节，全部移到 content-rules.md。

Claude 在处理内容相关任务时，先从 CLAUDE.md 知道基本约束，再从 content-rules.md 获取完整指导。