Claude Code 文档 Drift 检测系统是一套内置的自动化工作流，用于定期验证项目中的最佳实践报告（如 Settings、Commands 指南）是否与 Claude Code 官方文档保持同步。该系统通过并行启动专门的研究子代理（Subagent）对比官方源与本地文件，利用包含 30 余条规则的验证清单进行深度检查，并将发现的问题自动记录到版本历史中，从而实现对文档漂移的精准监控与持续更新。
Claude Code 文档 Drift 检测系统：自动化工作流追踪 Settings、Commands、Skills、Subagents 变化
在快速迭代的 Claude Code 生态中，官方文档（如设置项、命令列表、技能列表）会随着版本发布而更新。维护一份独立的最佳实践参考文档时，最大的挑战就是确保其内容与官方源保持同步，避免出现“文档漂移”。为了解决这个问题，Claude Code Best Practice 项目内建了一套名为 Drift 检测系统的自动化工作流。
这套系统并非单一工具，而是由多个针对不同文档维度的专用工作流组成。其核心目标是：自动化地发现并报告本地最佳实践文档与 Claude Code 官方文档之间的差异，确保项目作为从 Vibe Coding 到 Agentic Engineering 参考资源的准确性。
系统工作原理：五步工作流模式
尽管每个工作流的检查对象不同，但它们遵循一套通用且严谨的执行模式，可以概括为五个核心步骤：
- 并行研究启动：系统会同时启动两个独立的子代理（Subagent）进行研究。一个专用代理（如
workflow-claude-settings-agent）负责深入对比本地报告与官方文档；另一个通用代理（claude-code-guide）则独立调研最新的官方功能、变更和新增内容。并行执行提升了效率，而双代理的发现能相互印证与补充。 - 读取历史与验证清单：在等待代理结果的同时，系统会读取上一次的变更日志（
changelog.md）以了解历史问题，同时加载一份累积的验证清单（verification-checklist.md）。这份清单是系统的“回归测试套件”，包含多种深度（depth）的检查规则。 - 合并发现与执行验证：待两个代理返回结果后，系统会交叉对比它们的发现，标记矛盾之处。随后，严格依据验证清单中的每一条规则（如
field-level级别的完整性检查、content-match级别的内容比对）对发现进行二次验证，生成包含“验证日志”的详细报告。 - 追加变更日志与更新标记：报告生成后，系统会自动将本次检查的摘要条目（包含问题状态：
NEW、RECURRING、RESOLVED）追加到对应的changelog.md文件中，永不覆盖历史记录。紧接着，它会更新目标文档顶部的“最后更新”时间戳徽章，反映最新的检查时间。 - 提供执行选项：最后，系统将报告呈现给用户，并询问下一步操作：自动执行所有修复建议、选择性地执行部分建议，或仅保存报告而不做任何更改。
这套流程确保了文档同步工作的可追溯性（历史变更日志）、严谨性（验证清单）和灵活性（用户决策）。
核心工作流详解：以 Settings 报告为例
Settings 的 Drift 检测是该系统中最为复杂和全面的一个工作流，它能很好地展示整个系统的深度。其检查范围远不止简单的设置项增减。
检查维度：
- 设置键值：新增的设置、行为或默认值发生变更的设置、已弃用的设置。
- 权限语法：新的工具模式、通配符行为、权限模式的变化。
- 配置结构：MCP 服务器配置、沙盒（Sandbox）设置、插件设置、模型配置、显示与用户界面（UX）设置的变更。
- 环境变量：
env-可配置变量的完整性（注意：它会与负责startup-only变量的 CLI 启动标志指南 进行交叉验证，避免重复）。 - 文档内部一致性：报告中的示例（如快速参考 JSON）是否准确、所有超链接是否有效、设置层级（5 级覆盖链）描述是否正确。
- 版本元数据：报告头部的版本徽章和计数是否与实际内容匹配。
验证清单的威力：verification-checklist.md 中的 30 多条规则是这套系统的知识沉淀。每条规则都定义了检查内容、检查深度和比对来源。深度级别从基础的存在性检查 (exists) 到严格的内容逐字比对 (content-match)，再到跨文件一致性核对 (cross-file)，确保了检查的全面性。例如，规则 1F 专门检查报告中列出的设置键是否在官方文档中存在，防止出现“幽灵”条目。当新的漂移类型被发现，且现有规则未能捕获时，系统会自动向清单中追加新的规则。
覆盖全栈的其他工作流
除了 Settings，系统还为其他关键文档提供了专门的工作流：
- Commands 工作流：专注于追踪斜杠命令的 Frontmatter 字段和官方内置命令列表的增减。
- Skills 工作流：专注于追踪技能的 Frontmatter 字段和官方捆绑技能列表的增减。它特别区分了“捆绑”（随 Claude Code 发布）和“可安装”（来自外部仓库）技能。
- Subagents 工作流：专注于追踪子代理的 Frontmatter 字段和官方内置代理列表的增减。
- CONCEPTS 工作流：专注于维护项目根
README.md中的功能概念总览表，确保其中的链接、描述和徽章准确无误。
这些工作流共享相同的核心模式，但检查清单和报告模板针对各自领域进行了定制。
如何利用这套系统
对于项目维护者，可以定期运行这些工作流命令（如 /workflow-claude-settings），它们会输出一份清晰的漂移报告和优先级行动项，使文档更新工作变得有序且高效。
对于 Claude Code 用户，了解这套系统的存在意味着可以更信任该项目提供的参考指南。当你阅读 Settings 完整配置指南 时，可以确信其中的内容是经过自动化系统定期校验的，最大程度减少了过时信息带来的误导。这也体现了项目自身追求“结构化代理工程”的实践——用自动化工作流来维护自身知识库的准确性。
这套 Drift 检测系统本身，就是编排工作流的一个优秀实例，它将多个代理、工具和自动化步骤组合成一个可持续运行的可靠流程。
FAQ
Q: 这些工作流可以用于我自己的 Claude Code 文档或配置库吗？ A: 可以。这套工作流的架构是通用的。你可以参考其模式，为自己的项目创建类似的 Drift 检测工作流，用于监控自定义命令、技能或项目配置与官方源或内部规范的同步情况。
Q: 验证清单（verification-checklist.md）是静态不变的吗？ A: 不是。验证清单是“仅追加”的。当一次检查运行发现了一种新型的漂移，而现有规则未能捕获时，系统会自动为这种新情况添加一条新规则。这让清单能够随着 Claude Code 生态的演变而不断成长，变得越来越全面。
Q: 运行这些工作流需要什么权限？
A: 它们需要执行子代理、读写项目文件（如 changelog.md、源文档）以及访问外部网页（抓取官方文档）的权限。通常在 settings.json 中为这些命令配置了适当的权限模式。