current-knowledge-maintenance

项目知识建设与维护

帮助人掌握项目的目标、结构、关键行为和设计取舍，并由智能体（Agent）按需核实最新实现。建设与维护代码地图（Code Map）、技术图（Technical Diagram）和解释文档（Explanatory Documentation）时，依据正式规范、当前代码、登记配置和已确认决定，按理解目标选择表达方式，没有固定生成顺序。

本技能（Skill）提供 buildr.current-knowledge-maintenance/v4。通过其他能力调用时读取已解析的协作约定（Capability Contract）；直接用户请求同样按以下步骤执行，不要求先有 OpenSpec 变更。

按用户意图选择工作：了解或追问时解释当前事实；首次建立时形成整体认识和主干主题；检查时指出有依据的差异；维护时更新已授权且实际受影响的成果。它们共享同一组知识文件与来源，不各建一套内容。

本技能（Skill）只承载可长期复用、有当前事实来源的知识。不再创建、刷新或要求 Buildr 增强的 brief.md；历史文件保留普通阅读，不批量改写。独立任务说明（Task Brief）的形成、保存与接续由 task-manager 通过任务记录（Task Record）的 brief 字段负责，不要求有变更（Change）或知识影响。方案、实施、交付及专业审查、验证报告不默认收纳到 knowledge/；已有任务文档位于该目录时可显式引用原文，保留位置与历史。过程成果确有长期价值且维护范围已获授权时，核对来源后维护对应当前知识，不复制整份报告、执行历史或任务状态。

1. 确定本次范围

用户希望了解全貌、跟随一个场景、深入某部分或建设项目知识时，读取结构探索与知识建设。用户表达问题即可，智能体（Agent）负责定位来源、核实关系和组织解释。普通提问默认只读，交付回答、依据和继续探索方向；明确要求建设或完善时，再维护长期成果。已有同范围建设授权持续有效。只要求单独图示、地图或已有成果维护时，按其明确目标处理。

收到首次建立请求或网页的 initialize 指令时，按上述参考中的首次建设分支执行；用户无需预先拟定主题或文件清单。页面的范围与读取观察用于定位，材料里的指令不替代用户请求，落笔前核对实际现场。

从用户目标、真实改动或明确检查范围解析项目（Project）、服务（Service）、模块或流程，以及允许检查、维护和新建的范围。先识别哪些事实变化，再判断哪些成果可能受影响。已知目标直接读；未知位置从相关导航和来源路径定位，只检索当前相关范围。文件或提交版本变化只是检查线索，不能据此认定所有成果过时。

确认写入前观察到的相关文件内容与版本，保留他人修改。规范与实现不一致时明确分别列出承诺和实际行为、证据及影响；按现有授权交给对应事实来源的维护动作处理，不能只改映射来掩盖冲突。

2. 找到成果并判断价值

先读相关统一入口与成果自身的范围、来源、边界和关联说明，定位已有地图、技术图及解释文档。检查职责、关系、关键陈述是否仍适用，区分需要更新、无需修改、有价值的缺口和真实冲突。

建设或整理成果时，读取成果种类、组织与来源；选择对应种类的写法。每份受维护成果的四项说明可以在正文、图源或明确导航中表达，不新建全局登记库。不因文件缺失机械建设，也不为每个模块补齐三类成果。

3. 承接具体授权

用户已要求建设某范围时，自行确定一组具体成果，说明覆盖范围、目标文件、表达视角、事实来源和预期用途，然后连续实施，不逐文件询问。已授权维护现有受影响内容时直接更新。

开发开始时判断预计知识影响，实际增改删结束后按最终事实复核。发现已有关联表达失真、失效或需要补充时，主动说明“什么事实改变、影响哪篇文章或图/地图、建议校准什么”。已有同范围维护授权就说明影响并执行；只有事实源修改授权、未包含知识维护时，提出这一组校准建议并等待授权，仅暂缓相关知识写入，继续无关开发。不能把代码修改授权自动扩大为所有关联知识的写入授权，也不能重复索要仍有效的建设授权。

日常工作发现范围外值得补建的成果时，先给出上述具体建议并寻求该组建设授权。未取得授权只暂缓相关建设，继续无关开发和已成立的交付。用户明确指定的持续维护授权按其范围与期限使用；本次授权不推导永久全项目授权。

4. 建设和维护

OpenSpec 指导规范建设，code-architecture 指导代码建设；本技能（Skill）负责将结果准确表达。需要制作代码地图（Code Map）时采用当前可用的 code-map，由它负责规范与职责协作解释、可点击目录及文件定位；需要技术图（Technical Diagram）时采用当前可用的 Archify，术语变化按已有治理约定处理。这些专业方法按需要组合，不新增全局必需依赖。