文档总会过期，让 AI 代理替你保持同步

📋 概述

作者描述的普遍场景：新人加入团队，打开仓库看到写得漂亮的 README 和架构文档，读几分钟就发现架构图和实现不符、文档引用的工具已经不存在、配置项变了、重要组件整个缺失。文档漂移的根源不是开发者不懂它的重要性，而是维护它是一件持续的事，很容易忘。他的方案基于一条原则：源码永远是唯一真相，文档只是它的可读表达。具体做法是给每份技术 Markdown 加上两行前置元数据——commit 记录最后一次对照审核的提交，updated 记录审核日期。这两行给了一个参照点：人一眼能看出文档落后代码库多远，代理则可以以那个提交为起点，检查此后所有变更是否影响文档。接着他描述了 sync-docs 这个代理技能的九步流程：找带元数据的文档、读出记录的提交、与 HEAD 比较、审阅期间变更、判断哪些影响该文档、核对当前实现、更新文档、刷新元数据、开 PR。关键点是代理不能把最近的 git 变更摘要往文档后面一贴了事，而要读懂现有文档、核对实现，再判断哪里需要改。