context-infra 检查与复盘infra.guiming.net · 全内容自包含呈现 · 生成于 2026-07-21 16:28 UTC

Handoff Context

Z3 全文↑ Z2 条目

术-内容 · 术层 skill 全文

← 返回术层 skill 索引 · 返回方法论区

本页是 <code>rules/skills/drafts/workflow_handoff_context.md</code> 的逐字投影（仅隐私清洗，零改写）。

时点提示：本页是仓内文件 rules/skills/drafts/workflow_handoff_context.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。

Workflow：Handoff Context

元数据

目标

这个 skill 的目标是把 handoff 从“session 总结”提升为“面向下一位 agent 的任务运行说明”。成功的 handoff 不要求复述完整历史，而是让一个没有共享聊天上下文的新 agent 明确知道自己要做什么、先核什么、从哪里取权威需求、怎样判断完成，以及哪些问题和文件边界必须服务于这项任务。

handoff 文档不是权威事实源本身。它是面向恢复者的压缩索引：指向需求、trace、diff、测试、进程文档和任务卡等权威来源，并补足这些来源无法直接表达的下一步行动、注意力状态和 from-scratch 恢复要求。

何时使用

适用：

不适用：

核心不变量

handoff 只承担三件事：

  1. Current truth：当前真实状态是什么，证据在哪里。
  2. First action：恢复者第一步具体做什么，读什么，跑什么命令，不能依赖再读全篇才能理解。
  3. From-scratch requirements：如果恢复者完全没有旧聊天上下文，它必须知道哪些进度、约定、关键文件、不可逆决策和已知陷阱。
  4. Task-serving filter：handoff 里的每个问题、说明、章节和待读文件都必须服务于当前交接任务。不能改变下一步行动、完成判据、证据边界或风险控制的内容，删掉或改成指针。

任何不能服务这三件事的内容都应删掉或改成指针。

产物位置

优先使用当前任务已有的控制面：

同一主题的 handoff 不做追加拼贴。读取旧 handoff 理解历史后，从当前事实重写一份新的文档；同日同主题可覆盖，不同日同主题可新建并明确旧文件是否 stale。下一版 handoff 必须自包含运行机制、纪律和完成判据，不能要求恢复者回读上一版才能拼出完整流程。旧版只作 provenance。

最小输出契约

handoff 文档至少包含以下内容。章节名可以因项目约定调整，但语义必须齐全。

# Handoff: <topic>

## Resume Gate

- status: active | paused | awaiting_user | blocked | closure | stale
- handoff_created_at: <ISO-8601 or local date>
- authoritative_state: <path to state/control/trace or "this file only">
- stale_sources: []

## First Action

<恢复者第一步要做的一个具体动作。必须不依赖阅读其他章节即可执行。>

## Startup Check

- verify_claimed_position:
- unfinished_before_new_work:
- authoritative_task_source:

## Current Truth

- user_goal:
- current_phase:
- completed:
- in_progress:
- not_started:
- blockers:
- claim_ceiling:

## Evidence Pointers

- requirement_source:
- state_source:
- changed_files:
- validation:
- run_logs:
- decisions:

## From-Scratch Requirements

- progress:
- conventions:
- key_files:
- decisions_to_keep:
- known_pitfalls:
- files_to_read_first:
- files_not_to_touch:

## Next Steps

1. ...
2. ...
3. ...

可选章节：

来自 Binding Requirements Decomposition 的要求

adhoc_jobs/landing_requirement_decomposition_20260531 里 v4 handoff 是当前最相关的实战样本。它给出的要求不是模板美化，而是下一位主 agent 能直接运行的任务契约：

这些要求对一般 handoff 的迁移方式：handoff 本体负责“怎么恢复并执行”，需求全集和顺序交给权威文件；handoff 必须给恢复者一个先核对、再执行、再验收的闭环。

最终 Prompt 写法

当 handoff 本身要作为下一位 agent 的启动 prompt 时，按这个顺序组织。项目名、工具名和文件路径可替换，但语义不要丢。

你是接手 <task/project> 的新主 agent。第一步读取本仓库启动必读文件和本任务指定权威文件。

权威来源：
- 需求：<requirements source>
- 原始 prompt：<original prompt source>
- 执行顺序：<execution order source>
- 状态 / trace：<state or trace source>

启动核对：
1. 先核对本 handoff 记录的执行位置是否属实。
2. 找出 claimed-done 但未真正完成、in_progress、blocked 或孤儿产物。
3. 先补这些未完成项，再取新任务。

执行模型：
- 一次只推进一个 bounded task。
- 取任务顺序来自 <execution order / dependency edge>，不来自 recency 或主观 priority。
- 执行 prompt 从 <dispatch command or source> 组装，不手工拼。

每条任务必须包含：
1. 注入该任务逐字原始 prompt。
2. 先定位并审查既有成果。
3. 在既有基础上继续，不独立重做。
4. 用完成闸门收口。

完成闸门：
- 真实运行和可查 evidence。
- 可路由入口或消费链已接通。
- 文件状态真实落盘，不把 untracked 当完成。
- 第二方或确定性 gate 独立核验。
- done 前回答：它被谁调用？哪些 always-loaded / routing 文件更新？有没有孤儿文件？

报告与交接：
- 写出原始需求、做了什么、为什么有效、前后对比、未验证边界。
- 若仍需继续，重写 handoff：自包含机制，只写当前 phase 位置，需求指向权威源，纪律并入常驻机制。

这个 prompt 的核心是把下一位 agent 的注意力收束到当前任务：先核执行位置，再从权威需求取任务，再按完成判据收口。其他问题只有在影响这条链路时才进入 handoff。

写作纪律

Distill, do not copy

handoff 应比原会话短。不要粘贴聊天记录、长工具输出、完整 diff、长日志或已经存在于 PRD / ADR / task card / trace / report 的内容。保留结论和指针。

Reference, do not duplicate

已经存在权威文件时，只给路径、行锚、命令或 URL。重复内容会漂移，尤其是需求、测试结果、commit 状态和 blockers。

First Action must stand alone

First Action 是恢复者的启动指令，不是摘要。它应包含最小读入路径、目标动作和停止点。例如：

Read CONTROL.md and TASKS/T004.md, then run the focused unit test listed in TASKS/T004. Stop after writing evidence/reviews/round_004_file_production.md.

Current truth beats narrative

优先写当前可证实状态，不写“我们快完成了”这类叙事。每个完成声明都应能指向文件、命令输出、测试、diff、trace、commit 或人工等待条件。

Questions serve the task

handoff 里可以留下问题，但问题必须能改变下一步执行、验收或风险控制。泛泛的开放问题、历史争论、背景解释和“以后也许要想”的内容会污染下一位 agent 的注意力，应移到报告、设计文档或 backlog。

Secrets and private context are blocked

handoff 可能被复制给另一个工具或公开环境。默认删除 API keys、tokens、私密路径、个人身份信息、未公开客户/项目名、私有数据集和 unpublished assets。必须保留时，用占位符和本地路径指针，不写原值。

NightCode 分层恢复模型

从 NightCode process doc 迁移来的关键判断：

写 handoff 时按这个顺序压缩：

层handoff 中怎么表达证据要求
P1 语义Current Truth、First Action、From-Scratch Requirements允许自然语言，但关键 claim 要有指针。
P2 交付changed_files、commits、artifacts文件路径、diff、commit hash 或 artifact 路径。
P3 上下文validation、run_logs、files_to_read_first命令、日志、trace、source manifest。

如果已有进程文档或 .loop_trace/，handoff 不复制 P2/P3，只索引它们。若没有机器事实源，handoff 必须诚实写 authoritative_state: this file only，claim ceiling 不能超过 bounded_resume_context。

不要在本 skill 中引入 context 使用率阈值、置信度检测器或自动压缩状态机。handoff 写作只处理已经确定需要交接的情况；是否触发交接由上层 runtime、Controller 或用户决定。

与 Controller Loop 的关系

在 workflow_controller_loop 中，HANDOFF.md 只在这些场景创建：

普通 inline 任务或当前 turn 能收束的 task_loop 不应为了仪式感创建常驻 HANDOFF.md。

Controller Loop 中的 handoff 必须满足：

验收标准

一个 handoff 合格，必须同时满足：

常见失败模式

失败模式表现修正
总结代替恢复契约写了很多“做过什么”，没有第一步动作。把 First Action 提到前面，写成可执行指令。
重复权威文件把需求、日志、diff 复制进 handoff。改为路径和证据指针。
叙事成功“基本完成”“测试应该过”没有证据。降级 claim ceiling，补验证或写未验证原因。
旧 handoff 追加成拼贴多轮追加导致旧 blocker 和新状态并存。读旧文件后整体重写当前版。
与机器状态冲突handoff 说 active，state 写 blocked。明确权威源并修正 stale source。
忽略用户原始目标只写 agent 自己做了什么。指向用户需求源，恢复者先读 requirement。
无边界委派没写 owned / forbidden files，debug agent 可能误改。增加 files_to_read_first 和 files_not_to_touch。
参照旧版拼流程“见上一版 §X”导致新 agent 需要多文件拼装。当前 handoff 自包含运行机制，旧版只作 provenance。
问题不服务任务留下一堆泛泛 open questions，下一位 agent 不知道取舍。只保留会改变执行、验收或风险控制的问题。
重列需求全集handoff 复制需求表，和权威需求文件漂移。指向权威需求与原始 prompt 文件，只写当前 phase 位置。

来源与融合依据

← 返回术层 skill 索引 · 返回方法论区