第 5 篇：让 Claude 少犯错，验证机制、测试策略与发布检查清单

本篇核心目标建立改完就验的协作习惯。掌握内容型知识库项目的三套检查清单设计方法学会自动化测试与手动验证的搭配策略以及如何把验证步骤嵌入 Claude 的工作流中。规则写了Claude 就一定遵守吗你按前四篇的方法搭了一套完整的规则体系——CLAUDE.md 主文件、6 份 docs/ 文档、frontmatter 规范、schema 定义、构建链路说明。这套体系已经比大多数项目强了。但你很快会发现一个现实规则再完善Claude 也会犯错。不是因为它不听话而是因为某些规则它确实看了但在具体执行时遗漏了某一步任务复杂时它专注于主逻辑忽略了边缘检查你的规则覆盖了 90% 的场景但这次刚好遇到了那 10%规则写的是不要做 X但 Claude 做了一个它没意识到等价于 X 的操作这是所有 AI 协作的常态。即使是人类开发者代码审查、单元测试、CI/CD 也不是因为不信任开发者而是因为人会犯错系统来兜底。所以你需要的不只是告诉 Claude 规则还需要改完之后有一套机制来确认它做对了。这就是验证机制的作用。内容型项目的验证和代码项目有什么不同在代码项目中验证的核心手段是自动化测试——单元测试、集成测试、E2E 测试。写一个函数跑一遍测试套件绿了就行。内容型知识库项目的验证要复杂得多原因有三第一很多问题不是代码报错而是数据不对。frontmatter 缺一个字段构建可能不报错——但列表页上这篇文章的摘要就是空的。category 拼错一个字构建也不报错——但这篇文章从分类页上消失了。这类问题自动化测试很难覆盖。第二看起来正常不等于真的正常。详情页能打开不代表搜索索引收录了这篇文章。列表页展示了这篇文章不代表分类聚合页也展示了。你需要检查多个页面、多个环节才能确认一次改动没有造成连锁问题。第三改动的影响范围不直观。改一行代码你大概知道影响哪几个函数。但改一篇内容的 category 字段你不一定能立刻想到它会影响分类聚合页的内容列表、侧边栏的分类计数、搜索索引中该文章的分类标记、可能存在的 RSS 分类过滤。这三个特点决定了内容型项目的验证策略不能照搬代码项目的做法。你需要的是自动化校验 手动检查清单的组合。三套检查清单这是本篇最核心的交付物。三套清单分别应对三种场景内容变更、结构变更、发布上线。清单一内容变更后检查清单触发场景新增一篇内容、修改一篇内容的正文或 frontmatter 字段、删除一篇内容。这是最高频的场景。每次内容层面的改动都应该走这套清单。## 内容变更后检查清单 ### 自动化检查如项目支持 - [ ] 运行 npm run content:validate校验 frontmatter 完整性 - [ ] 运行 npm run content:build确认内容索引生成正常 - [ ] 运行 npm run lint 和 npm run type-check如改动涉及代码 ### 手动检查 - [ ] 目标内容的详情页可正常打开 - [ ] 详情页的标题、摘要、日期显示正确 - [ ] 列表页中该内容出现且展示正常 - [ ] 分类聚合页中该内容出现在正确分类下 - [ ] 标签页中该内容出现在对应标签下如适用 - [ ] 搜索结果中可找到该内容如项目有搜索功能 ### 如果是修改已有内容 - [ ] slug 未被修改除非明确被要求 - [ ] category 和 tags 使用的是已有名称 - [ ] 未新增未定义的 frontmatter 字段 ### 如果是删除内容 - [ ] 确认无其他内容的 related_articles 引用了该 slug - [ ] 确认无页面硬编码了该内容的链接 - [ ] 构建后无 404 页面这套清单的设计逻辑先跑能自动化的再人工看不能自动化的。自动化解决结构对不对手动检查解决效果对不对。清单二结构变更后检查清单触发场景新增或修改 frontmatter 字段、修改内容解析逻辑、修改页面模板的数据消费方式、调整分类或标签体系、修改搜索索引生成逻辑。结构变更比内容变更影响范围大得多。一次结构变更可能影响所有内容文件的处理方式。## 结构变更后检查清单 ### 类型和定义 - [ ] 类型定义已同步更新如 types/content.ts - [ ] 新增/修改的字段在类型定义中有明确的类型标注 ### 解析和构建 - [ ] 内容解析函数正常工作 - [ ] 构建脚本正常执行npm run build 无报错 - [ ] 内容索引生成正常npm run content:build 无报错 - [ ] 搜索索引包含正确的字段 ### 页面消费 - [ ] 详情页正常渲染抽查 3 篇不同类型的内容 - [ ] 列表页正常展示 - [ ] 分类聚合页数据正确 - [ ] 标签聚合页数据正确 ### 兼容性 - [ ] 旧内容未因结构变更而失效 - [ ] 缺少新字段的旧内容有合理的默认值或降级处理 - [ ] draft 过滤逻辑仍然正常 ### 文档同步 - [ ] docs/data-schema.md 已更新 - [ ] docs/content-rules.md 已更新如涉及 frontmatter 变更 - [ ] docs/build-process.md 已更新如涉及构建逻辑变更这套清单的设计逻辑按影响链路逐层检查——类型定义 → 解析构建 → 页面消费 → 兼容性 → 文档同步。不放过任何一个环节。注意最后的文档同步部分。这一步很多人会忘——改了代码但没更新文档下次 Claude 读到的就是过期的规则。