技术蓝图维护Skill：代码改了文档自动跟上，彻底告别文档漂移
- 一句话定位：这是一个在「修改现有系统」前后被自动调用的文档同步技能，核心使命是让蓝图文档（blueprints）与代码始终保持一致，防止文档漂移。
- 工作方式：改动前先搜索并阅读相关蓝图、记录现状；改动后重新阅读、逐项验证、写回更新，并删除过时内容。
- 四类变更全覆盖：新增功能、修改功能、移除功能、重构，每种变更都有对应的文档更新清单。
- 内置质量保障：文档债务分级（关键/高/中/低）、九项验证清单、钩子自动提醒与校验。
- 权限克制：仅开放读取、写入、编辑、搜索、全局搜索五类工具，且技能元数据标记为用户不可直接调用，由 AI 助手在工作流中自主使用。
1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 技能中文名 | 技术蓝图维护Skill（技能内名称为「蓝图维护」） |
| 技能英文名 | blueprints-maintenance |
| 技能ID | 13984 |
| 是否用户可调用 | 否（由 AI 助手在合适时机自动启用） |
| 允许工具 | 读取、写入、编辑、搜索、全局搜索 |
它解决什么问题
技能详情里把问题定义得非常直白——文档漂移，通常发生在四种情况下：
- 代码改了，但文档没改；
- 加了新功能，但没有记录；
- 功能已经弃用，文档里却还在写；
- 行为发生了变化，文档描述没有同步。
这四种情况会持续累积成「文档债务」，最终让蓝图文档从「可信参考」退化成「过期噪音」，新人不敢信、老人懒得看。
一键安装的思路与步骤
该技能的安装信息在技能详情中未给出具体命令与下载地址，因此下面按通用流程描述，具体命令、入口与版本要求以官方说明为准：
- 确认安装前提：你的 AI 编程助手需要支持「技能（Skill）」扩展机制，即能够加载带名称、描述、允许工具列表的技能包，并能识别技能ID。若不支持技能机制，则无法装载本技能。
- 找到安装入口：在技能市场、插件中心或技能管理面板中，用技能英文名
blueprints-maintenance或技能ID13984进行检索；也可直接用中文名「技术蓝图维护 / 蓝图维护」搜索。 - 执行安装：按面板提示完成安装与授权，注意确认技能申请的权限范围是否为「读取、写入、编辑、搜索、全局搜索」这五项。
- 验证是否生效：安装后在一个存在
blueprints/目录的项目里，让助手执行一次与现有系统相关的改动，观察它是否会在改代码前主动搜索并读取蓝图、在改完后重新读取并提示更新。若助手完全没有读取蓝图的行为，通常说明技能未加载成功，需检查技能是否启用、项目目录约定是否匹配。 - 建立目录约定：技能示例中使用
blueprints/作为蓝图存放路径，建议团队沿用该约定或在技能配置中统一路径，否则搜索会落空。
需要强调的是：由于该技能「用户可调用」为否，正常使用时不需要你手动敲命令调用，它更像一个随开发流程自动介入的「文档守护者」。
2. 该技能的主要功能和特点
- 改前读、改后更的双阶段校验：变更前搜索并阅读相关蓝图、评估概述/API/行为描述是否准确，并规划与代码同批次的文档更新；变更后重新阅读、逐项核对、写回最新内容。
- 按变更类型给出差异化更新路径：新增功能时扩写概述、补 API 文档、记录新行为、更新关联系统与文件清单；修改功能时改行为描述、修订签名、更新示例；移除功能时清 API、删行为段落、必要时保留「已移除」注释；重构时重点更新文件路径与架构、验证示例有效性，API 文档通常不动。
- 文档债务识别与优先级排序：通过「文件路径不存在」「函数在代码库中不存在」「行为与现实不符」「可见功能缺文档」四类迹象识别债务，并按关键（公共 API 文档错误）→ 高（核心系统未记录）→ 中（内部系统过时）→ 低（小错误）排序处理。
- 九项验证清单：概述是否匹配当前目的、公共 API 是否齐备、签名是否准确、示例能否执行、行为是否匹配实现、文件路径是否存在、是否残留已移除功能、相关系统链接是否有效、是否与其他蓝图重复。
- 自动化钩子提醒：技能内置的蓝图钩子会在
UserPromptSubmit阶段提醒你检查文档，在Stop阶段验证文档是否与变更匹配，把「靠自觉」变成「有提醒」。 - 反模式约束：明确禁止在蓝图里长期保留 TODO、复制即将变更的实现细节、记录外部库（应改为链接）、保留弃用功能文档「供参考」；要求立即删除过时内容、与代码原子化更新、交叉引用而非重复、示例保持最小但完整。
- 与普通工具的区别：普通文档工具解决的是「怎么写文档」，本技能解决的是「文档什么时候必须跟着代码一起改」——它把文档维护嵌进了变更流程本身，而不是事后补写。
3. 如何使用该技能？
由于该技能由助手自动调用，你的「使用」更多体现为配合它的流程。推荐按以下步骤操作：
步骤 1：变更前先让助手定位蓝图
技能会先做搜索，例如：
搜索("auth", 路径: "blueprints/", 输出模式: "匹配的文件")
你也可以主动要求：「改认证模块之前，先读一下 blueprints/authentication.md」。输出是匹配到的蓝图文件列表，用于确认影响范围。
步骤 2：阅读并记录现有文档现状
读取("blueprints/authentication.md")
此时重点回答三个问题：概述是否准确？API 文档是否完整？行为描述是否正确？把这三条结论记录下来，作为后续核对的基线。
步骤 3：把文档更新纳入本次变更计划
在动手改代码前，先列出「这次改动会导致蓝图哪几段失效」，例如「新增了 token 刷新接口，需要补一条 API 文档 + 更新行为描述中的过期时间说明」。
步骤 4：完成代码修改
按正常流程改代码，建议同一批次内完成文档修改。
步骤 5：重新阅读蓝图进行验证
读取("blueprints/authentication.md")
逐项对照：概述是否仍描述目的？所有公共 API 是否都已记录？行为描述是否准确？文件路径是否仍正确？
步骤 6：写回更新后的内容
写入("blueprints/authentication.md", 更新后的内容及前置内容)
技能要求写回时保留前置内容（frontmatter），不要因为重写把元信息弄丢。
步骤 7：清理过时内容
删除已废弃的 API 段落、失效的路径、错误的示例。技能对这一点态度很强硬——过时的文档会误导，必须立即删除，而不是「留着供参考」。
步骤 8：定期审计
技能建议定期用 /blueprints 命令重新生成蓝图，并移除孤立的蓝图文件；审查时可直接套用技能提供的验证清单：
## 验证清单
- [ ] 概述匹配当前目的
- [ ] 所有公共 API 已记录
- [ ] API 签名准确
- [ ] 示例执行正确
- [ ] 行为匹配实现
- [ ] 文件路径存在
- [ ] 没有记录已移除的功能
- [ ] 相关系统链接有效
- [ ] 没有与其他蓝图重复的内容
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 技术蓝图维护Skill（blueprints-maintenance） | 变更流程内的文档同步机制 | 改前读蓝图、改后验证更新、四类变更清单、文档债务分级、钩子提醒 | 需支持技能机制的 AI 编程助手；按技能ID或英文名安装，具体入口以官方说明为准；无需手动调用 | 已有 blueprints/ 蓝图体系的团队，尤其核心模块频繁变更时 |
优势：把文档维护嵌进开发动作里，有清单可核对、有钩子兜底；不足：依赖蓝图文档本身存在且质量过关，无蓝图则价值有限 |
| 手工维护 README / Confluence / Notion 文档 | 传统文档协作 | 自由撰写、多人协作、权限管理 | 零技术门槛，但完全依赖人的自觉 | 文档量小、变更频率低的项目 | 优势：灵活、可读性好；不足：极易漂移，没有任何机制保证「代码改了文档也改」 |
| 代码注释生成型文档工具（如 JSDoc、Sphinx 类） | 从源码注释自动生成 API 文档 | 抽取注释生成接口文档 | 需引入工具链、编写规范注释、配置构建流程 | 对外 API 稳定、注释规范度高的库 | 优势：自动化程度高、与代码强绑定；不足：只能覆盖 API 签名层面，架构说明、行为描述、使用示例、系统关联几乎无能为力 |
| 通用 AI 编程助手的临时对话 | 一次性问答式辅助 | 让 AI 帮你「顺手写个文档」 | 几乎零门槛 | 临时补文档、一次性说明 | 优势：即时、便宜；不足：无流程约束，不看历史蓝图、不做改后校验，容易生成与实现脱节的「漂亮废话」 |
5. 该技能的典型应用场景与实际体验情况
场景一：后端工程师修改认证模块
痛点是认证逻辑牵一发动全身，改完代码后常常忘记更新 blueprints/authentication.md，导致后续排查问题时被过期文档带偏。使用方式是改动前让助手搜索并读取认证蓝图，改动后重新读取核对 API 与行为描述，最后写回。实际体验：上手几乎零成本，因为不需要记命令，只要正常描述需求，助手就会先读文档；效果取决于蓝图本身写得细不细，如果原文档只有一句话概述，那么能「同步」的信息也有限。
场景二：接手遗留项目的开发者清理文档债务
痛点是文档里写着一堆代码库中早已不存在的函数和路径。使用方式是按技能给出的四类迹象（不存在的文件路径、不存在的函数、不匹配现实的行为、可见功能缺文档）逐一排查，再按关键→高→中→低排序处理。实际体验：这一步的收益最直观，尤其是先修「公共 API 文档错误」这类关键债务，团队信任度回升很快；注意不要一次性重写所有蓝图，按影响面推进更稳。
场景三：重构（行为不变但结构变了）
痛点是重构后目录结构、文件路径全变，文档里的指引全部失效。使用方式是按技能的「重构」路径处理：更新文件部分的路径、结构变化时更新架构说明、验证示例是否仍有效，API 文档通常无需改动。实际体验：这类变更最容易被误判为「不需要改文档」，而技能明确要求更新路径，能堵住一个高频漏洞。
场景四：功能下线与弃用
痛点是被移除的功能文档长期留在蓝图里「供参考」，反而误导新人。使用方式是按「移除功能」路径清除 API 文档与行为段落，范围缩小时更新概述，变更显著时保留「已移除/历史」注释。实际体验：这类清理动作技能态度很明确——立即删除过时内容，不做「历史归档式」妥协。
整体体验小结：上手难度低（自然语言驱动，无需学习新命令）；效果上限由蓝图质量决定；最重要的注意事项是必须建立并维持 blueprints/ 目录与文档约定，否则技能无从下手。
6. 该技能能为用户带来的价值
- 把「事后补文档」变成「同批次原子更新」：技能要求文档与代码在同一个提交里完成，直接消灭了「等有空再补」这个漂移起点。
- 降低排查成本：文档一旦可信，新人定位问题、老手回忆设计意图的时间都会显著缩短；反过来，一份过期的行为描述足以让人在错误方向上耗掉半天。
- 让文档维护有章可循：四类变更各有清单、九项验证逐条可打勾，把「文档写得好不好」这种主观判断，变成了可执行的检查动作。
- 文档债务可控：通过关键/高/中/低分级，团队不必一次性还清所有债，而是持续处理影响最大的部分，避免文档体系整体崩坏。
- 形成长期资产：蓝图新鲜度维持住之后，架构说明、API 文档、文件清单会沉淀为可复用的团队知识资产，而不是一次性的文档任务。
- 降低协作门槛：钩子在
UserPromptSubmit和Stop阶段的提醒与校验，让「记得改文档」不再依赖个人责任心。
7. 常见问题 FAQ
Q1：这个技能怎么安装？收费吗？
在支持技能机制的 AI 编程助手中，用技能英文名 blueprints-maintenance 或技能ID 13984 检索并安装即可，安装后需确认它已启用。具体安装入口、版本要求与是否收费，技能详情中未提供，请以官方说明为准。
Q2：我需要手动调用它吗？
不需要。该技能在元数据中标记为「用户可调用：否」，属于由 AI 助手在修改现有系统时自动启用的能力。你只需正常提出开发需求，助手会在改动前读取蓝图、改动后更新蓝图。另外技能提到可用 /blueprints 命令重新生成蓝图，可作为定期维护入口，具体可用性以你所用环境的官方说明为准。
Q3：它会不会乱改我的代码？
不会。技能允许的工具仅为读取、写入、编辑、搜索、全局搜索，其职责范围是蓝图文档的读取与更新。它的动作对象是 blueprints/ 下的文档，而非业务代码。
Q4：它和 JSDoc、Sphinx 这类自动生成文档的工具冲突吗？
不冲突，二者定位不同。自动生成类工具从源码注释抽取 API 签名，覆盖的是接口层；本技能处理的是概述、行为描述、使用示例、文件路径、关联系统等更「人话」的部分，并负责在变更时同步更新。实践中可以让注释生成工具管签名，让蓝图文档管设计与行为说明。
Q5：适合谁用？如果我的项目里没有 blueprints 目录还有意义吗？
最适合已经建立蓝图文档体系、且核心模块变更频繁的研发团队。如果你的项目还没有 blueprints/ 目录，建议先按该技能推荐的路径约定沉淀首批蓝图（至少覆盖核心系统与公共 API），再让技能介入日常维护；否则技能会「无蓝图可读」，价值无法体现。