doc-sync

doc-sync 是一项自动化文档管理工具，旨在 AI 辅助开发环境中强制执行上下文卫生 (context hygiene)。它维护一套双文件标准：CLAUDE.md 用于操作导航，README.md 用于存放架构性的隐性知识。通过扫描存储库，它能绘制目录结构、审核版本漂移，并将错误置放的架构性描述从导航文件中迁移至结构化文件中。这确保 AI 代理程序不会因过大的上下文窗口而过载，并通过自动加载索引，精准获取执行当前任务所需的信息。

• 对 CLAUDE.md 导航层级与 README.md 的覆盖范围进行全存储库级别的审核。

• 强制区分操作指令（如命令、构建步骤）与解释性架构知识。

• 自动化建立与同步表格索引，确保文件与子目录能被正确索引以供 AI 发现。

• 执行内容迁移，移除 CLAUDE.md 中过多的叙述并将其移动至 README.md，以维持高效的 Token 使用率。

• 验证索引完整性，识别缺失的文档，并校正已删除或移动文件导致的过时索引条目。

• 支持作用域执行，允许用户在存储库、特定目录或单一文件父目录层级触发文档同步。

• 专为使用 AI 代理程序进行长期代码库维护与技术债管理的软件工程师设计。

• 要求遵循 .claude 目录中定义的文件规范。

• 非常适合用于具有复杂目录结构、且担心 LLM 注意力漂移风险的项目。

• 自动排除生成的文档、供应商依赖项与 Git 内部文档，以防止索引污染。

• 遵循严谨的工作流程：探索、审核、内容迁移、索引更新与最终验证，确保文档状态干净且独立。

• 当代码库遵循即时上下文 (just-in-time context) 原则时运作效果最佳，通常将操作元数据控制在 200 个 Token 内，架构文档控制在 500 个 Token 内。