escapewu/project-docs-workflow

项目 docs 维护编排

这是一个薄编排层。

它不替代 AGENTS.md 的规则，也不替代 project-analysis 的深度分析。它负责把两者接起来。

目标

在代码实施前后，把项目文档工作流跑完整：

1. 开发前先找 docs/ 里的相关文档，同时扫描 tasks/ 中的活跃 taskBoard 获取当前执行上下文
2. 把文档当作半可信上下文，把 taskBoard 当作当前执行状态
3. 只在需要时升级到 project-analysis
4. 实施后判断哪些文档可能过时
5. 先询问用户，再决定是否 patch 文档
6. taskBoard 完成后，提炼结论更新 docs/（SSOT），taskBoard 移入 tasks/archive/

触发原则

遇到下面这些场景，应主动使用本技能：

• 用户要求实现功能、修改功能、开发新模块
• 用户要求修 bug，且 bug 涉及真实代码修改
• 用户要求重构、调整 API、调整数据流、调整调度逻辑
• 用户要求做跨模块代码修改

下面这些场景通常不要触发：

• 纯解释代码
• 纯搜索/调研，不修改代码
• 纯测试、纯文案、纯格式、小 typo
• 用户明确要求忽略 docs

标准流程

阶段 1：开发前扫描 docs 和 tasks

先检查：

• docs/OVERVIEW.md
• 可能相关的 docs/feature-*.md
• 可能相关的 docs/reference-*.md
• .agents/skills/harness/harness-engineering-plan/tasks/ — 当前活跃的 taskBoard（提供执行上下文，不是 SSOT）

优先用 Glob 找文件，再用 Read 读取候选文档。

匹配时重点看：

• 模块名
• 功能名
• API 名称
• 关键词
• 最近 changelog

如果找到相关文档：

• 在心里把它标成半可信上下文
• 用它帮助建立模块心智模型
• 但后续仍必须以当前代码核实，不能直接把文档当事实

如果没找到相关文档：

• 直接进入代码实施或定向分析
• 不需要因为缺文档而阻塞

阶段 2：判断是否需要升级到 project-analysis

只在下面情况升级：

• 涉及跨模块调用链
• 需要梳理架构 / 数据流 / 时序
• 现有 docs 明显过旧，且单靠读代码难以快速建立全局视图
• 用户明确在问“这个模块怎么工作”“是否有性能问题”“帮我梳理链路”这类问题

如果只是普通功能开发或局部 bug 修复：

• 不要默认调用 project-analysis
• 直接读相关代码和现有 docs 即可

如果升级到 project-analysis：

• 明确告诉它默认目标是写入文档，而不是停留在纯终端分析
• 优先判断当前结果应走 update-doc 还是 new-doc
• 若已有合适长期文档承接，优先 update-doc
• 若没有合适长期文档承接，再 new-doc
• 长期知识仍应优先回填 feature-* / reference-* / OVERVIEW.md
• 不要默认再造平行的长期文档体系

阶段 3：实施代码变更

代码实施阶段：

• 以当前代码为准
• 把 docs 作为背景，不把 docs 当真值源
• 如果实现中发现 docs 与代码冲突，以代码为准

阶段 4：实施后做 docs 影响判断

代码完成后，主动判断是否有 docs 影响。

重点判断这四类：

1. feature-xxx.md
   • 功能行为、架构、数据模型、API、测试方式是否变化
2. reference-xxx.md
   • 外部系统接入方式、限制、契约、参考结论是否变化
3. docs/OVERVIEW.md
   • 是否新增模块、模块边界是否变化、入口索引是否需要更新
4. AGENTS.md 的“历史教训”
   • 这次修复是否形成了新的稳定经验，值得追加一条编号记录

如果没有实质变化：

• 不要为了“形式完整”而改 docs

如果确认文档已过时、缺失或与实现不一致：

• 先询问用户是否要 patch 对应 docs
• 不要直接改

阶段 5：用户确认后 patch docs

如果用户确认 patch：

• 优先增量更新现有文档
• 保留仍然正确的部分
• 不默认整篇重写
• 功能级内容优先回填到 feature-xxx.md
• 外部参考优先回填到 reference-xxx.md
• 新模块补 docs/OVERVIEW.md
• 新踩坑补”历史教训”并编号递增

阶段 6：taskBoard 完成后蒸馏到 docs

当 tasks/<module>/taskBoard.md 所有 milestone gate 通过后：

1. 将 taskBoard 移入 tasks/archive/<module>/taskBoard-<phase>.md
2. 从 taskBoard 提炼稳定结论，更新 docs/feature/<module>/：
   • 新增/变更的数据模型 → data-model.md
   • 新增/变更的 API 契约 → docs/reference/interfaces.md
   • 设计决策与取舍 → README.md 或 design.md
3. 若模块无 docs/feature/<module>/ 目录，先建目录和 README
4. 同步更新 docs/feature/INDEX.md 的路由表

核心原则：taskBoard 是过程文件（WIP），docs 是事实来源（SSOT）。过程结束→蒸馏→更新事实。

文档落点规则

默认只维护这一套长期文档：

• docs/feature-*.md
• docs/reference-*.md
• docs/OVERVIEW.md

不要默认再造长期并行文档体系。

如果 project-analysis 产出了时序图、数据流图、性能观察：

• 优先判断是否能更新现有 feature-* / reference-* / OVERVIEW.md
• 能承接则走 update-doc
• 没有合适承接文档时，再走 new-doc
• 不再把 analysis-only 作为默认返回形态

输出给用户时要说明的事

在实施前，如果找到了相关 docs，可以简短说明：

• 找到了哪些相关文档
• 会把它们当半可信上下文

在实施后，如果发现 docs 可能过时，要明确指出：

• 哪份文档可能过时
• 为什么过时
• 是否建议 patch

执行提醒

• 本技能的目标是降低 docs 与代码脱节的概率，不是为了增加文档动作。
• 小改动不要强行引入 docs 流程。
• 真正需要时，再升级到 project-analysis。