项目交接 ChenneyZhuang/project-handoff

project-handoff 项目交接

让下一个会话和这一个一样聪明：一份带日期的交接文件，装着现状、带理由的决策、和写成「症状 → 原因 → 对策」的坑。

Why / 为什么

长项目死在聊天记录里：关键上下文住在会滚走、被压缩、或属于已结束会话的消息中。handoff 是安装量最高的 agent 技能之一（79.7 万+），因为几乎人人都会撞上。这个技能是同一纪律的双语版，坑的格式更严格。

How it differs from conversation-compaction handoffs / 与「对话压缩交接」的区别

流行的 handoff 技能（如 mattpocock 的，79 万+安装）把当前对话压缩成临时目录的交接文档，解决会话到会话的连续性。这个技能解决的是另一个问题：住在项目里的、可版本控制的持久 handoff.md——跨周积累决策与坑，人和智能体都能读，即使没有对话产生它也存在。两者可以同时用，互不冲突。

The handoff file / 交接文件长什么样

Project X — handoff

Current state (dated)
- what exists, counts, paths, versions — verifiable claims only

Next steps (dated, actionable)
1. the next concrete action

Decisions (why attached)
- Use X because Y; rejected Z — so nobody relitigates

Pitfalls (symptom → cause → fix)
- error text → the real cause → the fix that worked

The discipline / 纪律

1. 先读再动手。 在已有项目上开工，意味着先读交接文件——再拿现实核对它的说法，就地改正过期的行。
2. 落地就更新。 里程碑、决策、坑——立刻写下来，别等「今天结束再说」。过期的交接文件就是谣言。
3. 坑才是干货。 最有价值的几行，能让下一个会话避开已知的陷阱；「症状 → 原因 → 对策」这个格式，三周后再读依然管用。
4. 决策要带上理由。 「用 X」是事实；「用 X，因为 Y」才是决策，下一个会话可以尊重它，也可以有意识地重新审视。
5. 敏感事实不要写进去。 交接文件可能被同步或分享；凭据和个人信息放在专门的存储里，交接文件只指向位置。
6. 什么都标日期。 每条记录都带日期，读者才能判断它是否过期。

Live test (2026-09-14) / 实测

这条纪律已经用在真实跨会话项目上：handoff 文件承载了 3 代架构演进和 15+ 条决策，横跨 4 个工作会话；基于它做上手审计，发现缺了「怎么跑起来」一节——当小时就补上了。新会话只靠这个文件就能接着干，零考古。

如实说明局限

- 交接文件记录的是写入那一刻的事实；过期条目和缺失条目一样会误导——日期戳和「读时核验」步骤就是为这个准备的，文件日期早于最近一次大改动，就该怀疑它。
- 它替代不了版本控制：代码历史归 git；handoff 只装 git 装不了的东西（决策、理由、潜规则）。
- 单人短周期项目可能根本用不上；只要跨会话或跨人，这套纪律就值。

安装

npx skills add ChenneyZhuang/project-handoff

各 agent 的安装路径见 COMPATIBILITY.md。MIT 许可。v0.1.0——实测通过。