summary

这个 skill 用来在需求、plan 和实现闭环后，把已经落地的业务行为沉淀到 docs/spec/。重点不是复述源码，而是帮助后续维护者理解最终规范：需求落成了什么行为、代码怎么支撑这个行为、改它会影响哪些契约，以及当前还有哪些真实边界。

适用场景

当用户要求根据某个需求、plan、diff、文件、tool、service、接口链路或模块实现生成 docs/spec/ 规范文档时，优先使用这个 skill。

当用户明确要求总结核心逻辑、详细代码逻辑、影响范围、当前边界、TODO 注释、文件名、方法名、行号，或把本轮实现沉淀到文档时，也使用这个 skill。

如果用户只是问一句代码做什么，可以直接简短回答，不需要生成完整规格文档。只有用户要求沉淀文档、写入 docs、生成总结、更新 spec、整理模块说明时，才进入完整流程。

非目标

这个 skill 只负责把已明确的需求、plan 和实现沉淀为规格文档，不负责顺手改业务代码，不负责重新设计方案，也不负责做完整 code review。

如果阅读过程中发现明显 bug、风险、实现与需求不一致、旧文档与当前实现冲突，需要在规格沉淀前客观指出。不要把不符合需求的实现强行写成新规范，也不要把规格文档写成问题清单或重构计划，除非用户明确要求。

工作流程

按下面顺序推进。这个流程的目的，是先确认规范文档应该落在哪里，再确认最终行为是什么，最后才写入文档。

用户输入 / 本轮 diff / 指定文件
        │
        ▼
读取需求、plan、实现入口或 git diff
        │
        ▼
读取 docs/spec/index.md 和相关子索引
        │
        ▼
读取目标模块已有规格文档
        │
        ▼
顺着 import、schema、type、service、prompt、controller、query 查直接依赖
        │
        ▼
判断更新旧文档、新建文档，还是先反馈冲突
        │
        ▼
写入 docs/spec，并同步更新索引
        │
        ▼
检查 git diff / git status，确认只产生预期文档变更

上下文读取口径

先确认可用上下文。优先读取用户提供的需求说明、plan 文档、实现文件或本轮 git diff。如果当前对话已经包含需求和 plan，可以直接使用；如果没有，就根据用户指定路径读取对应文档或代码。

再读取 docs/spec/index.md，确认目标业务域已有文档位置。目标目录存在子索引时，也要读取子索引，例如 AG-UI 相关内容要读取 docs/spec/ag-ui/index.md。

接着读取目标模块已有规格文档。目标是判断本次沉淀应该更新既有文档、新增独立文档，还是合并到更合适的主题里。不要在不了解既有 spec 的情况下只按代码路径新建文档。

然后读取用户指定的主文件或本轮实现 diff。不要只看文件名猜职责，也不要只根据已有记忆写总结。

读完主文件后，继续顺着 import、核心函数调用、schema、type、service、prompt、controller、query 方法查直接依赖。目标是把当前模块的真实执行链路看完整，但不要无限扩散到无关模块。

如果主文件只是入口层，要继续找到真正承载业务逻辑的 logic、service 或 query 文件。总结时需要讲清入口层做什么，核心业务层做什么，不能把入口层误写成全部逻辑。

遇到 schema、类型文件和 prompt 文件时，需要判断它们是否会影响入参、出参、调用方式、结构化输出、前端协议或展示口径。只要会影响，就应进入影响范围章节。

查 TODO 时要搜索主文件、直接依赖文件，以及当前模块目录下相关文件。搜索关键词至少覆盖 TODO、todo、FIXME、fixme、待办。没有查到就明确写没有发现，不要编造待办。

决策口径

遇到文档落点或冲突时，按这张表判断。表格比散文更适合给模型稳定执行，因为每一行都是一个清楚的输入条件和动作。

规格沉淀原则

规格文档沉淀的是最终行为，不是代码流水账。需求和 plan 里的业务目标要被转换成稳定口径，代码只作为这个口径的证据。

如果需求、plan、代码和旧 spec 之间出现冲突，不能默认以代码为准。先指出冲突点，说明哪一边缺少依据；只有用户明确当前实现符合需求时，才把当前实现沉淀为新规范。

如果旧 spec 已经过期，优先更新旧文档里的相关章节。不要绕开旧文档再写一份语义重叠的新文档，避免 docs/spec/ 里出现互相打架的规范。

如果目标模块还没有对应 spec，写入 docs 时需要补充新文档，并同步更新 docs/spec/index.md。如果目标目录有子索引，也要同步更新子索引。

文档结构

生成规格文档时，首要章节必须是核心逻辑。这个章节要先说明模块定位，再说明需求落成的最终行为，再说明主流程和关键设计取舍。写法要像给后续维护者交代规范，不要像在逐行翻译代码。

章节可以按下面的表格组织。能省略的章节只在缺少真实依据时省略，不要为了模板完整编内容。

推荐章节模板

文档可以按下面的顺序组织。

# 模块总结

## 核心逻辑

说明这个模块负责什么、需求最终落成了什么行为、输入是什么、输出是什么、主流程怎么走、核心设计是什么。

## 需求落地

如果有明确需求或 plan，说明关键需求点分别由哪些代码路径支撑。没有明确需求或 plan 时省略。

## 详细代码逻辑

按入口函数、权限或参数处理、核心编排函数、关键算法函数、输出组装的顺序写。每段都带文件名和行号。

## 影响范围

写改动当前模块会影响的 schema、type、prompt、调用方、查询层、业务聚合层、事件协议、前端协议、checkpoint、缓存和相关模块。

## 当前边界

写代码已经体现、后续维护容易误解的边界。没有明显边界时可以省略。

## TODO 注释归纳

写检查到的 TODO、FIXME、待办注释。没有时写清检查范围和结果。

详细写作要求

全文保持人类友好。句子要短，逻辑要顺，先讲结论，再讲细节。不要把源码大段贴进文档，除非用户明确要求源码示例。

代码引用要克制。优先引用文件路径、方法名和行号，不要贴大量源码。通常每个关键点引用一处行号就够了。

不要复杂化。不要为了显得完整而扩展无关历史、架构背景、理论解释或不在当前代码中的推测。

不要复读同一信息。核心逻辑讲过模块定位后，详细代码逻辑就只补执行顺序和关键函数，不要再重复同一段介绍。

写影响范围时要具体。应该写清楚某个 schema 会影响结构化输出校验，某个 type 会影响 TypeScript 类型契约，某个 prompt 会影响模型何时调用 tool，某个 query 会影响字段口径，某个事件会影响前端恢复或 replay。

写当前边界时要诚实。已经落地的边界就写清楚，没有依据的未来规划不要写进规范。

写 TODO 时要克制。TODO 是当前边界的补充，不是文档主角；没有就是没有，不要为了章节完整强行找问题。

行号要求

行号必须来自实际读取或搜索结果。不要凭印象写行号。

如果文件刚被编辑过，需要重新读取或搜索相关片段，确保行号没有过期。

如果行号密集，不要每一行都标。选关键方法定义、关键分支、关键调用、关键返回结构即可。

输出到文件时

总结文档默认存放在 docs/spec/* 下对应模块目录。先读取 docs/spec/index.md，再根据主文件所属业务域、需求所属业务域和调用链路找到最合适的模块文件夹。比如 MCP 课程相关内容放到 docs/spec/mcp/course，AG-UI 相关内容放到 docs/spec/ag-ui 或其子目录。总结同时涉及多个模块时，需要分别更新这些模块对应目录下的文档，不能只放到其中一个模块里造成上下文缺失。

文档命名要能直接看出主题。默认使用“业务名总结.md”或“业务名工具总结.md”这类中文名称，例如 课次详情工具总结.md。如果目标目录里已经存在同主题文档，优先更新已有文档，不要再创建一份内容重叠的新文档。只有主题确实独立，或者用户明确要求新建时，才创建新文件。

如果用户要求写入 docs 或指定路径，先查看目标目录已有文档命名和风格。新文档应尽量沿用相近命名和表达方式，但不要覆盖已有文件，除非用户明确要求覆盖。

写入前要确认目标文件是否已经存在。已存在时先读取内容，再决定是覆盖、追加还是更新。用户没有说覆盖时，优先更新同主题文档；没有同主题文档时才新建语义清楚的文件。

新增或迁移 docs/spec/ 文档后，必须同步更新 docs/spec/index.md。如果目标目录有自己的 index.md，也必须同步更新该子索引。

写入后检查 git diff 或 git status，确认只产生预期文档变更。如果发现工作区还有其他既有改动，只说明它们存在，不要擅自处理。

质量标准

一篇合格规格文档应该让读者不用打开源码，也能知道这个模块的最终行为、需求落地方式、主链路、关键算法、影响契约、当前边界和 TODO 状态。

一篇合格规格文档也应该让读者想继续排查时，能根据文档里的文件路径和行号快速跳到源码。

如果文档读起来像源码逐行翻译，说明还不够好。应该重新压缩成模块行为、数据流、关键约束和影响范围。

如果文档只写代码做了什么，却没有说明需求落成了什么稳定行为，也不算合格。应该补上需求口径、规格口径和影响契约。