project-handoff

Readme

# project-handoff 项目交接

Make the next session as smart as this one: a dated handoff file that carries current state, decisions with their reasons, and pitfalls as symptom → cause → fix.

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

## Why / 为什么

Long projects die in chat history: context that matters lives in messages that scroll away, get compressed, or belong to a session that has ended. `handoff` — one of the most-installed agent skills (797k+ installs) — exists because almost everyone hits this. This skill is the same discipline, bilingual and with a stricter pitfall format.

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

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

Popular handoff skills (e.g. mattpocock's, 790k+ installs) compact the *current conversation* into a temp-directory document for the next agent session. That solves session-to-session continuity. This skill solves a different problem: a **persistent, version-controlled handoff.md living in the project itself** — accumulating decisions and pitfalls across weeks, readable by humans and agents, surviving even when no conversation produced it. Use both together if you like; they compose.

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

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

```markdown
# 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. **Read before you build.** Starting work on an existing project means reading the handoff first — and verifying its claims against reality, correcting stale lines in place.
2. **Update when it lands.** Milestone, decision, pitfall — written immediately, not "at the end of the day". A stale handoff is a rumor.
3. **Pitfalls are the payload.** The most valuable lines save the next session from a known trap; symptom → cause → fix is the format that survives being read three weeks later.
4. **Decisions carry their why.** "Use X" is a fact; "Use X because Y" is a decision the next session can respect or consciously revisit.
5. **Sensitive facts stay out.** The handoff may be synced or shared; credentials and personal details live in dedicated stores, and the handoff points at where.
6. **Date everything.** Every entry carries a date so the reader can judge staleness.

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

The discipline was applied to a real cross-session project: the handoff file carried 3 architecture generations and 15+ decisions across 4 working sessions; the onboarding audit it enabled found a missing "run it" section — which was fixed the same hour. New sessions resumed from the file alone, zero archaeology.

该纪律已在一个真实跨会话项目上应用：handoff 文件承载了 3 代架构演进与 15+ 条决策，横跨 4 个工作会话；基于它的上手审计发现缺失的"怎么跑起来"一节——当小时修复。新会话仅凭文件即可续作，零考古。

## Honest limitations / 如实说明局限

- A handoff file records what was true when written; stale entries mislead as easily as missing ones — the dated entries and the read-verify step exist for this, and a pack older than the last big change deserves distrust.
- It is not a substitute for version control: code history lives in git; the handoff carries only what git cannot (decisions, reasons, unwritten rules).
- Solo short-lived projects may never need one; the discipline pays off on anything spanning multiple sessions or people.

交接文件记录的是写入时刻的事实；过期条目和缺失条目一样会误导——所以有日期戳和"读时核验"步骤，日期早于最近大变更的文件应被怀疑。它不能替代版本控制：代码历史归 git，handoff 只装 git 装不了的（决策、理由、潜规则）。单人短周期项目可能用不上；跨会话或跨人的项目才见效。

## Install / 安装

```bash
npx skills add ChenneyZhuang/project-handoff
```

Per-agent paths: [COMPATIBILITY.md](COMPATIBILITY.md). MIT. v0.1.0 — live-tested.

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