Back to Details

handoff

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

写 Handoff 的方法论

Methodology for Writing Handoff Documents

什么时候写

When to Write

  • 长任务/大需求暂停或收尾，要换人（或换 agent）接手时
  • 用户明说"写个 handoff / 交接文档 / handoff.md"
  • 上下文窗口即将耗尽、需要把进度固化到磁盘时
  • When a long-term task/large requirement is paused or wrapped up and needs to be handed over to another person (or Agent)
  • When the user explicitly requests "write a handoff / handoff document / handoff.md"
  • When the context window is about to be exhausted and progress needs to be saved to disk

放哪里

Where to Place It

.agents/tasks/<task_name>/handoff.md
  • <task_name>
    = 任务 slug（与 plan.md/findings.md 同目录，如 
    kdrive
    ）。
  • 不要放 
    .agents/tasks/
    根目录（那是任务列表区，不是文档区）。
  • 同目录有 plan.md 时 handoff 是"对外交接版"，plan 是"执行流水版"，不互相替代。
.agents/tasks/<task_name>/handoff.md
  • <task_name>
    = task slug (in the same directory as plan.md/findings.md, e.g., 
    kdrive
    ).
  • Do NOT place it in the root directory of 
    .agents/tasks/
    (that is the task list area, not the document area).
  • When there is a plan.md in the same directory, the handoff is the "external handoff version" and the plan is the "execution log version"; they are not interchangeable.

写什么（结构模板）

What to Write (Structure Template)

  1. 一句话现状：现在能跑/不能跑，停在哪
  2. 分支与合并纪律：分支栈、MR 顺序、retarget 规则（读者第一需要）
  3. 架构不变量：改代码前必须背下来的约束（锁模型、语义红线、协议契约）
  4. 测试基建：怎么跑测试/仿真/e2e，现成的脚手架在哪
  5. 环境坑：权限、CI、构建、部署的踩坑记录（血泪最值钱）
  6. 已知边界与 roadmap：没做的、触发条件、下一步候选
  7. 怎么继续：从哪切分支、怎么验证、找谁
  1. One-sentence Status: Whether it works now, and where it's stuck
  2. Branch and Merge Discipline: Branch stack, MR order, retarget rules (top priority for readers)
  3. Architecture Invariants: Constraints that must be memorized before modifying code (lock model, semantic red lines, protocol contracts)
  4. Testing Infrastructure: How to run tests/simulations/E2E, and where the existing scaffolding is located
  5. Environment Pitfalls: Records of issues encountered with permissions, CI, building, and deployment (lessons learned are the most valuable)
  6. Known Boundaries and Roadmap: Uncompleted items, trigger conditions, and next-step candidates
  7. How to Continue: Where to branch from, how to verify, and who to contact

写作原则

Writing Principles

  • 自包含：读者零上下文能接手；不引用"见上面的对话"
  • 不变量 vs 易变信息分开：架构约束、坑、方法照写；MR 状态/排期/进度等易变信息注明权威源 + 快照日期（如"MR 状态以 GitLab 为准，2026-08-03 快照"），不抄死
  • 环境坑必须写：权限、CI 钩子、构建绕行——这是handoff 最省时间的部分
  • 简洁直接，不堆历史；读者是"下一个干活的人"，不是评审
  • Self-Contained: Readers can take over without prior context; do not reference "see the conversation above"
  • Separate Invariants vs Volatile Information: Write down architecture constraints, pitfalls, and methods as-is; for volatile information such as MR status/scheduling/progress, specify the authoritative source + snapshot date (e.g., "MR status is subject to GitLab, snapshot taken on 2026-08-03") instead of copying statically
  • Must Document Environment Pitfalls: Permissions, CI hooks, build workarounds—this is the most time-saving part of a handoff
  • Be concise and direct; do not pile up history; the reader is the "next person to do the work", not a reviewer

落地顺序

Implementation Sequence

  1. 写进 
    .agents/tasks/<task_name>/handoff.md
    （任务状态的家）
  2. 若其中有可复用的领域知识（架构不变量、环境坑、纪律），再抽进 gizmo 的 
    skills/<domain>-dev/
    （SKILL.md 入口 + references/ 存放全量），别把任务状态本身塞进 skill
  1. Write it into 
    .agents/tasks/<task_name>/handoff.md
    (the home for task status)
  2. If there is reusable domain knowledge (architecture invariants, environment pitfalls, discipline) in it, extract it into gizmo's 
    skills/<domain>-dev/
    (SKILL.md entry + references/ for full storage); do not put the task status itself into a skill