技术蓝图维护Skill blueprints-maintenance

---

名称: 蓝图维护 用户可调用: false 描述: 在修改现有系统后使用，以更新蓝图文档。在更改前阅读蓝图，更改后更新。防止文档漂移。 允许工具: [读取, 写入, 编辑, 搜索, 全局搜索]

维护技术蓝图

同步问题

文档漂移发生在：

• 代码更改而未更新文档
• 添加新功能而未记录
• 已弃用的功能仍被记录
• 行为变更未反映在文档中

验证过程

在进行更改之前

1. 查找相关蓝图:

   # 搜索与您的系统相关的蓝图
   搜索("auth", 路径: "blueprints/", 输出模式: "匹配的文件")
   
   # 阅读蓝图以了解当前文档
   读取("blueprints/authentication.md")
   

2. 记录现有文档:

   • 概述准确吗？
   • API 文档完整吗？
   • 行为描述正确吗？

3. 规划文档更新与代码更改一起

在更改之后

1. 重新阅读蓝图以验证准确性:

   读取("blueprints/authentication.md")
   

2. 验证每个部分:

   • 概述是否仍描述目的？
   • 所有公共 API 是否已记录？
   • 行为描述是否准确？
   • 文件路径是否仍正确？

3. 更新蓝图:

   # 读取当前内容，根据需要修改，写回
   写入("blueprints/authentication.md", 更新后的内容及前置内容)
   

4. 删除过时内容 - 过时的文档会误导

更新类型

添加新功能

当添加功能时：

1. 更新概述，如果范围扩展
2. 添加新的 API 文档
3. 记录新行为
4. 更新相关系统，如果有新集成
5. 添加到文件部分，如果创建了新文件

修改现有功能

当更改行为时：

1. 更新行为描述
2. 如果签名更改，修订 API 文档
3. 如果使用方式更改，更新示例
4. 检查相关蓝图的影响

移除功能

当弃用或移除时：

1. 移除 API 文档
2. 从行为部分移除
3. 如果范围减少，更新概述
4. 如果变更显著，考虑保留“已移除”或“历史”注释

重构

当重构而不更改行为时：

1. 更新文件部分，使用新路径
2. 如果结构更改，更新架构
3. 验证示例是否仍有效
4. API 文档通常不变

文档债务

识别债务

蓝图需要关注的迹象：

• 不存在的文件路径
• 代码库中不存在的函数
• 不匹配现实的行为
• 可见功能缺少文档

减少债务

按影响优先处理：

1. 关键: 公共 API 文档错误
2. 高: 核心系统未记录
3. 中: 内部系统过时
4. 低: 小错误

验证清单

当审查蓝图时：

## 验证清单

- [ ] 概述匹配当前目的
- [ ] 所有公共 API 已记录
- [ ] API 签名准确
- [ ] 示例执行正确
- [ ] 行为匹配实现
- [ ] 文件路径存在
- [ ] 没有记录已移除的功能
- [ ] 相关系统链接有效
- [ ] 没有与其他蓝图重复的内容

保持蓝图新鲜

在开发期间

• 将文档视为功能的一部分
• 在同一个提交中更新蓝图
• 在代码审查中审查蓝图变更

定期维护

• 定期审计蓝图与代码
• 使用 /blueprints 命令重新生成
• 移除孤立的蓝图文件

工具支持

蓝图钩子自动：

• 提醒您检查文档 (UserPromptSubmit)
• 验证文档匹配变更 (Stop hook)

反模式

不要

• 在蓝图中永久保留 TODO 注释
• 复制将变更的实现细节
• 记录外部库 (改为链接)
• 保留弃用的功能文档 “供参考”

做

• 立即删除过时内容
• 与代码原子性更新
• 交叉引用而非重复
• 保持示例最小但完整