executing-handoff-prompts

name	executing-handoff-prompts
description	手动触发

Executing Handoff Prompts（接手并执行交接文档）

这是什么

prompts/*.md 是自包含的跨会话任务交接文档：上一会话把"目标 / 现状摸底（file:line 为证）/ 已定方向 / 未完成清单 / 硬约束 / 参考文件"固化下来，交给一个全新会话接手。本 skill 就是接手这一棒的标准流程。

为什么不能照着文档闷头做。 交接文档是上一会话某个时点写的，而它描述的代码一直在动：分支被并发会话推进、文件搬迁、行号漂移、声称"已提交"的东西可能其实没进 git、声称的接口名/字段后缀/表名可能看错或已改名。.claude/rules/data-integrity.md 把这件事钉死了——子代理报告、历史代码、二手转述，进硬断言/SQL/migration 前一律不可直接采信，必须落权威源头核对。交接文档本身就是最大的一份二手转述。所以本 skill 的脊梁是：动手前先派子代理把文档里的事实逐条核实，与真实代码对账，把差异摊出来，再执行。

这正是用户要的：执行之前先派 agent 探索相关代码，证实文档中的内容。

主代理（你）是编排者，不是执行者

本 skill 的纪律是让你始终保持轻量上下文，把读和写都隔离到一次性子代理里，自己只做"核实—对齐—编排—审查"：

• 只读最重要的文档，不大批量读代码。 你读这份交接文档、以及它点名"先读"的 spec / 姊妹交接 / 记忆——这些是把握全局必需的。源码的成片阅读一律交给子代理：你要知道某段代码的事实，是派子代理去查、带证据回报，而不是自己把源文件拉进上下文通读。唯一例外：要进硬断言/SQL 的事实，你亲手做一次外科式核对（grep 一个实体定义 / 查真 DB 一条）——那是一行命令，不是通读。
• 不自己执行任务，派子代理执行。 写代码、改文件、跑实现这些活你不亲自动手——你拆批、构造自包含简报、派发子代理（走 subagent-driven-development 的批次模型），再收口审查、对用户汇报。
• 执行前先出方案、等用户拍板（HARD-GATE）。 核实对账完成后，先把"打算怎么做"摊给用户看，得到明确确认才动手，别对完账就径直开干。

为什么这么定：交接任务往往牵涉大量文件与多轮实现，主代理一旦自己下场读代码/写代码，上下文很快被占满、也容易在没对齐的方向上跑偏。让主代理专注协调，把读和写都隔离到一次性子代理里，既省主代理上下文，又能在动手前由用户把关方向。

何时使用

• 用户给了一份 prompts/*.md（或贴了一整段交接文档）让你接手/续作。
• 一个任务跨多会话推进，这一会话要接上一棒。
• 任何"按这份别的会话写好的、带现状摸底+待办的文档继续做"的场景。

不适用：从零开始的新需求（用 /brainstorming）；已有正式实现计划且在本会话执行（用 subagent-driven-development）；并行会话执行计划（用 executing-plans）。交接文档常常会把你导向这些 skill——那时本 skill 负责"核实 + 对账 + 按文档闸门驱动"，具体实现交给被导向的 skill。

---

流程

阶段 0 · 定位并通读文档

• 用户给了路径就读它；只说"接手 prompts 里那个"就 Glob prompts/*.md 列出来、按命名挑出最可能的一份与用户确认（注意 prompts/archive/ 里是已完成/过时的，别接）；贴了正文就直接用正文。
• 整篇读完再动，别只读一句话目标就开干。交接文档的价值密度在"现状摸底 / 硬约束 / 并发交叉 / 参考文件位置"这些段。
• 把文档点名"先读"的 spec / 姊妹交接 / 记忆一并读了——这些都是文档，属"最重要的文档"，该读。但到此为止：别顺着"参考文件位置"段去成片读源码，那是阶段 2 子代理的活，主代理不下场读代码。

阶段 1 · 解析出"待核实清单"

通读时把文档里所有可证伪的具体声明抽成一张清单，这些就是子代理要去坐实的东西：

• file:line 引用：xxx.ts:23-141、runner.ts:150 这类——文件还在不在、行号有没有漂、内容是否还是文档说的那回事。
• 事实型断言：接口名 / 字段后缀 / 表名 / 列名 / 实体名（例：raw.daily_indicator、adj_factor、fwd_ret_h1）。
• git 声明：commit 5f2706b 已提交、T3 已提交但无单测、"分支之后又落了多笔"——commit 是否真在、改了哪些文件、声称"已完成/已提交"的是否真进了 git。
• 已定方向的前提：文档说"放 X 模块下,因为 Y 会循环依赖"——Y 这个前提是否still成立。
• 并发交叉：文档点名的并发 commit / 同域改动（例"T1 与并发 425365d 同域""factor_code_fp 护门可能误拦"）——这些最容易让旧结论失效。
• 数值/规模声明：行数（"Modal 214 行"）、测试数（"vitest 146 例"）、"全绿"之类——可能已被后续改动推翻。

同时记下文档规定的执行流程（"建议执行流程"段）和硬约束段——阶段 4 要照着走、逐条带走。

阶段 2 · 派 Explore 子代理核实（强制）

把待核实清单切成互不相交的若干片，并行派 Explore 子代理（subagent_type: Explore，显式传 model: sonnet——CLAUDE.md 规定）。每个子代理给一份自包含的简报：它要核实哪几条、到哪里查、用什么证据回答，不要让它继承本会话上下文。

切片建议（按依赖/文件域分，参考 dispatching-parallel-agents）：

• 代码事实片：file:line 是否仍有效 + 接口/字段/表名/列名是否属实。要求子代理亲 grep 实体定义 / 真读那几行，回报"PASS / 漂移到新行号 / MISMATCH"并附证据（文件 + 行 + 摘录）。
• git 现状片：git log --oneline -10 看 HEAD 是否被并发推进、git status --short 看工作区；逐个 git show <hash> --stat 坐实"已提交"声明真假、改了哪些文件；并发 commit 是否真同域。
• DB/口径片（涉及表名/列名/数据口径时）：docker exec crypto-postgres psql -U cryptouser -d cryptodb -c "..." 查真表一条样本坐实列名/后缀。涉及 Tushare 字段/口径的，子代理先触发 tushare-sync-dev skill 查文档。

要求每个子代理带证据回报，结论用 PASS / 漂移 / MISMATCH 三态，不要只说"看起来对"。

铁律：子代理报告也是二手。 凡是核实结果要进硬断言 / 硬编码常量 / SQL join 键 / migration的，主代理在写之前自己再亲查一次（grep 实体 / 查真 DB 一条）。这是一次外科式单点核对（一条 grep / 一行 psql），不是通读源码——和"主代理不大批量读代码"不冲突。data-integrity.md 明确：agent 报告 = 二手信息，与"历史代码推断"同级，不得直接进硬断言。本项目真踩过——摸底子代理报"后缀 .THS、表 a_share_daily_indicators"，真值是 .TI、表已改名 raw.daily_indicator，未自查就会写出误杀全部正常数据的断言。

git 路径搬迁陷阱：用带路径过滤的 git log -- <path> 做考古时，若该路径在历史某点被搬迁过（例 apps/quant-pipeline 曾从仓库根搬进 apps/），跨搬迁点的查询会静默返回空——别据此误判"当时不存在",改用 --follow / git blame / 老路径。

阶段 3 · 对账，按严重度分级处理

把"文档声称 vs 子代理坐实（+ 主代理自查）"逐条对账，输出一份简短对账报告给用户看，每条标明严重度：

• 琐碎漂移（行号偏移、文件搬迁但目标仍在、行数/测试数等非关键计数变了）→ 自动校正，在报告里记一笔（"文档说 runner.ts:150，实际在 :162"），继续往下，不打断。
• 实质矛盾 → 硬停，摊给用户，等定夺。包括但不限于：
  • 文档声称"已提交/已完成"，git 里其实没有（或被 revert）。
  • 接口名 / 字段后缀 / 表名 / 列名 / 实体名 与代码不符。
  • "已定方向"的前提不成立（例文档说"放 A 模块因 B 会循环依赖"，实际 B 已不存在）。
  • 并发会话已经把文档假设的基础改掉（HEAD 推进后基础接口/契约变了）。
  • 文档说的文件/模块整个不在了。

对账报告模板：

## 交接文档核实对账（先核实再执行）
文档：prompts/xxx.md ｜ 接手时 HEAD：<git log 第一行>

✅ 已坐实（N 条）：……（一句话带过，必要处附 file:line）
🔧 琐碎漂移已自动校正（M 条）：文档说 X → 实际 Y，已按实际为准继续
🛑 实质矛盾，需你定夺（K 条）：
  1. 文档称「……」，实际「……」（证据：file:line / git show / psql）。
     影响：……。我的建议：……（但不替你拍板）。

有 🛑 就停在这里等用户；只有 ✅/🔧 则简报一句"文档与代码已对齐（含 M 处琐碎漂移已校正）"，进入阶段 4 出执行方案。

阶段 4 · 出执行方案，展示给用户，确认后才执行（HARD-GATE）

对账通过（无 🛑，或 🛑 已与用户解决）后，先别动手。把一份具体执行方案摊给用户，等到明确确认（"可以""按这个来"之类）再进阶段 5。方案要让用户一眼看清你打算怎么把这份交接落地，至少含：

• 路线：直接派子代理实现，还是先进文档规定的 /brainstorming 敲设计（若文档要求，方案这一步就写"下一步进 brainstorming"，并把待敲定的开放问题列给用户）。
• 批次拆分：打算派几个子代理、各做什么、按什么文件域/依赖切批（参考 subagent-driven-development），哪些可并行。
• 改动面：会碰哪些文件/模块、要不要 migration、要不要前端、要不要重启 server/worker。
• 验证口径：完成后跑哪些命令算绿（jest / type-check / pytest / 真机 e2e 等，多取文档"验证标准"段）。
• 风险与权衡：对账里的 🔧 漂移、并发交叉、文档里的开放问题，逐条点明你的处理打算——不替用户拍板，列选项。

用户没确认前不写任何代码、不派实现子代理。用户若在此调整方向，按调整后的方案再确认一次。

这一闸门和文档自身的 /brainstorming HARD-GATE 不冲突、是叠加：文档要求 brainstorming 的，方案的"路线"就是去 brainstorming，brainstorming 内部敲设计仍需用户批准；文档没要求的，这一闸门保证你也不会"对完账就闷头开干"。

阶段 5 · 按方案派子代理执行，主代理只编排

用户确认方案后，按方案 + 文档自己的"建议执行流程"往下走，但实现工作一律派子代理，主代理不亲自写代码/改文件：

• 实现 = 派发，不是自己动手：按方案的批次拆分，给每个子代理一份自包含简报（要改的文件、契约、验收命令、相关 file:line 与硬约束，不继承本会话上下文）；不相交的批次并行派（subagent-driven-development 模型）。子代理回来后，主代理审查（spec 合规 + 代码质量）、必要时再派一轮。主代理的上下文用于协调与审查，不下场敲实现。
• 文档把你导向某个 skill，就进那个 skill：
  • 让先 /brainstorming 敲设计 → 进 brainstorming，它的 HARD-GATE（设计需用户批准）照样停下等批准，别越过。（brainstorming 是你与用户的设计对话，由主代理直接进行，不算"执行任务"。）
  • 让用 subagent-driven-development 拆批次实现 → 进 SDD，按上一条派子代理。
  • 收尾让走 finishing-a-development-branch → 进它，与用户定整合方式，别擅自合并/PR。
• 文档没规定流程、就是"做 X"，也按批次派子代理实现（主代理不亲自写），结束前走 verification-before-completion。
• 逐条带走文档"硬约束"段——那是上一会话用踩坑换来的，本项目反复出现的坑通常已写在里面（nest start 无热加载改 server 必重启；新增 TypeORM 实体须同时加 module forFeature + app.module 根 entities 数组，漏后者运行时 EntityMetadataNotFound 500；前端日历日用 getFullYear/getMonth/getDate 防 UTC 漂移；factor_ids 空数组 = 全量重算；PowerShell 禁 && 用 ;；源文件一律 UTF-8、I/O 显式 encoding='utf-8'、对象键名用英文；git commit -m 中文走单引号 here-string、消息里别放 ASCII 双引号）。
• 提交纪律：工作区常有 ambient / 并发在途改动，提交只 git add <精确路径> 自己的文件，禁 git add -A/.；提交前 git log --oneline -5 确认 HEAD 没被并发会话推进。文档点名"别动"的 ambient 改动（如 CLAUDE.md、uv.lock）别一起提交。
• 全程不假设、暴露权衡、用中文（CLAUDE.md）。多解读都列出，别悄悄选一个；验证全绿前别说"完成"。

收尾 · 维护交接文档生命周期

任务做完后，按 CLAUDE.md 约定处理这份交接文档：完成/过时的删除或移入 prompts/archive/，别让已实现的交接留在主目录冒充"待办"。若本会话没做完，把"已做 / 未做 / 下一步（带 file:line 为证）"更新回文档或新写一份，交给下一棒。提交信息用 docs(prompts): … 或 chore(<域>): 删除已实现的交接提示词。

---

一句话记忆

文档是二手的，代码才是真的；你是编排者，不是执行者。 只读最重要的文档，派子代理把文档逐条核实并与代码对账（琐碎漂移自动校正、实质矛盾摊给用户）；出方案、等用户拍板；再派子代理把任务实现到底——读和写都隔离在一次性子代理里，主代理只核实、对齐、编排、审查。