project-handoff-zh

name	project-handoff-zh
description	生成和更新中文项目接班与上下文入口文档，用于项目切换 AI、长期科研/工程项目丢失上下文、需要沉淀项目统一认知、AI接班手册、工作流细化、单文件记忆桥、三层记忆入口、总览索引、当前状态补丁、下一步优先级和文档更新规则时使用。Use when: 接班手册、新AI继承、项目统一认知、工作流细化、上下文恢复、交接文档、科研项目交接、AI换人继续项目、单文件记忆、记忆文档分层、AGENTS/CLAUDE规则整理。

Project Handoff Zh

Project structure gate / 文件树结构门禁

只要本工作流将初始化或重组项目，或新建、移动应用、服务、包、模块、页面、API、研究步骤、实验、流水线、测试、文档或多文件产物树，必须先使用 project-structure-architect。

1. 开始前：读取适用的 AGENTS.md、PROJECT_STRUCTURE.md、.project-structure.yaml 和现有文件树，锁定项目类型、蓝图及唯一合理路径。
2. 运行中：每次新增或移动文件前先判断职责、所有者、复用范围和对应测试；禁止同义目录、根目录堆放、跨层混放及无关重组。
3. 阶段收口：纵向切片或阶段完成后检查结构漂移；新项目或重大重组更新结构文档，最终运行结构审计。出现 BLOCK 时停止结构性写入并先修正或询问用户。

纯内容编辑且目标路径已由用户或现有规范唯一确定时，可不重复调用。

目标

为长期项目生成或更新“新 AI 可直接接手”的中文入口文档。核心不是复述历史流水账，而是提炼当前有效事实、主线边界、关键入口、下一步优先级和禁止误解的内容。

两种入口结构

轻量三件套

适合中小项目：

• 项目统一认知.md：项目定位、主线 claim、目录角色、边界和禁止误解。
• AI接班手册.md：下一位 AI 的总入口，说明当前状态、关键文件、有效结论、下一步。
• 工作流细化.md：整体实验/开发链路；只有阶段、入口、指标或验收标准变化时更新。

三层记忆入口

适合长期比赛、科研实验、性能优化、多分支工程：

1. 第一层：AGENTS.md / CLAUDE.md / 项目根规则文件。只写硬规则、启动读取顺序、分支规则、禁止事项。
2. 第二层：单文件记忆桥或一屏总览，通常放在 资料/项目入口/ 或 docs/project-entry/。新项目优先用 项目记忆总览.md，至少包含 尝试方法、计划、脚本/命令、结果、经验；材料变多后可拆为：
   • 计划总览.md
   • 尝试方法总览.md
   • 脚本命令总览.md
   • 结果总览.md
   • 经验总览.md
3. 第三层：详细档案目录，每轮一个文件，通常为 计划/、尝试方法/、脚本/、结果/、经验/。

当历史材料超过约 500 行、关键词容易歧义、或多轮实验不断追加时，优先使用三层记忆入口。第二层必须短，像地图；单文件记忆桥只保留当前有效事实和跳转指针，第三层才保存完整证据。

上下文卫生

三层入口不仅整理文档，也整理会误导 AI 的工程上下文：

• 远程分支、本地分支、worktree、IDE 可见目录都应只保留冻结基线、当前最优基线和用户点名保留项。
• 清理前必须先归档：保存 refs 清单、必要时创建 git bundle --all，并给冻结/当前最优基线打 tag。
• 已记录结果的短期实验分支和 worktree 应及时删除；保留价值写入第二层或第三层，而不是靠分支名提醒。
• 若用户要求“保持干净”，同时处理远程和本地，避免旧分支、旧目录、旧入口继续污染后续判断。
• 新实验默认从第二层写明的当前最优基线派生；除非用户明确要求历史消融，不从旧侧枝开始。

工作流

1. 先读取项目现有入口文档、近期结果文档和 tracing/记录文件。
2. 区分四类内容：当前有效事实、历史背景、过期结论、下一步行动。
3. 选择入口结构：中小项目用轻量三件套；长期迭代项目用三层记忆入口。
4. 若使用轻量三件套，更新 AI接班手册.md、项目统一认知.md、工作流细化.md。
5. 若使用三层记忆入口，先更新根规则文件的启动读取顺序，再更新单文件记忆桥或拆分后的总览。
6. 同步检查上下文卫生：分支、worktree、入口文件和历史目录是否仍会误导下一轮。
7. 只在第三层或 tracing 记录完整流水、命令、raw 路径和失败细节。
8. 若新增/删除/改名 skill 或修改 skill 触发描述，同步更新 skills/README.md 或对应注册清单。
9. 最后输出更新了哪些文件、当前交接口径和下一位 AI 的阅读顺序。

内容判断

• 写入 AI接班手册.md：冻结版本、当前最好开发分支、关键结果、下一步优先级、禁止继续的低价值方向。
• 写入 项目统一认知.md：项目定义、平台决策、主线 claim、创新口径、适用边界、当前统一结论。
• 写入 工作流细化.md：阶段划分、运行入口、数据集/算法/指标口径、验收标准、汇总路径。
• 写入 计划总览.md：当前目标、强基线、下一步优先级、gate、止损条件。
• 写入 尝试方法总览.md：候选路线分类、代表轮次、能否继续、禁止重试路线。
• 写入 项目记忆总览.md：新项目的单文件记忆桥，按 尝试方法、计划、脚本/命令、结果、经验 汇总当前有效事实和第三层跳转。
• 写入 脚本命令总览.md：启动命令、实验命令、常用检查命令、输出路径和废弃命令。
• 写入 结果总览.md：官方/正式结果、当前最优、稳定中位、负例和数据解释规则。
• 写入 经验总览.md：已成立经验、歧义词表、禁止误解、下次必须继承的新规则。
• 写入第三层档案或 tracing：本次修改、用户问题和回答、阶段结论、问题与解决方案。

必须避免

• 不要把 项目统一认知.md、工作流细化.md、单文件记忆桥或第二层总览写成实验日志。
• 不要让入口文档只列文件名而不说明“当前有效事实”。
• 不要把探索分支直接写成冻结主线，除非已有明确冻结结论。
• 不要覆盖用户已有记录；只追加或补丁式更新。
• 不要忘记同步 README、注册清单、目录树等二级入口文件。
• 不要只按关键词检索后下结论；若关键词有歧义，先在 经验总览.md 建术语分类，再读对应原文。
• 不要只清远程而留下大量本地旧分支、旧 worktree 或旧入口；这些同样会污染 AI 上下文。

推荐读取顺序

轻量三件套：

1. AI接班手册.md
2. 项目统一认知.md
3. 工作流细化.md
4. Tracing/修改记录.md
5. Tracing/结论记录.md
6. 最近一个 step/result/report/skill-output 文档

三层记忆入口：

1. 根规则文件：AGENTS.md / CLAUDE.md
2. 第二层入口：优先读 项目记忆总览.md；若已拆分，再读 计划总览.md、尝试方法总览.md、脚本命令总览.md、结果总览.md、经验总览.md
3. 第三层相关原文：只读本轮相关的计划、尝试方法、脚本、结果、经验文件
4. 当前要修改的源码、测试和配置

资源

• 详细写作规范：references/handoff-doc-rules.md
• 经验沉淀规则：references/experience-sync-rules.md
• AI接班手册 模板：assets/AI接班手册模板.md
• 项目统一认知 模板：assets/项目统一认知模板.md
• 工作流细化 模板：assets/工作流细化模板.md
• 三层记忆入口 模板：assets/三层记忆入口模板.md