docs-update

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会将旧版 Claude /skill-name 引用改写为 $skill-name。
• 任务跟踪要求：在执行任何工作流或技能步骤之前，先为所有步骤创建或更新任务跟踪，并随着进度变化保持同步。
• 用户问题提示表示应直接在 Codex 中询问用户。
• 出现 Claude 专属的模式切换指令时，请忽略。
• 严格执行约定：用户明确调用某项技能时，按原样执行该技能协议。
• 子 Agent 授权：当用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的激活即授权为该任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，明确执行每个列出的子技能步骤，并逐步报告证据。
• 如果所需步骤或工具在此环境中无法运行，请停止并询问用户，然后再调整方案。

Codex 项目参考资料加载（无钩子）

Codex 使用静态项目参考资料加载，而非运行时注入项目文档。 编码、规划、调试、测试或审查时，请根据此路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块以及工作流／测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录的路由）
• docs/project-reference/lessons.md（始终适用的防护措施和反模式）

上下文缺失或过时时的处理路径： 如果 docs/project-config.json、文档索引、lessons.md、CLAUDE.md、AGENTS.md 或任务所需的任何参考文档缺失或过时，请在常规项目工作之前自动运行 $project-init 或范围较窄的设置路径（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）。如果 Codex 镜像文件或 AGENTS.md 缺失或过时，请要求用户运行 $sync-codex；不要自动运行。

按情境查阅文档：

• 项目结构／架构／技术栈／部署／设置（任一层，包括后端、前端或基础设施）：project-structure-reference.md
• 后端／CQRS／API／领域／实体变更：backend-patterns-reference.md、domain-entities-reference.md
• 前端／UI／样式／设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 编写规范、docs/specs/ 路径或 TC 格式：feature-spec-reference.md、spec-system-reference.md、spec-principles.md
• 行为／公共契约变更或规范—测试—代码同步：workflow-spec-test-code-cycle-reference.md，以及上述规范文档
• 派生规范索引／ERD／重新实现指南：spec-system-reference.md 和 docs/specs/ 下的源 Feature Specs
• 集成测试实现／审查：integration-test-reference.md
• E2E 测试实现／审查：e2e-test-reference.md
• 代码审查／审计：code-review-rules.md，以及根据变更文件查阅的领域文档

不要盲目阅读所有文档。从 docs-index-reference.md 开始，然后只打开与任务相关的文件。

[BLOCKING] 按声明顺序执行技能步骤。未经用户明确批准，绝不跳过、重排或合并步骤。 [BLOCKING] 每个步骤或子技能调用之前，都要更新任务跟踪：步骤开始时设为 in_progress，结束时设为 completed。 [BLOCKING] 每个已完成／跳过的步骤都必须包含简短证据或明确的跳过原因。 [BLOCKING] 如果任务工具不可用，请创建并维护等效的逐步计划跟踪，并使用相同的状态转换。

快速摘要

目标： 检测代码变更影响到的文档，并协调更新所有文档类型，让每项代码／规范／测试变更都能确保文档同步——受影响的项目参考文档、project-config.json 章节、Feature Specs、§8 TCs、测试代码链接和派生索引都反映已发布的行为，不留下任何未发现的偏差。

摘要：

• 此技能是路由器，而非撰写者——从 Phase 0 分诊开始（git diff → 分类 → 模块去重 → 检查现有文档），并将各文档类型交给对应负责人（$spec、$spec [mode=tests]、$spec [mode=sync]、$spec-index、用于派生技术视图的 $tech-spec）；绝 NEVER 直接撰写 §8、docs/specs/ 或派生技术规范内容。原因：多人撰写会导致规范与索引／视图不一致。
• 主要步骤（每一步都以影响评估为准；跳过阶段时，需注明原因并标记为 completed）： Phase 0 分诊（git diff → 分类 → 模块去重 → 记录现有文档状态）→ Phase 1 项目上下文同步（影响映射 → 并行核验受影响的 docs/project-reference/** 文档、docs/project-config.json 章节和 README.md）→ Phase 2 $spec（§1–§7 Feature Spec；如果功能行为已变更但不存在 Spec，则阻止继续，先编写文档）→ Phase 2.5 $spec-index（可选：刷新派生的分组 INDEX／ERD）→ Phase 2.6 $tech-spec（可选：刷新／审查派生技术视图，仅在技术目录受影响时执行）→ Phase 3 $spec [mode=tests]（§8 TCs）→ Phase 4 $spec [mode=sync]（§8 ↔ 测试代码）→ Phase 5 摘要报告 → 最终审查（#8 执行 Step 2.4 代码 ↔ 规范同步验证）。
• 修改任何文件前，先通过任务跟踪创建全部 8 项任务；按固定阶段顺序 0 → 1 → 2 → 2.5/2.6 → 3 → 4 → 5 → final review 执行——快速退出是一个决策，绝不能默默省略步骤。
• 最终检查（Step 2.4）是工作流的最后一道关卡：逐个受影响的模块核验已发布代码与 §3 ACs、§4 BRs、§8 TCs 是否一致——移除／弱化的 [HARD] BR 会造成代码与规范矛盾，必须阻止流程完成。
• 输出使用与技术无关的文字（证据字段以外不得出现框架／产品名称），并优先保证可追溯性（先更新 FR-／BR-／OP-／TC- 逻辑 ID，再写说明文字）；必须始终编写 Phase 5 摘要报告，作为审计记录。

编排模型：

git diff → Triage → Phase 1: Project Context Sync (PARALLEL, impact-scoped)
                  │            ├─ impacted docs/project-reference/** — verify → patch → (escalate to $scan --target=X)
                  │            ├─ impacted docs/project-config.json sections — verify → merge → validate
                  │            └─ README.md / project docs (docs-manager)
                  → Phase 2: $spec (business feature docs)
                  → Phase 2.5: $spec-index (derived index/ERD refresh) [optional]
                  → Phase 2.6: $tech-spec (derived technical view refresh/audit) [optional]
                  → Phase 3: $spec [mode=tests] (§8 test specifications)
                  → Phase 4: $spec [mode=sync] (§8 ↔ test code sync)
                  → Phase 5: Summary Report

关键规则：

• 仅负责路由——绝不要重复子技能逻辑，也不要编写 Section 8 / docs/specs/ 内容
• [BLOCKING] 新鲜度按影响范围核验，绝不假定为新鲜。 Phase 1 只核验差异实际可能导致过时的 docs/project-reference/** 文档和 docs/project-config.json 部分（由 node .claude/scripts/doc-impact-map.cjs 路由），并为每份文档报告单独的判定结果 FRESH | PATCHED | RESCAN REQUIRED | UNVERIFIED。无人检查的文档为 UNVERIFIED——绝不是 FRESH。—原因：这些文档会注入所有下游 AI 上下文，因此一条悄然过时的内容会让之后的每个 Agent 都学到一个已不存在的代码库。
• **[BLOCKING] 按影响范围核验绝不会写入 。** 只有完整的 `$scan --target=X` 才能更新该时间戳；范围较窄的核验会改写为 ——且仅限已有 Last scanned 时间戳的文档（Step 1.6）。—原因：Last scanned 会触发 60 天完整重新扫描门限（.claude/hooks/lib/session-init-helpers.cjs:769）；从局部检查重置该时间戳，相当于通过禁用捕获整篇文档过时内容的防护网来换取速度。
• 已 PATCHED 的 docs/project-reference/** 文档在最终确定判定结果前，必须运行$prompt-enhance <doc>（Step 1.3）——让文档尽可能简洁，同时保留足够价值以供 AI 使用；仅在编辑时间戳/计数时可跳过。
• Phase 1/docs-manager 不得负责任何 docs/specs/**、测试规范、规范索引/ERD 或派生技术视图路径。
• 每项排除的制品都明确保留给对应的子技能（$spec、$spec-index 或 $tech-spec），确保每项制品只有一个权威写入者。
• 从所有 docs-manager 任务简述和写入范围中排除 docs/specs/** 和生成的技术视图。
• 每个阶段在调用前检查是否确有必要——无影响时跳过该阶段
• 步骤到技能的顺序固定——依次运行各阶段，绝不乱序
• 始终报告检查内容，即使无需更新任何内容也要报告
• 通过 $ARGUMENTS 向每个子技能传递分流上下文（变更文件、检测到的模块、受影响的章节）
• 必须留意模块列表去重——同一模块同时发生后端和前端变更时，只保留一项
• 必须实时跟踪步骤状态：in_progress -> 执行 -> completed（或标记 completed 并注明跳过原因）
• 对于 .claude 技能/钩子/工作流/同步工具的变更，标记生成镜像的同步状态（npm run codex:sync 已完成或明确标注 N/A）。docs-update 负责路由并报告此检查；不会直接编辑生成的镜像。
• [BLOCKING] 与技术无关的输出： 更新 spec/specs/README/INDEX 时，不要在正文或标题中引入框架/产品/语言/设计模式名称——保留证据字段例外（**Evidence**、CoveredBy、旧版 IntegrationTest、[Source:]、frontmatter、Mermaid）。依据：docs/project-reference/spec-principles.md §3。
• [BLOCKING] M3 可追溯性更新： 有关阻断条件，参阅 .claude/skills/shared/sdd-artifact-contract.md → “AI-SDD Mandates (M1-M7)”。代码变更后同步文档时，先更新逻辑 ID 映射（FR-/BR-/OP-/TC-），再更新正文。只有在逻辑制品被重命名/拆分时，才重新解析 [Source: namespace/service/id] 抽象锚点证据——文件移动或技术栈变更不会改变锚点（物理坐标仅保存在溯源 sidecar 中）——且逻辑 ID 主干在变更过程中保持稳定——绝不能仅因代码移动就删除或重新编号逻辑 ID。确保所有同步后的正文符合 M1/M2 要求。

保持审慎。运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，置信度须高于 80%。

---

必须创建任务（零容忍）

[BLOCKING] 在触碰任何文件之前，通过任务跟踪创建全部 8 项任务。绝不要合并、重命名或遗漏。跳过的条件性任务：立即标记为 completed 并说明原因——绝不能默默省略。 | # | 任务主题 | 是否有条件？ | | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | 1 | [docs-update] Phase 0 — Triage: collect git diff, categorize files, detect modules, check existing docs | 否 — 始终首先执行 | | 2 | [docs-update] Phase 1 — Project context sync: impact-map → PARALLEL verify of impacted docs/project-reference/** + docs/project-config.json sections + README/project docs | 否 — 始终执行，除非 Step 0.3 声明了 TRUE 快速退出（影响映射为空）。即使 Phase 2-4 全部跳过，也要运行 | | 3 | [docs-update] Phase 2 — Invoke $spec: update business feature docs | 是 — 服务端/前端文件已更改，且模块已有功能文档 | | 4 | [docs-update] Phase 2.5/2.6 — Refresh derived views via $spec-index and/or $tech-spec | 是 — 功能规格已更改，且对应目录维护 INDEX/ERD，或者技术树受到影响 | | 5 | [docs-update] Phase 3 — Invoke $spec [mode=tests]: update/add §8 business test specifications | 是 — 新增了业务可见功能，或者更改了现有业务可见行为 | | 6 | [docs-update] Phase 4 — Invoke $spec [mode=sync]: sync §8 ↔ test code | 是 — Phase 3 更改了 §8 测试用例 | | 7 | [docs-update] Phase 5 — Write summary report to plans/reports/docs-update-{YYMMDD}-{HHMM}.md | 否 — 始终执行 | | 8 | [docs-update] Final review — verify all impacted docs updated, no phases skipped without justification, AND run the Step 2.4 code↔spec sync-verify (AC/BR/TC drift) for every touched module | 否 — 始终执行 |

执行规则：

• 每项任务开始时标记为 in_progress，完成时标记为 completed——同一时间只能有一项任务处于进行中
• 涉及多个模块 → 在第 2/3 阶段的调用中为每个模块添加一项子任务
• 涉及多个参考文档 → 在任务 2 下为每份文档（或每个事实来源集群）添加一项子任务，以便分别跟踪每份文档的结论
• 绝不批量标记完成——分别跟踪每次子技能调用
• 第 0 阶段真正快速退出（影响映射为空）→ 将任务 2-8 标记为 completed，并注明原因“已跳过——影响映射为空”
• 第 0 阶段部分退出（文档/配置受影响，但业务行为未变——例如仅涉及测试框架、CI 或清单的变更）→ 执行任务 2，将任务 3-6 标记为 completed，并注明原因“已跳过——业务行为未变”，仍须执行任务 7-8
• 在对应任务状态为 in_progress 前，绝不执行阶段步骤
• 每次阶段/技能调用后，在任务更新中写入一行证据（运行了什么、变更了什么、为何跳过）
• 如果无法进行任务跟踪/更新，则维护一份状态转换相同的等效 8 项任务计划跟踪表

步骤-技能调用顺序（不得调整）

| 顺序 | 任务 ID | 步骤 / 阶段 | 技能调用 | 跟踪规则 | | ----- | ------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | 1 | 1 | 阶段 0：分诊 | 此技能中的内联分诊逻辑 | 在差异扫描前将任务 1 设为 in_progress；记录模块和影响范围图后将其设为 completed | | 2 | 2 | 阶段 1：项目上下文同步 | doc-impact-map.cjs + 并行运行 docs-manager 子代理（每个受影响文档 / 文档集群一个）+ 仅在升级处理时运行 $scan --target=X 或 $project-config | 在影响范围图绘制前将任务 2 设为 in_progress；只有所有已分派的文档和配置部分都包含判定结果及证据后，才将其设为 completed | | 3 | 3 | 阶段 2：业务功能文档 | $spec | 调用前将任务 3 设为 in_progress；审阅输出后将其设为 completed | | 4 | 4 | 阶段 2.5/2.6：衍生视图刷新 | $spec-index [mode=index] 和/或 $tech-spec [mode=generate | audit] | 调用前将任务 4 设为 in_progress；衍生输出刷新完毕或说明跳过原因后，将其设为 completed | | 5 | 5 | 阶段 3：§8 测试规格 | $spec [mode=tests] | 调用前将任务 5 设为 in_progress；审阅 TC 后将其设为 completed | | 6 | 6 | 阶段 4：§8 ↔ 测试代码同步 | $spec [mode=sync] | 调用前将任务 6 设为 in_progress；同步验证后将其设为 completed | | 7 | 7 | 阶段 5：总结报告 | 内联编写报告 | 编写报告前将任务 7 设为 in_progress；确认文件路径后将其设为 completed | | 8 | 8 | 最终审查 | 内联验证关卡 | 最终审计前将任务 8 设为 in_progress；所有阶段均有合理依据后将其设为 completed |

强制要求： 如果某个必需步骤无法执行，请停止并先询问用户，再调整顺序。绝不要继续执行未跟踪的步骤。

---

阶段 0：分诊 — 检测受影响的文档

步骤 0.1：收集变更文件

1. 运行 git diff --name-only HEAD（已暂存 + 未暂存的变更）
2. 没有未提交的变更 → git diff --name-only HEAD~1（上次提交）
3. 仍然为空 → git diff --name-only origin/develop...HEAD（分支变更）

步骤 0.2：变更分类

变更文件模式	影响类别	要运行的阶段
docs/project-config.json 中的 {backend-source-paths}/**	spec + spec [mode=tests] + 项目文档	1 + 2 + 3 + 4
{frontend-apps-dir}/**、{frontend-libs-dir}/{domain-lib}/**	spec + spec [mode=tests] + 项目文档	1 + 2 + 3 + 4
{legacy-frontend-dir}/**Client/**	spec + spec [mode=tests] + 项目文档	1 + 2 + 3 + 4
{configured-framework-source-paths}/**	仅项目文档	仅 1
docs/**（在 specRoots 之外）	仅项目文档	仅 1
.claude/**、.agents/**、.codex/**、CLAUDE.md、AGENTS.md	harness 清单 — 技能/钩子/Agent/工作流数量、目录、模块注册表	仅 1
依赖清单（package.json、*.csproj、pyproject.toml、锁文件等）	项目文档 — 技术栈、版本、运行命令	仅 1
基础设施/CI/环境（docker-compose*、Dockerfile、.github/workflows/**、*.tf、appsettings*、.env*）	项目文档 — 端口、部署、环境变量键	仅 1
{frontend-libs-dir}/{framework-core-lib}/**、{frontend-libs-dir}/{common-lib}/**	仅项目文档	仅 1

此表对业务文档影响进行分类（决定运行第 2–4 阶段中的哪些阶段）。分类刻意保持粗略。精确的 docs/project-reference/** + docs/project-config.json 路由由步骤 1.1 中的影响映射生成——请在那里查看，切勿在此猜测。

步骤 0.3：快速退出检查——根据影响映射决定，绝不凭路径直觉判断

现在运行影响映射（使用与步骤 1.1 相同的命令），并从输出中读取 fastExit：

node .claude/scripts/doc-impact-map.cjs --text

映射结果	流程
fastExit: true — 没有受影响的参考文档、没有受影响的配置部分，也没有 unrouted 文件	报告 "No documentation impacted by current changes." → 将任务 2-8 标记为 completed，原因填写 "Skipped — impact map empty" → 提前退出
文档/配置受影响，但业务行为没有变化（harness、CI、manifests、docs tree）	部分退出——完整运行阶段 1，将阶段 2-4 标记为 completed，原因填写 "Skipped — no business behavior changed"，然后继续阶段 5
任何业务/服务/前端代码发生变化	执行完整流程
unrouted 非空	不可快速退出——先手动分类每个未路由文件（将其加入波次，或记录其为何不会影响文档）

[BLOCKING] 仅涉及 .claude/**（或仅涉及工具）的差异并不意味着可以完全快速退出。 Harness 编辑会更改由 CLAUDE.md、docs-index-reference.md 和 project-structure-reference.md 通过 globbing .claude/ 得出的技能/钩子/Agent/工作流清单：即使没有任何功能影响，计数和目录也会过时，而且此技能中没有其他检查点能发现这些问题——阶段 2-4 只检查 docs/specs/\*\*。——原因：发布过时文档的最简单方式，就是将变更归类为“工具”，然后跳过唯一能发现问题的阶段。

步骤 0.4：自动检测受影响的模块

从变更路径中提取唯一模块名称。必须注意去重： 将其传递给任何子技能前先调用 unique()——后端和前端属于同一模块时，只保留一项。避免重复调用 $spec。

变更文件路径模式	检测到的模块
{backend-module-path}/{Module}/**	{Module}
{frontend-apps-dir}/{app-name}/**	{Module}（将应用映射到模块）
{frontend-libs-dir}/{domain-lib}/{configured-feature-path}/**	{Module}（将功能映射到模块）
{legacy-frontend-dir}/{Module}Client/**	{Module}

根据 docs/project-config.json 和项目参考文档构建项目专属映射，而不要使用硬编码的技能路径：

node -e "const cfg=require('./docs/project-config.json'); console.log(JSON.stringify({sourcePaths: cfg.codebaseHealth?.sourcePaths, contextGroups: cfg.contextGroups?.map(g => ({name:g.name,pathRegexes:g.pathRegexes})), specRoot: 'docs/specs/'}, null, 2))"
node -e "process.stdout.write('docs/specs/')"

步骤 0.5：检查每个模块的现有文档

对每个检测到的模块：

1. 检查 docs/specs/ 下是否存在对应的目录分组
2. 检查该目录分组是否包含 README.*.md 功能规格，或使用项目参考文档中的功能文档布局
3. 使用项目参考文档检查 docs/specs/ 下是否存在对应的目录分组
4. 记录：hasFeatureSpec（§1–§7 存在）、hasTestSpecs（§8 存在）、hasDerivedIndex（目录分组的 INDEX.md 存在）

步骤 0.6：声明文档更新波次

检测按顺序进行，且必须先完成——以下每项任务都由受影响文档集推导而来，因此在步骤 0.1–0.5 生成该集合之前，不得分派任何任务。该集合生成后，更新 N 篇互不相关的文档即可轻松并行：每篇文档或每个文档簇分配一个 docs-manager 子 Agent，并在同一条消息中一次性启动所有子 Agent。

1. 分派前先声明——Parallel plan: wave 1 = [docs-manager: {doc A}, docs-manager: {cluster B}, …] · SEQ = [Phase 0 triage, the Phase 2 → 2.5/2.6 → 3 → 4 spec chain, Phase 5 report] (reason)。
2. 严格执行每个文件只能有一名写入者。 每个受影响的文档路径必须且只能出现在一名 Agent 的任务说明中，并明确列为该 Agent 负责的文件集。无人负责的文档会被悄然遗漏；两名 Agent 同时负责一篇文档，则会发生更新丢失竞态，后写入的内容会覆盖先前写入，导致先前的发现消失。
3. [HAZARD] 两篇嵌入相同规范数据或派生数据的文档必须交给同一名 Agent——绝不能在波次中拆分。 计数、目录、模块映射、INDEX 行、ERD 实体，以及从事实来源复制出的任何表格，都必须由一名写入者基于对该来源的一次读取重新生成。拆给两名 Agent 后，它们会在同一次提交中产生分歧——而且这种分歧会通过审核，因为每篇文档本身都自洽，只有两篇文档之间不一致。按事实来源聚类，而不是按目录聚类。
4. 在规范文档链之前设置屏障。 Phase 2 → 2.5/2.6 → 3 → 4 必须保持为固定的顺序链：$spec 的输出为派生索引提供输入，而 §8 TCs 为 [mode=sync] 提供输入。并行只发生在同一阶段内彼此独立的模块之间，绝不能跨越这些阶段。
5. 按模块拆分任务仅在模块互不相交时才可并行。 两个检测到的模块若映射到同一份 Feature Spec，就会共享一个写入目标，因此必须作为一个任务处理——原因与步骤 0.4 对模块列表去重相同。
6. 每位成员都必须返回摘要和 Full report: 路径；只有在所有成员都返回后，你才能将其合并到 Phase 5 报告中，跳过的成员也算已返回。

---

Phase 1：项目上下文同步——参考文档 + project-config.json（并行，按影响范围限定）

此阶段存在的原因。 docs/project-reference/** 和 docs/project-config.json 会注入每个下游 AI 上下文，并为框架中的每项技能提供路由。当代码发生变化而这些文档没有更新时，运行环境就会继续向 Agent 灌输一个已不复存在的代码库信息——而此技能中的其他部分都无法发现这一问题，因为 Phases 2–4 只检查 docs/specs/**。$scan-all + $project-config 确实会修复它们，但它们会从头重新推导每篇文档，这就是为什么它们每 60 天运行一次，而不是每次变更后都运行。本阶段以差异范围完成相同的工作：同样确保没有过期内容，而且足够轻量，可以在每次变更后运行。

运行时机： 除非步骤 0.3 声明了真正的快速退出，否则始终运行。即使 Phases 2–4 全部跳过，也要运行本阶段。

范围约束： 只核实影响映射指向的内容；如果无法通过局部修补使文档恢复准确，则升级为完整的 $scan --target=X。绝不重新生成所有文档，也绝不在此处手动编写完整的参考文档——文档编写由 scan 负责，本阶段只负责核实和局部修复。

步骤 1.1：构建文档影响映射（SEQ——以下所有内容均由此推导）

node .claude/scripts/doc-impact-map.cjs --json     # machine-readable (drives the wave)
node .claude/scripts/doc-impact-map.cjs --text     # human-readable (goes in the report)
node .claude/scripts/doc-impact-map.cjs --base=origin/main   # branch-scope instead of working tree

该映射会将每个已更改文件路由到可能因此过时的文档和配置部分，并为每份文档返回：doc、exists、lastScanned/ageDays、scanTarget（升级到完整重新扫描的目标）、checks（适用的验证项）、changedFiles/addedFiles/deletedFiles，以及 heuristicOnly。路由依据 docs/project-config.json（contextGroups、modules、testing、e2eTesting、styling、designSystem、specRoots）和变更类别规则推导，绝不依赖硬编码的项目路径。

处理映射输出的规则——[BLOCKING]：

1. unrouted 文件不能证明没有影响——它们只能证明路由器没有对应规则。逐个手动分类：将其加入本轮处理，或在报告中说明其为何不会影响文档。绝不能让未路由文件在未说明的情况下通过并被视为最新。
2. heuristicOnly 文档只是一个猜测，不是证据。像验证其他文档一样验证它；只有说明理由后，才能将其判定为“不受影响”。
3. 任何 exists: false 的文档都是缺失文档，不是最新文档 → 路由到 $scan --target=<scanTarget>（如果整套文档都不存在，则使用 $docs-init）。
4. 如果脚本不可用（检出版本较旧，或主机不是 Node），则根据 docs/project-config.json 手动生成相同的映射——将已更改路径与 contextGroups[].pathRegexes 匹配 → guideDoc/patternsDoc/stylingDoc/designSystemDoc，将 modules[].pathRegex 匹配到项目结构 + modules，将测试/e2e/样式路径匹配到对应文档，将清单文件匹配到技术栈，将基础设施/CI 匹配到端口与部署，将 .claude/** 匹配到清单计数。记录该映射是手动生成的。

步骤 1.2：声明验证轮次（PAR——一条消息，包含所有成员）

Parallel plan: wave 1 = [docs-manager: {doc A}, docs-manager: {cluster B}, docs-manager: project-config.json, …] · SEQ = [Step 1.1 impact map, the Phase 2 → 2.5/2.6 → 3 → 4 spec chain, Phase 5 report] (reason)

轮次构建规则——步骤 0.6 中的注意事项原样适用，另外：

• 严格执行每个文件仅由一个写入者负责。 docs/project-config.json 在轮次中必须且只能由一个 Agent 负责。两个 Agent 合并 JSON 到同一个文件，必然导致更新丢失。
• 按信息源聚类，而不是按目录聚类。 README.md + project-structure-reference.md 都会重述模块/目录映射，而 CLAUDE.md + docs-index-reference.md + project-structure-reference.md 都包含从 .claude/ 推导出的计数——每组都交由一个 Agent 处理，避免同一次提交中的数字不一致。
• 每份路由到的文档必须且只能出现在一份任务说明中。没有负责人认领的文档会被悄然遗漏。
• 每个成员都必须返回其判定表 + Full report: 路径；只有所有成员都返回后才能合并。

步骤 1.3：逐文档验证约定（每个轮次成员的实际操作）

先验证，再做最小范围的修补。只运行映射为该文档列出的 checks：

检查项	回答的问题	如何检查	未通过时的处理
claims	文档中引用的路径和示例是否仍然存在？	运行 node .claude/scripts/doc-impact-map.cjs claims <doc>（missing = 无效，ambiguous = 通过后缀解析的简写），然后在引用的文件中搜索每个引用的符号	重新指向或删除无效引用，将有歧义的引用改为从仓库根目录开始的路径（引用是证据，绝不能留下无效引用）。reference-doc-freshness 测试套件会因任何无效引用而导致构建失败
coverage	此文档所属类型的每个新增产物是否都已列入其中？	将映射中的 addedFiles 与文档的清单／示例进行比较	添加缺少的行／示例，并注明 file:line
counts	数字声明是否与实际情况一致？	通过 glob／grep 重新统计（技能、钩子、Agent、工作流、服务、文档、测试）	更新数字；如果计数是生成的，还要更新标记区域
conventions	此次差异是否引入了文档未描述的模式，或违反了文档中的约定？	根据文档中的规则检查差异	新模式 → 记录在文档中。违反约定 → 报告问题，不要将其记录为约定
commands	文档中说明的运行／测试命令是否仍然有效？	对照清单／脚本（package.json、测试配置、integrationTestVerify）进行检查	修正命令
versions	声明的技术／框架版本是否与清单一致？	阅读清单，不要推测	修正版本
ports	文档中说明的端口／端点是否与基础设施配置一致？	阅读 compose／k8s／appsettings，不要推测	修正端口
links / catalog	交叉链接和目录条目是否都能解析？	检查每个目标是否存在	修复或删除该条目
每份文档的判定（必须且只能选一个，并提供证据）：

判定	含义	所需证据
FRESH	所有适用的检查均已运行且通过；无需编辑	运行了哪些检查 + 比较了哪些内容
PATCHED	已应用精确编辑，随后运行 $prompt-enhance <doc> 以保持内容简洁	修改的章节 + 每项新增声明的 file:line 证据 + prompt-enhance 运行确认（或说明跳过原因）
RESCAN REQUIRED	超出精确修复范围——出现了新的子系统／模式类别、大部分受影响章节中的示例已失效，或文档结构已不再适用于代码	要运行的 scanTarget（$scan --target=X），以及本次会话中是否已运行或已排队
UNVERIFIED	无法检查（缺少工具、读取受阻、预算不足）	原因，以及接下来必须运行的内容

[BLOCKING] 切勿捏造新鲜度。“看起来没问题”“可能没变”和“差异很小”都不算检查结果。未验证的文档应标记为 UNVERIFIED，绝不能标记为 FRESH——错误的 FRESH 比不检查更糟，因为它会消除原本能够在之后发现偏差的疑虑。

**[BLOCKING] 每份 PATCHED 的 docs/project-reference/** 文档都必须运行 $prompt-enhance <doc>（默认 --op=enhance），然后才能记录判定。**这些文档会注入每个下游 AI 上下文——如果精确编辑新增了正确的文字，却没有重新压缩，文档仍会显得臃肿。$prompt-enhance 会在保持内容对 AI 足够有用的同时尽可能精简（简洁压缩 + 注意力锚定），从而弥补精简修补路径上的同一缺口；而 $scan --target=X 自身的强制最终步骤（scan/SKILL.md Final Step）已在完整重新扫描时弥补了这一缺口——因此，升级为运行 $scan 的 RESCAN REQUIRED 文档无需在此单独调用。仅当编辑内容只有单个印章／日期／计数时才可跳过，并记录跳过原因。

步骤 1.4：project-config.json 偏差检查（单一写入者，经过架构验证）

仅验证映射中标记的部分。对每一项：

1. 根据证据重新推导——读取变更的文件，而不是沿用旧配置值。
2. 精确合并——添加／更新条目；绝不重命名、删除或重构顶层部分（$project-config Schema Protection Rules 在此同样适用）。
3. 证明每个已修改的 pathRegex／路径仍能匹配到真实内容——匹配不到任何文件的正则属于过时配置，会悄然禁用所有依赖它的下游路由器，而且架构检查无法发现这一点：

node -e "const c=require('./docs/project-config.json');const {execSync}=require('child_process');const files=execSync('git ls-files',{encoding:'utf8'}).split('\n').filter(Boolean).map(f=>'/'+f);for(const m of c.modules||[]){const re=new RegExp(m.pathRegex,'i');const n=files.filter(f=>re.test(f)).length;console.log((n?'OK  ':'DEAD')+' modules.'+m.name+' -> '+n+' file(s)')}"

4. 合并后验证架构：

node -e "const {validateConfig}=require('./.claude/hooks/lib/project-config-schema.cjs');console.log(JSON.stringify(validateConfig(require('./docs/project-config.json')),null,2))"

5. 升级处理，不要自行变通——新增顶层部分、新模块类别、新技术栈或验证失败，都意味着需要重新扫描，而非打补丁 → 运行 $project-config（如果本次会话无法运行，则报告需要运行）。

步骤 1.5：README 和项目文档（docs-manager）

在同一轮中，将 Phase 0 差异上下文传递给 docs-manager 子 Agent（agent_type="docs-manager"），用于处理项目说明文档：

• README.md — 如果项目范围或设置发生变化，则更新（保持在 300 行以内）
• docs/project-reference/project-structure-reference.md — 如果服务架构或跨服务模式发生变化，则更新（与 README 使用同一个 Agent：共享单一事实来源）

独立调用（非工作流步骤）可以先生成 2-4 个 scout-external（优先）或 scout Agent 来定位受影响的区域；作为工作流步骤时，跳过侦察并使用 Phase 0 差异上下文。

排除项不变：此 Agent 绝不负责 docs/specs/**、测试规格、spec-index/ERD 或派生技术视图。

步骤 1.6：时间戳规范（阻塞项）

执行内容	要写入的时间戳
完整 $scan --target=X	``（由 scan 负责，位于文档顶部）
对包含 Last scanned 时间戳的文档进行影响范围限定的验证/修补	``，写在该时间戳的下一行
对不含 Last scanned 时间戳的文档进行影响范围限定的验证/修补 — CLAUDE.md、.claude/docs/** 及其他面向 AI 的指令文件	不要写入任何时间戳。 仅在步骤 1.7 的输出中记录该文档的结论。——原因：这些文件是实时指令，且 .claude/agents/docs-manager.md:35 禁止在其中添加来源元数据；不添加元数据的规则优先于时间戳规则，不会被其覆盖。

[BLOCKING] 影响范围限定的检查不得修改 Last scanned。 该时间戳是 60 天完整重新扫描门槛的输入（getStaleReferenceDocs → refreshScanStaleFlag、.claude/hooks/lib/session-init-helpers.cjs:769-810）。通过局部检查移动该时间戳来换取速度，会关闭捕捉整篇文档过时内容的防护网——这两种机制相辅相成，不可互相替代。

本次运行中任何文档完成完整重新扫描后，重新评估该门槛：

node -e "require('./.claude/hooks/lib/session-init-helpers.cjs').refreshScanStaleFlag()"

步骤 1.7：Phase 1 输出

将新鲜度表写入 Phase 5 报告——每份已路由的文档和每个配置章节各占一行，并列出结论、执行的检查和证据。结论为 RESCAN REQUIRED 或 UNVERIFIED 的文档应纳入建议，让下一次会话明确继承这些待办事项，而不是让它们悄然遗留。

---

Phase 2：业务功能文档——调用 $spec

运行条件： 分类发现包含 hasFeatureDocs = true 的模块，且服务端/前端文件发生变化。

跳过条件： 没有服务端/前端功能文件发生变化。报告："No business feature docs impacted."

步骤 2.1：确定创建还是更新

场景	操作
模块已有功能文档	调用 $spec — 自动检测并触发更新流程
模块没有功能文档，且变更新增或修改了功能（新端点、命令/查询、实体、业务规则、面向用户的行为）	阻止 — 报告："模块 {Module} 没有功能规格，但此变更引入了功能行为。请先通过 $spec 创建无技术细节的 8 节功能规格，然后重新运行 docs-update。"。不要跳过。这是文档优先门禁。
模块没有功能文档，且变更仅涉及工具/样式/配置（不影响行为）	跳过并说明原因 "功能行为未发生变化 — 无需功能规格。"（与阶段 0 的快速退出 :113-120 一致）。
用户明确要求完整创建文档	使用明确的模块名称调用 $spec

步骤 2.2：调用 $spec

$spec Update feature docs for modules: {detected modules}.
Changed files: {list from triage}.
Impacted sections based on change types: {section impact from triage}.
Mode: update (existing docs only, do not create from scratch).

$spec 负责处理的内容（此处不要重复）：

• 强制执行无技术细节的 8 节结构
• 分析差异 → 映射受影响的章节
• 分析代码库（实体、命令、查询、控制器）
• 根据证据更新受影响的章节
• 更新分组 INDEX.md 目录条目
• 三轮验证（证据审查、领域模型、交叉引用）
• 无技术细节原则（§1–§7 中不包含实现细节；仅 §8 和 [Source:] 可包含证据载体）

步骤 2.3：审查 $spec 的输出

1. 更新的章节与分诊的章节影响映射一致
2. 未遗漏分诊标记为受影响的章节
3. 发现缺漏 → 重新调用 $spec，补上遗漏的章节

Step 2.4：代码↔规范同步验证（最终检查——由于 docs-update 是每个序列中的最后一步，因此会运行）

目的： docs-update 已经在 feature/bugfix/big-feature 中作为最后一步运行，因此这是工作流的最终关卡。它是提交时 Phase 4 提交钩子的搭档（此步骤负责指导，钩子负责强制执行）。在工作流完成前，验证已交付的代码是否确实符合映射到的、无技术细节的 8 节 Feature Spec。

对于本次运行中涉及的每个模块，将变更的代码与其 Feature Spec 进行差异对比，并检查以下三组内容：

Spec 集合（Feature Spec 章节）	对照变更代码进行同步检查	发现偏差时
§3 验收标准（AC-{FC}-NN）	每项变更的用户可见行为都对应一个 AC；有新行为却没有 AC，即表示缺少 AC。	报告偏差；重新调用 $spec 添加 AC。
§4 业务规则（BR-{FC}-NNN，[HARD]/[SOFT]）	每项变更的校验/不变量都符合一条 BR；移除或弱化某条 [HARD] 规则的代码路径即为回归。	阻止——将其作为代码与规范之间的矛盾提出，交由作者解决。
§8 测试规范（TC-{FC}-NNN + CoveredBy:）	每项新增/变更的业务可见行为都有一条 TC；每条 Tested TC 的 CoveredBy: {File}::{Method} 或已批准的覆盖载体仍然有效。旧版 IntegrationTest: 仅作为迁移输入。	报告；转交 $spec [mode=sync]。
派生技术视图（specRoots.technical.path）	技术层面的覆盖或组件拓扑变更可能需要重新生成/审查派生视图。该视图由代码/测试生成，绝不手动编写。	报告；转交 `$tech-spec [mode=generate	audit]`。

输出： 一张简短的同步验证表（模块 · AC 偏差 · BR 偏差/矛盾 · TC 偏差），追加到 docs-update 报告中。无偏差 = 三组内容均无偏差。若存在 [HARD]-BR 矛盾，则在解决该矛盾或由负责人明确接受之前，工作流无法完成。

范围： 仅涉及业务代码↔规范偏差。技术契约（API 路由/DTO、总线/作业机制）以代码为准，因此有意不再与文字说明进行复核。不新增序列步骤，也不新增 verify-sync 模式——此职责属于 docs-update 现有的最终检查。

---

阶段 2.5：派生索引 / ERD 刷新（可选 — spec-index）

[SINGLE-HOME] 不存在单独的“工程规格包”。规范制品是阶段 2 中更新的 8 节功能规格。spec-index 已重新调整用途，仅用于根据这些功能规格重新生成派生类别中的 INDEX.md / 跨能力 ERD——它不会重新提取 A-E 树。仅当此类别维护的派生索引 / ERD 因阶段 2 的变更而过时时，才运行此阶段。

运行时机： 阶段 2 更改了一个或多个功能规格，且此类别维护的派生 INDEX.md / ERD 辅助文档因此滞后。

跳过时机：

• 仅更改了 docs/、.claude/ 或配置文件
• 未触及 docs/specs/{Bucket}/ 下的任何功能规格
• 已跳过阶段 2（对功能没有影响）
• 此类别不维护派生索引 / ERD，或 project-config.json 包含 "spec_discovery_update": false
• spec 已在阶段 2 刷新 INDEX.md（无需单独刷新）

步骤 2.5.1：确定类别

• 使用 docs/project-reference/spec-system-reference.md 中的规范表格，将已更改的服务映射到 App 类别 → App 类别映射。
• 确认 docs/specs/{Bucket}/ 中包含已更新的功能规格。

步骤 2.5.2：调用 spec-index（派生索引模式）

$spec-index mode=index bucket={Bucket} artifacts=INDEX[,ERD]
Source: the canonical Feature Specs in docs/specs/{Bucket}/.
Output: regenerated DERIVED docs/specs/{Bucket}/INDEX.md (+ {Bucket}.erd.md if maintained), each carrying the DERIVED banner.

步骤 2.5.3：确认刷新完成

• 确认 INDEX.md 中的行与当前功能规格集合一致（没有失效链接，也没有遗漏的能力）。
• 确认存在派生标记和重新生成日期。
• 报告："Derived index refreshed: {Bucket} — {N} capabilities catalogued"。

职责分离： docs-update 负责编排——将类别范围传递给 spec-index。绝不手动编辑派生索引，也绝不重新创建 M##/A-E 制品（已弃用）。

---

阶段 3：测试规格 — 调用 $spec [mode=tests]

运行时机： 新增了业务可见功能，或更改了现有业务可见行为。仅限技术层面的更改若未改变用户 / QC 可见结果，则不需要修改业务第 8 节；如需技术覆盖，转交给测试和 $tech-spec，以生成派生技术视图。

跳过时机： 仅有纯外观更改（样式、注释、仅文档更改），且不影响行为。

步骤 3.1：确定 TC 模式

上下文	TC 模式
新功能代码，没有现有 TC	implement-first
已存在 PBI / 故事，尚未编写代码	TDD-first
已有 TC + 代码更改 / Bug 修复	update
用户说“同步测试规格”	sync
测试存在注解，但没有文档	from-integration-tests

PBI / 想法制品处理流程： 当已更改的制品与 docs/project-config.json 或项目参考文档中配置的 PBI / 想法制品根目录匹配时，docs-update 仅执行检测和委派。它可以识别受影响的模块、功能文档和 TC 范围，然后转交给 $spec、$spec [mode=tests] 或 $spec [mode=sync]。它不得直接根据 PBI / 想法制品生成 TC 内容，也不得自行编辑第 8 节。如果未配置制品根目录，应要求用户先初始化项目配置 / 参考文档，再假定路径。

步骤 3.2：调用 $spec [mode=tests]

$spec [mode=tests] Mode: {detected mode}.
Modules: {detected modules}.
Changed files: {list from triage}.
Business-visible functionality detected: {new or changed user/QC-visible outcomes from diff analysis}.

$spec [mode=tests] 负责处理以下内容（此处不要重复）：

• 5 种模式：TDD-first、implement-first、update、sync、from-integration-tests
• TC-{FEATURE}-{NNN} 格式，按十位区间编号
• 交互式 TC 审查（直接询问用户）
• 跨领域类别：授权、种子数据、性能、数据迁移
• 按阶段映射覆盖范围（计划阶段 → TC）
• 跨服务影响的图上下文分析
• 逐项验证 TC 证据
• 写入功能文档第 8 节（规范业务 TC 注册表）

步骤 3.3：审查 $spec [mode=tests] 输出

1. 新 TC 覆盖了分流中所有新增的业务可见功能
2. TC ID 不与现有 ID 冲突
3. 证据字段已填写（不是模板占位符）

---

阶段 4：测试规格 ↔ 测试代码同步 — 调用 $spec [mode=sync]

运行时机： 阶段 3 在功能规格的 §8 中新增或更新了 TC。

跳过时机： §8 中没有测试规格变更。

步骤 4.1：调用 $spec [mode=sync]

$spec [mode=sync] Sync test specs for capabilities: {detected features}.
Direction: forward (Feature Spec §8 Test Specifications → executing test code).
Updated TCs from Phase 3: {list of new/changed TC IDs}.

$spec [mode=sync] 负责处理的内容（此处不要重复）：

• 正向／反向同步：§8 测试规格 ↔ 执行测试代码
• 双向比较：功能规格 §8 与测试代码（代码是技术事实来源）
• 测试交叉引用（在所有执行测试层级中配置的测试规格注解键 TestSpec，以及每个 TC 的 CoveredBy: 字段；旧版 IntegrationTest: 仅作为迁移输入）

已弃用的 QA 仪表板（docs/specs/README.md、docs/specs/PRIORITY-INDEX.md）和手动维护的 A-E／M## 工程树已不复存在 — §8 是规范的业务 TC 注册表。派生辅助内容包括分桶 INDEX.md 计数（阶段 2.5）以及 specRoots.technical.path 下可重新生成的技术视图（阶段 2.6）。

步骤 4.2：审查同步结果

1. 阶段 3 的所有新 TC 都已反映在测试代码中（或已标记为未测试并注明理由）。
2. 不存在孤立 TC（测试代码的 TestSpec 注解引用了该 TC，但 §8 中没有）。

---

章节归属参考

各文档章节由哪个技能负责 — docs-update 仅负责委派，绝不直接编写：

章节	负责技能	docs-update 的角色
docs/project-reference/**（编写）	$scan --target=X	验证影响范围并进行精确修补；如果修补无法使其符合要求，则升级给 scan 处理 — 绝不手动编写完整参考文档
docs/project-config.json（结构）	$project-config	验证并对受影响章节进行精确合并，同时验证架构；整节变更或新增技术内容时升级处理
§1–§7（功能规格，不含技术内容）	$spec	传递分流上下文；审查输出
§8（测试规格）	$spec [mode=tests]	传递 TC 模式和变更文件；绝不在此处编写 TC
§8 ↔ 测试代码同步	$spec [mode=sync]	传递能力清单和方向；绝不直接编辑
派生分桶 INDEX.md／ERD	$spec-index（可选）	传递分桶范围；绝不手动编辑派生索引
派生技术规格视图	$tech-spec（可选）	传递服务／组件范围；绝不手动编辑派生技术文件

---

阶段 5：总结报告

始终将完整报告写入 plans/reports/docs-update-{YYMMDD}-{HHMM}.md：

### Documentation Update Summary

**Triage:** {N} files changed → {categories detected}
**Modules detected:** {module list}
**Generated mirror sync:** {Completed / N/A / Required before close}

**Phase 1 — Project Context Sync (impact-scoped freshness):**

Impact map: {N} changed files → {D} docs, {S} config sections, {U} unrouted ({map source: working tree / last commit / branch})

| Reference doc | Verdict                                        | Checks run                    | Evidence / action                                         |
| ------------- | ---------------------------------------------- | ----------------------------- | --------------------------------------------------------- |
| {doc}         | FRESH / PATCHED / RESCAN REQUIRED / UNVERIFIED | {claims, coverage, counts, …} | {what was compared; sections patched; scan target queued} |

| project-config.json section | Verdict                                        | Evidence / action                                                   |
| --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------- |
| {section}                   | FRESH / PATCHED / RESCAN REQUIRED / UNVERIFIED | {re-derived from …; schema validation result; dead pathRegex found} |

- Unrouted files classified: {file → why no doc impact}
- README / project docs: {Updated/Skipped}: {reason}
- Stamps: {docs given `Last verified`} · {docs fully rescanned and given `Last scanned`} · staleness flag refreshed: {yes/no}

**Phase 2 — Feature Specs ($spec):**

- {Capability X}: {Updated §1–§7 / No existing Feature Spec / Not impacted}
- {Capability Y}: {Updated §4 Business Rules, §5 Domain Model / Skipped: no Feature Spec}

**Phase 2.5 — Derived Index Refresh ($spec-index, optional):**

- {Refreshed {Bucket} INDEX.md ({N} capabilities) / Skipped: no derived index maintained / Skipped: spec_discovery_update=false}

**Phase 3 — Test Specifications §8 ($spec [mode=tests]):**

- Mode: {mode used}
- New TCs: {list of TC IDs added}
- Updated TCs: {list of TC IDs modified}
- Skipped: {reason if skipped}

**Phase 4 — Test Spec ↔ Test Code Sync ($spec [mode=sync]):**

- {Synced N TCs to test code / Skipped: no §8 changes}
- Discrepancies: {§8-vs-test-code comparison issues}

**Recommendations:**

- {New docs that should be created}
- {Stale docs flagged but not auto-fixed}
- {TCs flagged as Untested}

---

决策矩阵：何时使用 docs-update，何时直接使用技能

场景	使用 docs-update？	直接使用技能？
实现完成后同步文档（任何代码变更）	是 — 完整编排	—
变更后更新项目参考文档和 project-config.json	是 — 第一阶段按影响范围验证	$scan --target=X 或 $project-config（需要完整重建单个文档/章节时）
无论差异如何，刷新所有参考文档	否	$scan-all（+ $project-config）
从头创建新功能文档	否	$spec
为特定 PBI 生成 TC（测试驱动优先）	否	$spec [mode=tests]
路由 PBI/想法工件变更	是 — 检测/委派	$spec + $spec [mode=tests] 所属技能
仅同步仪表板（无代码变更）	否	$spec [mode=sync]
$plan-execute 或 $fix 之后的工作流步骤	是 — 完整编排	—
用户要求“在我进行更改后更新文档”	是 — 完整编排	—

---

其他请求

通过 $ARGUMENTS 传递调用方上下文，以跳过冗余分诊或缩小范围：

键	示例	效果
modules	modules=ModuleA,ModuleB	跳过自动检测；使用提供的列表
changed_files	changed_files=<configured-source-path>/ModuleA/...	跳过 git diff；使用提供的文件列表
phases	phases=2,3	仅运行指定阶段
mode	mode=update	覆盖规范模式检测
tc_mode	tc_mode=implement-first	覆盖规范 [mode=tests] 模式检测
skip_phases	skip_phases=1,2.5	跳过指定阶段
freshness	freshness=impact（默认）/ full / off	impact = 按指定方式运行阶段 1；full = 将每篇路由文档升级为 $scan --target=X（以及 $project-config）；off = 跳过阶段 1——仅在用户明确要求时允许，且报告 MUST 将每篇路由文档记录为 UNVERIFIED
base	base=origin/main	将影响映射的范围限定为分支差异，而非工作树

<additional_requests> $ARGUMENTS </additional_requests>

---

升级：何时 docs-update 不足以解决问题

情况	替代做法
缺少 Feature Spec，但已有对应功能	运行 $spec [mode=init] 编写包含 8 个部分的 Feature Spec，然后运行 docs-update
衍生目录 INDEX.md/ERD 缺失	运行 $spec-index mode=index bucket={Bucket} 重新生成
集成测试与 TC 不匹配	运行 $integration-test-review 进行诊断，然后运行 $integration-test 修复
Bug 是错误的规格说明导致的	运行 $spec [mode=update]（修正规范规格说明），然后再运行 docs-update；也可运行 $spec-index mode=index 重新生成目录索引
某份参考文档的问题超出简单修补的范围	运行该文档对应的 $scan --target=<key>（映射中的 scanTarget），然后重新运行 Phase 1 进行确认
大多数参考文档已过时，或触发了 60 天检查	运行 $scan-all — 影响范围检查无法修复早于此次差异的腐坏
参考文档完全不存在	运行 $docs-init（整套文档缺失）或 $scan --target=<key>（单份文档缺失）
project-config.json 需要新增部分、模块类别或技术栈，或未通过架构验证	运行 $project-config — 这是重新扫描，而非合并
怀疑存在当前差异未涉及的长期腐坏	运行 $scan-codebase-health（计数漂移、失效的配置引用、损坏的交叉链接）

---

[BLOCKING] 执行任何操作前，必须通过任务跟踪创建全部 8 项任务 — 参见 Mandatory Task Creation 表。绝不跳过、批量完成，或在未调用子技能的情况下标记为完成。 [BLOCKING] 按固定的步骤技能顺序执行：Phase 0 -> Phase 1 -> Phase 2 -> Phase 2.5/2.6 -> Phase 3 -> Phase 4 -> Phase 5 -> Final review。未经用户明确批准，绝不调整顺序、合并或跳过。 [BLOCKING] 每步任务锁定：每一步开始前，将任务标记为 in_progress；每一步结束后，附上证据或明确的跳过原因，将任务标记为 completed。 [BLOCKING] 如果 Task 工具不可用，创建等效的 8 步计划跟踪器，并同步更新每一步的状态。

Critical Purpose： 代码变更后进行所有文档同步的单一编排器。负责分流影响范围，并委派给专用技能。

Evidence Gate： [BLOCKING] — 每项结论都必须有 file:line 证明或可追溯证据，置信度须高于 80% 才能采取行动。 批判性思维模式——运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，置信度 >80% 才可采取行动。 **防止幻觉：**绝不将猜测当作事实——每项主张都要引用来源，坦诚承认不确定性，自查输出中的错误，独立交叉核对，并对自己的信心保持怀疑——缺乏证据的确定性是一切幻觉的根源。

子 Agent 返回约定——当此技能生成子 Agent 时，子 Agent 必须且只能返回以下结构。主 Agent 只读取此摘要——绝不要求子 Agent 在行内提供完整输出。

## 子 Agent 结果：[skill-name]

状态：✅ PASS | ⚠️ PARTIAL | ❌ FAIL
置信度：[0-100]%

### 发现（仅限严重/高优先级——最多 10 条）

- [严重程度] [文件:行号] [发现]

### 已采取的操作

- [已更改的文件] [更改内容]

### 阻碍（如有）

- [阻碍描述]

完整报告：plans/reports/[skill-name]-[date]-[slug].md

主 Agent 仅在以下情况读取 Full report 文件：(a) 解决特定阻碍，或 (b) 制定修复计划。 子 Agent 应增量编写完整报告（遵循 SYNC:incremental-persistence）——不得将其保留在内存中。

上下文预算——返回内容是摘要，而非记录稿：≤10 条发现，不得在行内提供原始文件内容/完整差异/逐字日志，也不得重新粘贴源内容。摘要以外的所有内容都保存在磁盘上的 Full report 中。如果子 Agent 的内容会超出摘要格式要求，就必须将详细信息写入报告，并且只返回报告路径——编排器的上下文是整个 map-reduce 要保护的稀缺资源。

跨服务检查——微服务/事件驱动架构：在结束调查、计划、规格说明或功能文档之前，必须执行此检查。遗漏下游消费者会导致静默回归。

边界	Grep 搜索词
事件生产者	Publish、Dispatch、Send、emit、EventBus、outbox、IntegrationEvent
事件消费者	Consumer、EventHandler、Subscribe、@EventListener、inbox
Saga/编排	Saga、ProcessManager、Choreography、Workflow、Orchestrator
同步服务调用	与其他服务之间的 HTTP/gRPC 调用
共享契约	OpenAPI 规范、proto、共享 DTO——标记破坏性变更
数据所有权	其他服务读写同一张表/集合 → 共享数据库反模式

**每个触点：**所属服务 · 消息名称 · 消费者 · 风险（NONE / ADDITIVE / BREAKING）。

**解除阻塞的前提：**已扫描生产者 · 已扫描消费者 · 已检查 Saga · 已审查契约 · 已标记破坏性变更风险 AI 错误预防 — 每项任务都应避免的失败模式：

上下文变化后重新读取文件。 上下文压缩、恢复或长时间运行的工作可能导致记忆过时；采取行动前，请核实当前文件。 根据源证据核实生成的内容。 AI 可能会臆造 API、名称、说法和文档事实。记录或引用之前，请检查相关来源。 删除或重命名前检查下游引用。 删除某个产物可能导致文档、生成的镜像、配置和调用方过时；先梳理引用。 编辑后追踪完整的影响链。 更改定义可能遗漏派生输出和使用方。宣布完成前，请追踪受影响的链路。 核实所有受影响的输出，而不只是第一个。 一个检查通过不代表所有检查都通过；请验证变更可能影响的每个输出界面。 假定现有值都是有意设置的——更改或标记某项为缺陷前，先问清原因。 更改或报告常量、限制、标志、临界值、措辞或模式前，请阅读附近的上下文和历史记录、调用方的顺序，以及 2 个以上遵循相同约定的同级调用点。文档说明了是什么，却没有说明为什么，这意味着缺少依据，而不是证明缺少防护。 行动前明确提出歧义——不要默默自行选择。 存在多种合理解释时，必须明确提问，或说明假设及其风险。 断言系统负责的结果，而不是基础设施负责的中间状态。 验证异步工作时，应断言最终业务状态——绝不要断言共享基础设施中的交付／重试记录，因为任何同时运行的进程都可能写入这些记录。单独运行时，这类检查可能通过；一旦有其他进程共享该基础设施，就会变得不稳定。 确保共享指南与角色相关。 通用指南必须对每个接收该指南的技能或 Agent 都有帮助；代码专属要求只应放在代码专属协议中。

嵌套任务展开约定 — 调用工作流步骤时，[Workflow] ... 行只是父容器；子技能仍会创建可见的阶段任务。

1. 首先调用当前任务列表。如果存在匹配的活动父工作流行，则设置 nested=true 并记录 parentTaskId；否则独立运行。
2. 阶段工作开始前，为每个声明的阶段创建一个任务。嵌套时，主题前缀为 [N.M] $skill-name — 阶段。
3. 嵌套时，使用 TaskUpdate(parentTaskId, addBlockedBy: [childIds]) 将父任务与子任务关联。
4. 编排器必须在调用子技能或子 Agent 之前，预先展开该子技能的阶段列表，并关联工作流行。
5. 开始工作前，恰好将一个子任务标记为 in_progress；证据写入后立即将其标记为 completed。
6. 只有在所有子任务均已完成，或已明确取消并说明原因后，才能完成父任务。

解除阻塞的条件： 当前任务列表已完成、子阶段已创建、嵌套时父任务已关联、首个子任务已标记为 in_progress。 项目参考文档检查关卡 — 在任务跟踪初始化之后、读取目标文件/源文件、执行 grep、编辑或分析之前运行。项目文档优先于通用框架假设。

1. 确定范围：文件类型、领域范围和操作。
2. 先阅读 docs/project-config.json —— 项目的机器可读映射。 它是本仓库的唯一事实来源（模块/路径、框架与搜索关键词、测试/E2E/集成运行命令、设计系统、架构规则、工作流模式）；在调查、规划或编码之前，以此确认准确路径、运行命令和约定——绝不要假设框架默认设置（CLAUDE.md 和参考文档均由它派生）。如果它——或文档索引、lessons.md、CLAUDE.md、AGENTS.md 或任何必需的参考文档——缺失或过时，请先自动运行 $project-init 或更精确的流程（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）；如果 Codex 镜像或 AGENTS.md 过时，请让用户运行 $sync-codex（绝不要自动运行）。
3. 按触发条件确定必需文档：始终需要 docs/project-reference/lessons.md；文档查找需要 docs-index-reference.md；审查需要 code-review-rules.md；后端/CQRS/API 需要 backend-patterns-reference.md；领域/实体需要 domain-entities-reference.md；前端/UI 需要 frontend-patterns-reference.md；样式/设计需要 scss-styling-guide.md + design-system/design-system-canonical.md；集成测试需要 integration-test-reference.md；E2E 需要 e2e-test-reference.md；功能文档/规格需要 feature-spec-reference.md + spec-system-reference.md + spec-principles.md；行为/公共契约/规格-测试-代码同步需要 workflow-spec-test-code-cycle-reference.md；派生规格索引/ERD/重新实现指南需要 spec-system-reference.md + docs/specs/ 下的源功能规格；架构/新领域需要 project-structure-reference.md。
4. 阅读所有必需文档，然后在开始目标工作前说明：Reference docs read: ... | Not applicable: ...。

就绪条件： 已评估范围、已查阅 docs/project-config.json、已检查/阅读必需文档或已完成初始化流程、已确认 lessons.md，并已给出引用说明。

任务跟踪与外部报告持久化 — 执行前完成此初始化；然后在处理目标/源文件前预读项目参考文档。

1. 在读取目标文件、执行 grep、编辑或分析之前，先创建简短的任务拆分。上下文丢失时，先检查当前任务列表。
2. 工作前将一个任务标记为 in_progress，取得证据后立即标记为 completed；绝不要批量转换状态。
3. 对规划/审查工作，在发现首条结果前创建 plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md。
4. 每处理完一个文件/章节/决策后，追加记录发现结果，并在最后基于报告文件综合整理。
5. 最终输出注明：Full report: plans/reports/{filename}。

在以下条件满足前不得开始： 已创建任务拆分；规划/审查工作已声明报告路径；已将首条发现持久化后，方可记录下一条发现。

务必注意：运用批判性思维和顺序思维——每项结论都必须有适当的可追溯证据（仓库/代码结论需提供 file:line；研究、产品、内容和文档结论需提供来源 URL 或文档章节）；置信度 >80% 时才采取行动，<60% 时不得提出建议。防止幻觉：绝不要把猜测说成事实，坦诚说明不确定性，独立交叉验证，对自己的判断保持怀疑。

务必注意：落实 AI 错误预防措施——根据证据核验生成的内容；删除或重命名前追踪下游引用；核验所有受影响的输出；上下文丢失后重新阅读文件；采取行动前明确指出歧义。

• 强制要求：在处理目标之前初始化任务跟踪；一次只转换一个任务的状态。

• 强制要求：逐步将规划/审查发现持久化到 plans/reports/，并基于磁盘上的报告进行综合整理。

• MANDATORY 在调查、规划或编码之前，必须先阅读 docs/project-config.json（项目地图：模块／路径、运行命令、约定、架构／工作流规则）以及必需的项目参考文档，并注明 Reference docs read: ...。

• MANDATORY 始终包含 lessons.md；项目配置和约定优先于通用框架默认规则。

• MANDATORY 如果项目配置、根目录指令文件或任何必需的参考文档缺失或已过时，必须自动运行 $project-init 或更精简的底层流程，然后才能开展常规的项目特定工作。

• MANDATORY 父级工作流条目不能替代子阶段跟踪；展开各阶段，并在嵌套时关联父级条目。

• MANDATORY 编排器必须在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵守同一时间仅有一个 in_progress 的规则。

Prompt-Enhance 收尾锚点

IMPORTANT MUST ATTENTION 遵循此技能声明的步骤顺序；未经用户明确批准，绝不跳过、重排或合并步骤 IMPORTANT MUST ATTENTION 对每个步骤／子技能调用：执行前设为 in_progress，执行后设为 completed IMPORTANT MUST ATTENTION 每个跳过的步骤都必须说明明确原因；每个已完成的步骤都必须提供简明证据 IMPORTANT MUST ATTENTION 如果 Task 工具不可用，必须维护一个状态同步的等效逐步计划跟踪器

并行子 Agent 调度 — 一旦任务拆分完成，立即规划并行任务，且必须在执行前完成；将可证明相互独立的任务按顺序执行会浪费实际耗时。适用于所有多步骤工作：工作流步骤、规划、批量更新、调查、研究、扫描、审查、文档同步。执行计划由元数据门控，绝不能默认并行——仅依据计划声明的内容（PAR／SEQ 标签和各阶段的写入集合）展开任务；未标记的计划按顺序执行——原因：从派生写入集合无法发现级联或生成的写入。

1. 为每项任务标注 PAR 或 SEQ。 PAR = 输入不包含任何待处理任务的输出，且写入集合与其他所有 PAR 任务互不重叠。否则标注为 SEQ——MUST ATTENTION 指明强制顺序执行的依赖关系。
2. 将 PAR 任务分组为多个波次。 同一波次内的任务之间不得存在依赖边。两个会写入同一文件的任务绝不能放在同一波次。只读工作（搜索、调查、审查、研究）可以自由并行。
3. 调度前声明： Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason)。
4. 每个波次都必须在一条消息中启动——每次 spawn_agent 调用都必须放在同一个响应中，绝不能分多轮逐次发出。根据 .claude/skills/shared/sub-agent-selection-guide.md 将每项任务交给相应的专业人员；绝不能把 code-reviewer 当作万能角色。
5. 向每个子 Agent 提供自包含的任务说明： 目标 · 范围和负责的文件 · 参考文档 · 返回要求（摘要 + Full report: 路径，遵循 SYNC:subagent-return-contract）· 将进展逐步保存到 plans/reports/（遵循 SYNC:incremental-persistence）。
6. 每个波次都必须设置屏障。 仅当所有成员均已返回后才能继续（条件不满足而跳过的任务也视为已返回）。完成汇总，并将每项任务标记为已完成／已跳过，然后再调度下一波。修改操作必须等待屏障解除。
7. 仅限一层。 被调度的子 Agent 执行自己的任务说明；除非该 Agent 的 .claude/agents/*.md 定义授权，否则进一步展开任务仍由编排器负责。

绝不并行处理： 共用写入目标的任务 · 需要使用待处理任务输出的任务 · 简单的单文件工作（调度开销大于收益）· 技能或工作流明确规定顺序的步骤 · 等待用户批准的关卡。

解除阻塞的条件： MUST ATTENTION 为每项任务标注 PAR／SEQ，并为每个 SEQ 任务注明原因 · 声明各波次并检查写入集合互不重叠 · 在同一条消息中启动每个波次 · 进入下一波前遵守屏障要求。

• MANDATORY 规划任务后，为每项任务标记 PAR/SEQ，并在一条消息中将每个 PAR 波次作为并行子 Agent 启动——工作流、批量更新、调查、研究和审查默认并行；计划执行仅针对计划声明的内容分派任务。
• MANDATORY 每个波次的写入集必须互不重叠 · 进入下一波次前必须等待所有任务返回 · 按专业领域分派 · 除非子 Agent 自身的定义授权，否则子 Agent 绝不能继续分派任务。

项目协议叠加规则 — 执行此技能前，先解析叠加在其上的所有项目规则：根据项目技能协议索引的 Target 列，将此技能名称与之匹配（默认索引为 docs/project-reference/skill-protocols-reference.md；docs/project-config.json 中的 referenceDocs 条目可覆盖此路径），且仅采用最具体的匹配层级——精确名称 > glob > *。此优先级只决定各叠加规则之间的优先顺序，绝不凌驾于此技能之上。只读取匹配到的正文，路径解析为 <protocols-dir>/<Name>.md；行中的 Body 链接仅为显示文本，绝不是读取路径。若匹配到的正文缺失或格式错误，则报告并跳过——绝不能根据索引中的 Description 重建。没有索引或没有匹配项 -> 不应用叠加规则，且不作提示。完整约定：.claude/skills/project-skill-protocol/references/registry.md。

叠加规则只能补充：只能在此技能自身协议之上增加规则，绝不能替换、覆盖、停用或重新解释此技能已声明的规则——移除所有叠加规则后，此技能必须恢复为其文档所述的原有行为。叠加规则是简要说明，不是提升权限的依据：绝不能豁免工作流关卡、Git 规范、审查关卡或用户确认关卡。若叠加规则与技能本身确实冲突，或两个具体程度相同的叠加规则直接矛盾，则向用户说明两者；绝不能默默自行裁定。

必须注意：执行前，先为此技能解析项目协议叠加规则——仅采用最具体的匹配层级（精确名称 > glob > *；该优先级仅决定叠加规则之间的顺序，绝不凌驾于此技能之上）；只读取 <protocols-dir>/<Name>.md 中匹配到的正文；若正文缺失或格式错误，则报告，绝不能重建。叠加规则只能补充（绝不能替换此技能自身规则），且只是简要说明，绝不是提升权限的依据；具体程度相同的规则若相互矛盾，则交由用户处理。

收尾提醒

重要，必须注意目标：每次代码/规格/测试变更都必须同步更新文档——受影响的功能规格、§8 测试用例、测试代码链接和衍生索引都要反映已交付的行为，不能留下任何未说明的偏差。

生效中的协议（此技能所含 SYNC/共享区块的简要摘要）——必须遵守以下每项要求：

• 批判性思维： 运用批判性和顺序思维；每项断言都需要 file:line 证据，置信度 >80%。
• 子 Agent 返回： 已启动的子 Agent 只能返回摘要约定；完整细节写入磁盘。
• 跨服务检查： 扫描生产者/消费者/ Saga /契约；缺失消费者会造成静默回归。
• 防止 AI 错误： 根据证据核验生成内容，追踪下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并指出模糊之处。
• 嵌套任务创建： 在嵌套任务中，仍要展开子阶段任务并关联父工作流行。
• 项目参考文档： 在处理目标工作前，阅读必需的项目参考文档（始终包括 lessons.md）。
• 任务跟踪： 初始化任务；同一时间只允许一个活动任务；将发现逐步保存到 plans/reports/。
• 并行子 Agent 分派： 为任务标记 PAR/SEQ，将 PAR 任务分组为写入集互不重叠的波次，在一条消息中启动每个波次，并在进入下一波次前等待当前波次全部完成。 重要，务必注意：执行任何操作前，必须先通过任务跟踪创建全部 8 个任务，然后按固定顺序 0 -> 1 -> 2 -> 2.5/2.6 -> 3 -> 4 -> 5 -> final review 执行——未经用户明确批准，绝不得调整顺序、合并或跳过；原因：阶段顺序是防止偏差的关卡；跳过阶段会导致过时内容悄然发布 重要，务必注意：docs-update 仅用作路由器——委派给 $spec、$spec [mode=tests]、$spec [mode=sync]、$spec-index；绝不得编写 §8 内容、编辑 Feature Spec / 派生索引文件，或重复子技能逻辑；原因：双重编写会导致两个来源彼此偏离 重要，务必注意：每次跳过都必须是有依据的决定——将任务标记为 completed，并提供有 file:line 支持的理由；绝不得悄然省略某个阶段；原因：没有正当理由的跳过与遗漏更新无法区分 务必注意：嵌套任务扩展约定——在工作流内部调用时，仍须通过任务跟踪扩展内部阶段，使用 [N.M] $skill-name — phase 前缀，并通过 TaskUpdate(parentTaskId, addBlockedBy: [childIds]) 建立关联；原因：工作流行只是容器，不能替代阶段跟踪 务必注意：对于每一步，执行前将任务设为 in_progress，执行后将其设为 completed，并提供证据或跳过理由——绝不得批量变更状态，始终只保留一个活动任务 务必注意：如果任务工具不可用，请使用等效的 8 步计划跟踪器，并逐步同步状态 务必注意：证据关卡——每项主张、检测到的模块和影响映射都需要 file:line / git diff 证明；置信度 >80% 才可执行，<60% 时不得执行；没有证据的“模块未变更”不是有效的跳过理由；原因：推测会将文档更新路由到错误位置，并漏掉真正的偏差 务必注意：断定文档结构前，先搜索现有模式——阅读相应类别中现有的 Feature Spec / INDEX 布局以及项目参考文档；从 docs/project-config.json 构建模块映射，绝不得使用硬编码的技能路径；原因：本地文档惯例优先于通用假设 务必注意：复用相近模式前，先评估是否适用——包含后端和前端变更的模块应合并为一个条目，而非两个；确认变更确实会改变行为后，才路由至 $spec；原因：重复调用或不涉及行为的调用会浪费检查轮次并破坏审计记录 务必注意：对于有歧义的路由决定，必须直接询问用户以确认——说明可选方案，绝不得悄然自行决定要运行哪些阶段 务必注意：输出必须与技术栈无关——更新 spec/specs/README/INDEX 时，正文或标题中不得引入任何框架、产品、语言或模式名称；先更新逻辑 ID（FR-/BR-/OP-/TC-），再更新正文；证据字段例外，应予保留；原因：正文是可移植的约定，证据载体记录物理坐标（spec-principles §3） 务必注意：步骤 2.4 必须对每个已修改模块执行最终代码与规范同步核验——已移除或弱化的 [HARD] BR 构成代码与规范之间的矛盾，在解决该矛盾或经负责人接受之前，必须阻止任务完成；AC 偏差应重新调用 $spec，TC 偏差应路由至 $spec [mode=sync] 务必注意：阶段 1 的项目上下文同步除非影响映射为空，否则必须执行——构建映射（node .claude/scripts/doc-impact-map.cjs），并行核验路由到的 docs/project-reference/** 文档和 docs/project-config.json 章节，为每份路由文档给出结论（FRESH | PATCHED | RESCAN REQUIRED | UNVERIFIED），且在仅针对影响范围的检查中绝不得移动 Last scanned 时间戳；原因：这些文档为所有下游 AI 上下文提供信息，未经核验的文档属于 UNVERIFIED，而非 FRESH；移动时间戳会在不知不觉中使 60 天全面重新扫描关卡失效 务必注意：阶段 0 分类必须始终最先执行（git diff → 分类 → 模块去重 → 记录现有文档状态）；阶段 2 $spec 更新 §1–§7；如果变更模块具有功能行为但没有 Feature Spec，则必须先补文档，否则不得继续；原因：跳过分类或先补文档关卡会导致未记录的行为随产品发布 务必注意：阶段 2.5 $spec-index [mode=index] 可选地依据 Feature Specs 刷新派生的类别 INDEX/ERD（绝不重新提取 A-E 树）；阶段 2.6 $tech-spec 可选地刷新/审计派生技术视图；阶段 3 $spec [mode=tests] 同步 §8 TCs；阶段 4 $spec [mode=sync] 同步 §8 TCs 与实际执行的测试代码（不存在 QA 仪表板） 务必注意：对于 .claude 技能/钩子/工作流/同步工具的变更，必须标明生成镜像的同步状态（npm run codex:sync 已完成或明确标记为 N/A）；docs-update 负责路由/报告此项检查，绝不得直接编辑生成镜像 务必注意：始终将阶段 5 总结报告写入 plans/reports/docs-update-{YYMMDD}-{HHMM}.md，并执行最终复核任务（#8）；报告是审计记录，复核用于确认所有受影响文档均已更新，且不存在无正当理由的跳过 反合理化：

规避说法	反驳
“只改了文档/配置——跳过所有阶段”	仍然运行阶段 0 分诊——快速退出是一项决策，而不是假设
“只改了 .claude/**——只是工具，快速退出”	Harness 编辑会导致 CLAUDE.md / docs-index / project-structure 中基于 glob 的清单计数和目录过时。仍然运行阶段 1；仅跳过阶段 2-4
“参考文档看起来没问题”	“看起来没问题”不算检查。运行该文档指定的检查，或将其报告为 UNVERIFIED
“我更新了文档，所以会刷新 Last scanned”	只有完整的 $scan --target=X 才能更新该时间戳——按影响范围进行的补丁应写入 Last verified，且仅限已有 Last scanned 时间戳的位置
“project-config.json 足够接近了”	根据证据重新推导标记的部分，证明每个涉及的 pathRegex 仍与真实文件匹配，并运行架构验证
“映射器返回了未路由的文件——没什么可做的”	未路由意味着路由器没有规则，并不意味着文档是最新的。逐一手动分类
“没有功能文档——跳过阶段 2”	标记任务已完成并说明原因。绝不能悄悄省略
“模块没变——跳过子技能”	提供 file:line 证据。没有证据 = 不得跳过
“我已经知道改了什么”	仍然运行 git diff——了解不完整会导致遗漏更新
“不需要阶段 5 报告”	始终撰写摘要报告——这是审计记录
“我稍后再更新任务”	无效。每个步骤执行前后都必须实时更改任务状态。
“我先运行技能，再创建任务”	无效。先创建/跟踪任务，再执行 step-skill 调用。
“我自己写 §8 TC 更快”	无效。只能通过路由器处理——委派给 $spec [mode=tests]；双重编写会导致内容不一致。
“[HARD] BR 被削弱了，但测试通过”	阻止——代码与规范相矛盾；必须解决或由负责人接受，绝不能放行。
重要：必须注意：在采取任何行动前，通过任务跟踪（或等效跟踪器）创建全部 8 个任务，并实时跟踪每一步——开始前标记为 in_progress，完成后标记为 completed，并提供证据。
重要：必须注意：只能进行路由——委派所有 §8 / Feature Spec / 派生索引 / 派生技术视图的写入；此处绝不编写这些内容——原因：双重编写者会导致规范与其生成视图出现偏差。
重要：必须注意：每次跳过都需要 file:line 证据，并创建一个说明原因的 completed 任务；按固定阶段顺序执行——绝不悄悄省略任何阶段。

无钩子提示词协议镜像（自动同步）

来源：.claude/.ck.json + .claude/skills/shared/sync-inline-versions.md（:full blocks）+ .claude/scripts/lib/hookless-prompt-protocol.cjs

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议——必须遵守。重要，必须遵守。关键。不得以任何理由跳过。

**通用可移植性边界：**可复用技能和协议文本应保持项目中立；从 docs/project-config.json 和 docs/project-reference/ 中发现项目特定约定。应用共享 AI-SDD（参见 shared/sdd-artifact-contract.md）。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中指定的项目参考文档。对于规范、测试用例、行为变更、公共契约或 docs/specs/ 相关工作，请通过文档索引指定的本地规范文档进行路由：feature-spec-reference.md、spec-system-reference.md、spec-principles.md，以及在规范/测试/代码必须保持同步时使用的 workflow-spec-test-code-cycle-reference.md。如果任一文件或必需的参考文档缺失或过时，请在开展常规项目特定工作前自动运行 $project-init（或范围更窄的底层路由，例如 $project-config、$docs-init、$scan-all 或 $scan --target=<key>）。只要有此共享上下文和本地文档，任何受支持的 AI 工具均可执行。

1. **检测：**如果提示以明确的斜杠技能/工作流命令开头，直接执行。否则，将提示与工作流目录和技能列表进行匹配。
2. **分析：**选择最佳方案：直接执行、调用技能、启动标准工作流，或组合自定义步骤。
3. **自动选择：**自行选择最佳方案。不要询问用户是直接执行、调用技能、启动标准工作流，还是使用自定义工作流。
4. **启动：**对于选定的工作流，调用 $start-workflow <workflowId>；对于选定的技能，调用该技能；对于自定义工作流，直接按顺序执行自定义步骤；对于直接执行，继续处理任务。
5. **创建任务：**如果所选路径包含多个步骤，则在执行前为所有工作流/技能/自定义步骤创建任务跟踪。
6. **并行化：**执行任务列表前，为每项任务标记 PAR（输入独立且写入目标与所有其他 PAR 任务互不重叠）或 SEQ（注明阻塞依赖项），将 PAR 任务分组为多个波次，声明波次计划，并在一条消息中启动每个波次的子 Agent——每个波次都必须等待所有任务返回；默认只向下分派一层，除非子 Agent 自身的定义授权进一步分派。不得并行处理写入目标共享、依赖其他任务输出、属于简单的单文件工作、执行顺序由技能或工作流明确规定，或涉及用户审批门槛的任务。默认按顺序执行属于缺陷；独立任务不得不并行。
7. **执行：**遵循上下文指令中的 工作流步骤推进与并行阶段规则——由模型驱动；子 Agent 完成任务与内联调用具有同等推进作用；并行阶段组必须等待所有任务返回后才能推进，绝不可将其串行化。

共享 AI-SDD 协议标记

来源：.claude/skills/shared/sync-inline-versions.md

SYNC:ai-sdd-artifact-contract

AI-SDD 工件契约 — 共享的规范驱动开发规则应保持可移植，并由源文件管理。

1. 将可复用的 AI-SDD 原则保存在 .claude 中；将特定于仓库的路径、命令、负责人、产品和格式放在项目配置／参考文档中。
2. 保持以下周期：spec -> plan -> tasks -> implement -> verify -> update spec/docs。
3. 通过决策、任务、TC／测试、源证据以及文档／规范更新，追踪每项要求或不变量。
4. 将从代码提取规范的内容仅视为参考，直到规范的权威负责人接受为止。
5. 任何受支持的 AI 工具都可基于同步的上下文进行规划、实现、审查或验证；使用多个工具是可选的。
6. 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。— 原因：镜像是生成的工件；下次同步时，手动修改会被覆盖
7. 如果 docs/project-config.json、根目录指令文件或必需的项目参考文档缺失或过时，则在进行常规项目特定工作之前，自动运行 $project-init 或范围更窄的底层流程。

当前参考文档： 当前技能根目录中的 shared/sdd-artifact-contract.md。

---

SYNC:ai-sdd-artifact-contract:reminder

• MANDATORY 应用 shared/sdd-artifact-contract.md；将可复用的 AI-SDD 保存在 .claude 中，并将本地规则保存在项目文档中。
• MANDATORY 从代码提取的规范仅供参考，直到权威规范获批；任何受支持的 AI 工具都可基于同步的上下文执行工作。
• MANDATORY 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。
• MANDATORY 如果项目配置、根目录指令文件或必需的参考文档缺失或过时，则应自动通过 $project-init 或范围更窄的设置流程来处理项目特定工作。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；之后随着各步骤开始／完成，持续同步更新任务跟踪。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — MANDATORY。不得跳过。

开始前将工作拆分为小任务（任务跟踪）。添加最终任务：“分析 AI 错误与经验教训”。

提取经验教训——仅关注根本原因，而非修复表象：

1. 指明失败模式（推理／假设失误），而非表面症状——“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，则再向上抽象一层。
3. 写成通用规则——去除特定于项目的名称／路径／类。规则应适用于任何代码库。
4. 合并：多个错误若属于同一种失败模式，则合并为一条经验教训。
5. 复发门槛：“如果没有这条提醒，未来会话中是否会再次出现此问题？”——不会 → 跳过 $learn。
6. 自动修复门槛：“$code-review／$code-simplifier／$security-review／$lint 能否发现此问题？”——能 → 改进审查技能。
7. 两个门槛都通过 → 请用户运行 $learn。 [CRITICAL-THINKING-MINDSET] 运用批判性思维和序贯思维。每项断言都需要可追溯的证据；采取行动前，置信度须 >80%。 **反幻觉原则：**绝不将猜测当作事实——为每项断言引用来源，坦诚承认不确定性，自行检查输出错误，独立交叉核对，并对自己的信心保持怀疑——缺乏证据的确信是所有幻觉的根源。 **AI 注意力原则（首因－近因效应）：**在较长提示词／协议的开头和结尾都放置最关键的 3 条规则，以确保指令在较长的上下文窗口中仍能得到遵循。 **目标驱动执行：**先定义成功标准，持续循环直至验证完成；仅当可观察的检查均通过后才停止。 **测试验证意图：**测试必须保护业务规则／不变量，并在受保护的意图遭到破坏时失败，而不只是复现当前行为。

常见 AI 错误预防（系统经验）

• 上下文压缩后重新读取文件。 编辑前必须在同一上下文中先读取文件；上下文压缩会清除读取状态。编辑前重新读取。
• 批量替换后 grep 旧术语。 AI 过度相信查找/替换已覆盖所有内容。批量编辑后，对整个仓库执行 grep，检查文档/配置/目录中遗漏的引用。
• 删除前检查下游引用。 删除会连带导致文档/代码过时。移除前先梳理引用文件。
• 丢失记忆后，创建新内容前先检查现有状态。 上下文压缩会清除先前工作的记忆。查询当前状态以便继续——绝不要盲目重复创建。
• 根据实际代码验证 AI 生成的内容。 AI 会幻觉出 API、类名和方法签名。记录/引用前先用 grep 确认其确实存在。
• 编辑后追踪完整依赖链。 更改定义却漏掉下游使用方。追踪完整链路。
• 重命名时，对所有使用方文件类型执行 grep。 某些文件类型会静默忽略缺失的引用（不会产生编译错误）。搜索代码、模板、配置和生成文件。
• 验证正确性时追踪所有代码路径。 代码存在 ≠ 代码会执行。追踪提前退出、错误分支和条件跳过——不要只看正常路径。
• 源数据变更时，更新包含规范数据的文档。 内嵌派生数据（工作流、架构、配置）的文档会静默过时。源数据变更时，同时更新所有内嵌该数据的文档。
• 恢复上下文后验证子 Agent 的结果。 父 Agent 压缩上下文期间，后台 Agent 可能已经完成——用 grep 验证输出，不要相信对任务已完成的假设。
• 将完整目标列表与子 Agent 的分配任务交叉核对。 按类别并行分配子 Agent 会漏掉边界项。继续前，将各分配任务的并集与目标列表核对。
• 子 Agent 只能从其 Agent 的 .md 定义继承知识——使用自定义 Agent 类型，不要使用内置 Explore。 采用工具 = 权限 + 知识 + 执行（编号工作流步骤）。
• 逐步记录子 Agent 的发现，不要等最后一次性提交。 长时间运行的子 Agent 可能在最终写入前达到截断限制——导致发现丢失。指示其按章节追加到报告文件。
• 调试时，修复前先问“责任在谁？” 追踪调用方（数据错误）还是被调用方（处理错误）。在责任层修复——绝不要只修补症状出现的位置。
• 测试失败 → 先记录暂定结论，再追踪/编辑，然后调查。 使用完整的五类分类：SOURCE-WRONG（生产代码违背意图）、TEST-WRONG（断言/设置已过时）、TEST-NOT-OPTIMAL（测试有效但脆弱或信号弱）、ENVIRONMENT-BLOCKED（外部状态阻止得出结论），或 AMBIGUOUS（意图/证据不足以安全判断）。然后追踪根因，并对照规范依据（如果存在，查看 docs/specs/**）和源代码进行交叉验证。绝不要只为让测试变绿而削弱断言、添加跳过、放宽超时或更改源代码。
• 提取/重构后，对所有已移除名称执行 grep。 主文件“完成” ≠ 次要文件干净。宣布完成前，在整个范围内搜索每个已移除的符号。
• 假定现有值是有意设定的——更改或将其标记为缺陷前先问为什么。 仅凭模式匹配判定“错误”会忽略上下文。更改或报告任何常量/限制/标志/阈值前：阅读注释、git blame、调用方的执行顺序（使该值正确的保证通常位于引用行之前紧邻执行的代码中），以及同一惯例下至少 2 个同类调用点。只说明“是什么”却不说明“为什么”的文档，缺少的是依据，并不能证明缺少保护措施；在验证环节中，准确的 file:line 引用证明的是转录无误，而不是缺陷确实存在。
• 验证所有受影响的输出，而不只是第一个。 一个构建成功 ≠ 全部成功。涉及多个技术栈的变更（后端/前端/测试/文档）要求验证每一项输出。
• 复制相近模式前，先评估是否适用。 最接近的示例 ≠ 前提相同——确认新上下文具有相同的约束、基类、作用域和生命周期。
• 整体优先的调试方式——抵制注意力就近陷阱。 不要一头扎进第一个看似合理的原因。列出所有前提（配置、环境变量、路径、数据库、端点、凭据、版本、DI、数据）。用证据（grep/查询——而非推理）逐项验证。问“什么证据可以推翻这个假设？”——如果没有，那就不是假设。代价最高的失败：在“显而易见”的层继续深挖，而 Bug 实际位于从未质疑过的层。
• 精准修改——应用 diff 测试（结合上下文判断）。 两种模式：（1）Bug 修复 → 每一行都能追溯到该 Bug；不做样式调整；只清理因你的修改而变得未使用的孤立内容。（2）审查/增强 → 实施改进，并声明为“超出主要请求的增强：[内容]”。绝不要悄悄扩大范围。Diff 测试：“如果我没有被要求做 X，这一行还会存在吗？”——如果不会，就删除或明确说明。
• 编码前先指出歧义——不要默默自行选择。 存在多种有效解释时，逐一列出并说明工作量：“[请求] 可能指 (1) [N 小时]、(2) [N 小时]。哪一个更重要？”先列出范围/格式/数量/约束方面的假设。如果有更简单的方案，也要说明。绝不要默默自行选择。
• [MANDATORY FIRST ACTION] 回复前务必先启用合适的技能或工作流。 将任务与工作流目录和技能列表进行匹配；通过技能调用或 $start-workflow <workflowId> 启用。检查之前绝不要回答或编写代码。跳过 = 违反协议。
• Why-Review 对抗性思维——审查任何计划、决策或设计时都要运用。 默认持怀疑态度，而非验证者态度：充分论证被否决的替代方案，将每项既定理由反向审视（“它牺牲了什么？”），对最重要的 2-3 项假设进行压力测试，开展事前验尸（“已发布，3 个月后失败——什么会出问题？”），并指出作者遗漏的 1-2 种替代方案。章节齐全 ≠ 质量过关；质量取决于因果推理、具体缓解措施和证据，而不是“这样更好”或“密切关注”。
• 大型审查的子 Agent 提示词应优先安排报告写入。 处理许多文件的子 Agent 可能在最终写入前耗尽预算——导致发现丢失。设计提示词时应确保：（1）报告写入是第一个明确的交付项，（2）按文件/章节逐项追加（不要批量写入），（3）限定范围，避免读取耗尽预算。若输出在句中被截断且没有报告文件 → 启动范围更窄的任务，不要原样重试相同提示词。
• 上下文压缩后，继续前重新验证此前各阶段的所有结果。 摘要描述的是意图，不是环境状态（git 索引、文件系统、进程）。恢复时，首先审查：git status、重新读取修改过的文件、验证文件系统。每一项“已完成”的声明，在证据确认前都是未经验证的假设。
• OOM/内存：先检查行数，再检查行大小。 排查顺序：（1）无界查询——触发条件是否没有数据库筛选？将筛选推到数据库端；这可消除 OOM。（2）行是否很大？投影可按比例减少数据量。减少行数比投影的收益更大。
• 断言系统自身负责的结果，绝不要断言基础设施负责的中间状态。 测试任何异步行为（队列/代理传递、重试、后台任务、缓存、复制）时，应断言最终业务/实体状态。绝不要断言传递记录——消费/发送状态、尝试次数、最后错误、代理、调度程序或 outbox/inbox 表中的行存在与否或数量。这些记录属于共享基础设施，任何同时运行的进程（同伴 Worker、第二个副本、遗留的本地容器）都可能写入，且通常使用确定性的共享键；因此，断言会悄悄测试开发者的环境，而不是系统：单独运行时通过，一旦有其他进程共享该代理和数据库就会不稳定。每个断言都要问：“无论哪个进程执行了这项工作，该断言都会成立吗？”——如果不会，就改为断言已收敛的数据状态。推论：进程本地的故障注入和进程内遥测不能用于控制任何进程都可能执行的工作——将它们用作压力放大器（启用 → 限定时间窗口 → 停用 → 断言收敛），绝不要用作前置条件。
• 不要让领域概念进入通用/共享/基础设施层。 可复用层（共享库、框架、基础设施模块）不得引用任何特定使用方的领域概念——租户/客户/产品 ID、业务实体、功能规则。泄漏进来后，代码能够编译并运行，因此会悄无声息地通过审查，同时让“可复用”层与某个使用方耦合。保持共享类型与领域无关；通过子类/组合将领域字段/逻辑下放到使用方。——原因：与某个使用方的领域耦合的层不再可复用。