code-handoff

中文 | English

code-handoff 是一个面向代码开发项目的通用交接 skill。
它既帮助交接方输出结构化 handoff，也帮助接手方通过增量问询真正把项目接起来，适用于前端、后端、嵌入式、数据/ML、基础设施、SDK/库、移动端等工程场景。

它想解决的问题不是"再写一份交接模板"，而是把项目交接从一次性文档，变成一个可继续推进、可恢复、可逐步确认的工作流。

为什么要做

很多代码项目交接，真正容易卡住的不是"完全没文档"，而是这些高影响信息经常缺位：

• 第一条该跑的命令是什么
• 当前应该优先从哪里入手
• 哪些命令只是模板，哪些在本轮真实跑通过
• 哪些路径已经踩过坑，不值得再试
• 哪些是用户长期偏好，哪些只是当前项目例外
• 信息缺失时，什么时候应该立即追问，而不是最后再统一列清单

code-handoff 的目标，就是把这些最容易导致绕路的内容结构化，并把接手过程本身流程化。

核心思路

这个 skill 采用三层信息模型：

层	作用
User Development Profile	记录用户跨项目的长期稳定偏好
Project Collaboration Overlay	记录当前项目对长期偏好的覆盖项
Live Project / Session Handoff	记录本次 handoff 的实时状态

默认输出保持四段式：

1. handoff draft
2. gap report
3. minimum validation checklist
4. pitfalls and lessons learned

它们分别回答：

• 当前状态是什么
• 还缺什么
• 最少怎么验证
• 哪些坑不要再踩

两种模式

handoff-authoring

交接方使用，目标是生成结构化 handoff 包，尽量把当前入口、命令、验证方式、风险和推荐执行顺序写清楚。

handoff-intake

接手方使用，目标是先做非破坏性探索，一旦发现高影响缺口就立刻问用户，关键缺口收敛后再形成正式 intake 计划。

和普通 handoff 最大的区别在于：
它强调的不只是"写清楚"，而是"让下一个人更快开工，且少绕路"。

仓库结构

code-handoff/
  README.md                        中文主 README（本文件）
  README.en.md                     英文说明
  docs/
    plan.md                        设计方案与演化记录
    architecture.md                架构说明
    decisions.md                   已接受决策（ADR）
    for-ai-maintainers.md          AI 维护指南
    examples/                      示例方向
  skills/
    code-handoff/
      SKILL.md                     skill 主入口
      agents/
        openai.yaml                UI 元数据
        runtime-config.yaml        维护用结构化配置
      references/                  运行时细则
      scripts/                     后续自动化脚本
      assets/                      静态资源
  fixtures/
    sample-handoffs/               后续示例交接包
  tests/
    golden/                        后续 golden 输出

主要文件职责

文件 / 目录	作用
skills/code-handoff/SKILL.md	skill 入口、触发范围、顶层行为
skills/code-handoff/references/	runtime 细则、schema、workflow
skills/code-handoff/agents/openai.yaml	UI 展示元数据
skills/code-handoff/agents/runtime-config.yaml	维护用结构化配置清单
docs/plan.md	提案、探索、设计演化
docs/decisions.md	已拍板的长期决策
docs/architecture.md	当前结构与分层说明
docs/for-ai-maintainers.md	给维护仓库的 AI 的操作说明

怎么使用

本仓库里真正的 skill 位于 skills/code-handoff/。

接入方式

让 AI 自行获取并执行（无需安装）

适用于支持文件系统访问或网络访问的 AI 工具（如 Claude Code）。无需预配置，直接让 AI 拉取 skill 并当场执行。

从本地副本加载：

请阅读 skills/code-handoff/SKILL.md 及 skills/code-handoff/references/ 目录下的所有文件，
理解 code-handoff skill 的完整规则，然后按照该 skill 帮我完成项目交接。

从远程仓库加载（AI 自行克隆或拉取）：

请从 https://github.com/Powdered-Delta/code-handoff-skill 获取 code-handoff skill，
读取 skills/code-handoff/SKILL.md 及 references/ 目录，然后按照该 skill 帮我完成项目交接。

适合快速试用，或在不方便修改项目配置的环境下临时使用。

Claude Code / Claude Desktop

把 skills/code-handoff/ 目录复制到你的项目下，在 CLAUDE.md 里加一行引用；或直接在对话中告知路径：

请使用 skills/code-handoff/SKILL.md 里的 code-handoff skill 来帮我完成项目交接。

OpenAI Codex / 兼容 Agents SDK 的宿主

把 skills/code-handoff/ 复制或链接到 Codex 的 skills 发现目录，Codex 将通过 SKILL.md frontmatter 自动注册：

# 路径视实际 Codex 安装位置而定
cp -r skills/code-handoff/ "$CODEX_HOME/skills/"
# 或
ln -s "$(pwd)/skills/code-handoff" "$CODEX_HOME/skills/code-handoff"

其他 AI 工具

只要宿主能读取 Markdown 文件，直接把 SKILL.md 路径告诉 AI 即可。

典型用法

角色	模式	做什么
交接方	handoff-authoring	AI 读取 SKILL.md，采集当前项目状态，输出四段式 handoff 包
接手方	handoff-intake	AI 以计划模式运行，先非破坏性探索，发现高影响缺口立即追问，收敛后形成 intake 计划

计划模式要求

handoff-intake 需要计划模式（plan mode）支持，handoff-authoring 不做强制要求。

宿主不支持计划模式时：

• 接手方（intake）： skill 会先提示当前限制，建议切换到支持计划模式的宿主。若用户坚持继续，进入 fallback-intake——仅做静态缺口整理和单轮问题收集，输出标记 degraded: true，不视为完整接手。
• 交接方（authoring）： 自动降级为静态交接包生成，产出仍为四段式，但未经多轮确认的字段会显式标注。

维护方式

本仓库采用"文档先定方向，runtime 再落地，README 最后同步"的维护流程。

推荐顺序：

1. 先更新 docs/plan.md 或 docs/decisions.md
2. 再根据已更新文档同步修改 SKILL.md 与相关 references
3. 最后更新 README、示例和其他说明文档

如果你要继续开发这套 skill，可以按这个映射来判断先改哪里：

想改什么	优先修改哪里
skill 名称、触发描述、顶层流程	skills/code-handoff/SKILL.md
schema、问询规则、checkpoint、局部 workflow	skills/code-handoff/references/*.md
展示名、短描述、默认 prompt	skills/code-handoff/agents/openai.yaml
维护用结构化配置	skills/code-handoff/agents/runtime-config.yaml
设计方案、架构说明、长期决策	docs/*.md

最小校验

修改后建议运行 skill 验证脚本，检查 SKILL.md frontmatter 和基础结构是否仍然有效。

脚本来源： quick_validate.py 是 skill-creator 工具链自带的校验脚本，随 Codex / skill-creator 安装包一起分发，不包含在本仓库中。

运行要求：

• Python 3.8+
• 已安装 Codex 或 skill-creator 工具链

# 将 <skill-creator-scripts-dir> 替换为实际安装路径下的 scripts/ 目录
python -X utf8 <skill-creator-scripts-dir>/quick_validate.py skills/code-handoff

脚本主要检查：SKILL.md 是否包含合法 frontmatter（name / description 字段）、skill 目录基础结构是否符合规范。

当前进展

当前仓库已经具备：

• 标准 skill 基础结构
• SKILL.md 主入口（含 frontmatter）
• 一组较完整的 runtime references
• 维护用的架构与决策文档

目前更适合把后续工作理解为待推进事项，而不是"缺陷清单"。

TODO

• 补一份完整的 intake 示例
• 为 fixtures/sample-handoffs/ 加入真实样例
• 为 tests/golden/ 加入回归基准
• 视需要补充 scripts/ 下的辅助脚本

文档索引

• README.en.md：英文说明
• docs/plan.md：完整设计方案
• docs/architecture.md：架构说明
• docs/decisions.md：ADR 与关键决策
• docs/for-ai-maintainers.md：AI 维护指南

示例（欢迎提 pr 进行补充。ps: 记得脱敏）

• docs/handoff.md：本仓库自身的交接包，同时作为 handoff-authoring 模式的真实使用示例
• docs/examples/frontend-example.md：前端项目交接包示例（占位，待补）
• docs/examples/backend-example.md：后端项目交接包示例（占位，待补）
• docs/examples/embedded-example.md：嵌入式项目交接包示例（占位，待补）

一句话总结

code-handoff 想做的不是"交接模板集合"，而是一个能把代码项目交接过程结构化、可追问、可恢复、可持续推进的通用 skill。