维护技术蓝图
同步问题
当出现以下情况时，文档会与实现脱节：
代码变更但文档未更新
新增功能但未补充文档
已弃用功能仍留在文档中
行为变化未反映到文档
验证流程
改动之前
查找相关蓝图：
搜索与你的系统相关的蓝图
Grep("auth", path: "blueprints/", output_mode: "files_with_matches")
阅读蓝图以了解当前文档
Read("blueprints/authentication.md")
记录现有文档内容：
概述是否准确？
API 文档是否完整？
行为描述是否正确？
将文档更新计划与代码改动一并安排
改动之后
重新阅读蓝图以核对准确性：
Read("blueprints/authentication.md")
逐节核对：
概述是否仍描述其用途？
所有公开 API 是否都已记录？
行为描述是否准确？
文件路径是否仍然正确？
更新蓝图：
读取当前内容，按需修改，再写回
Write("blueprints/authentication.md", updated_content_with_frontmatter)
删除过时内容——过时文档会误导他人
更新类型
新增功能
添加功能时：
若范围扩大，更新概述
添加新的 API 文档
记录新行为
若有新集成，更新相关系统
若创建新文件，添加到文件章节
修改现有功能
改变行为时：
更新行为描述
若签名变化，修订 API 文档
若用法变化，更新示例
检查相关蓝图是否受影响
移除功能
弃用或移除时：
删除 API 文档
从行为章节中移除
若范围缩小，更新概述
若变更重大，可考虑保留“已移除”或“历史”说明
重构
在不改变行为的前提下调整结构时：
用新路径更新文件章节
若结构变化，更新架构说明
验证示例是否仍可用
API 文档通常无需改动
文档债务
识别债务
蓝图需要关注的迹象：
文件路径不存在
函数不在代码库中
行为与现实不符
可见功能缺少文档
偿还债务
按影响程度排序：
关键：公开 API 文档错误
高：核心系统缺少文档
中：内部系统文档过时
低：轻微不准确
验证清单
审查蓝图时：
验证清单
- [ ] 概述与当前用途一致
- [ ] 所有公开 API 均已记录
- [ ] API 签名准确
- [ ] 示例可正确执行
- [ ] 行为与实现一致
- [ ] 文件路径存在
- [ ] 未记录已移除的功能
- [ ] 相关系统链接有效
- [ ] 与其他蓝图无重复内容
保持蓝图常新
开发过程中
将文档视为功能的一部分
在同一提交中更新蓝图与代码
在代码审查中审查蓝图变更
定期维护
定期对照代码审计蓝图
使用 /blueprints 命令重新生成
删除孤立的蓝图文件
工具支持
blueprints 钩子会自动：
提醒你检查文档（UserPromptSubmit）
核对文档与改动是否一致（Stop 钩子）
反模式
不要
在蓝图中无限期保留 TODO 注释
复制会变化的实现细节
记录外部库（应改为链接）
以“供参考”为由保留已弃用功能的文档
要
立即删除过时内容
与代码原子化更新
交叉引用而非重复
保持示例精简但完整