cs-build-handoff

交付计划

当计划本身就是产品时，交接就是交付。 前期所有工作都是为构建准备产物——地图、笔记、PRD、任务看板。这些都不是写给付费方看的；把一个他们从未打开过的画布链接发给他们，也算不上交付。

这份文档就是他们会收到的东西。

请在 cs-build-create-tasks 之后运行，此时地图、笔记、PRD 和任务都已齐备。

请阅读：codespring 技能中的 references/project-state.md 和 references/pitfalls.md，以及 cs-build-audit-codebase/references/plain-english-writeup.md——其中的措辞规则在这里同样适用。阅读水平按小学三年级掌握，不要出现文件路径、行话或框架名称。

---

0. 检查是否有内容可以交付

bash ../codespring/scripts/fetch-project.sh --out /tmp/cs-state
node ../codespring/scripts/state.mjs       /tmp/cs-state
node ../codespring/scripts/check-map.mjs   /tmp/cs-state

不要交付有缺漏的计划。 检查并明确说明以下内容是否缺失：

• 核心功能，每项都要有实际笔记
• 每项核心功能都有 PRD
• 任务已编号、排序，且每项都关联到某个功能
• 如果产品有用户界面，还要有模型图

缺少内容不是绕开它继续写的理由——回去把它补齐。唯一的例外是有意推迟的内容；这种情况应放在 “尚未决定的事项” 中，而不是悄悄略过。

1. 了解读者

通常是非技术背景的产品负责人，他们花了真金白银，心里忐忑不安。他们往往曾被之前的代理机构或项目伤害过。

为他们而写，不要为构建者而写。 以下两点会决定整份文档的语气：

• 正文里不要出现行话、文件路径、框架名称或任务 ID。 他们不需要知道 PRD 是什么，也能明白自己会得到什么。
• 说清楚它能为用户做什么，而不是它如何构建。 “她选择时长，应用就会运行这次训练”——而不是“训练控制器会读取训练架构”。

如果他们确实懂技术，清晰的表达不会让他们恼火。反过来就不一定了。

2. 撰写交付文档

只写一份文档。各部分按以下顺序排列，因为读者通常会按这个顺序提出问题。

我们要构建什么

用两到三段朴实的语言来写，尽可能采用他们自己的说法——直接从通话记录或笔记中提取表述。他们应该能认出自己的想法，而且感觉你把它说得比他们原先更清楚。

说明它要解决什么问题，以及服务于谁。暂时不要列出功能。

它能做什么

列出核心功能，每项用一两句话说明使用者实际能做什么。用他们日常说话时的叫法来命名，不要照搬地图上的分类。

如果有模型图，就把相关截图放在这里，放在它所展示的功能旁边。他们会最仔细地阅读这一部分。

你会看到什么

模型图：说明如何打开，或在哪里可以访问；并用一句话说明，它只是成品的草图，不是应用——目前其中的功能都不能使用，数据是虚构的；它的作用是在开始构建前，让他们先对整体样子发表意见。

如果有风格指南页面，也要附上，并说明它的用途：颜色、字体和间距都集中设置在一个地方，因此之后调整外观只需做少量工作，不必重新构建。

它是如何构建的

把任务列表整理成阶段，而不是任务。没人想读六十行内容。把任务归入已有的四五个阶段，并为每个阶段说明：要做什么、大致需要多久，以及完成后能实现什么。

这里有两点必须如实说明：

• 指出难点，并说明会先验证它，再围绕它构建界面。如果计划中的第一项任务是技术验证，就用一句话说明原因。
• 明确他们需要做什么。 内容、决策、评审、账号。这部分最容易被跳过，也是构建停滞最常见的原因。

除非双方实际商定过，否则不要给出整体交付日期。 说明各阶段的安排和顺序即可。

我们的假设

把我们替对方做出的每项假设都用通俗的话写明，并为每项附上一句理由。包括平台、范围、受众，以及任何从 v1 中删掉的内容。

这一部分能赢得信任，而不是消耗信任。对方不同意的假设，现在改起来成本很低，等开发完成后再改则成本很高；把假设摆出来，正是计划与猜测的区别。

我们尚未决定的事项

列出真正悬而未决的问题，以及**每个问题需要由谁回答。**具体说明做出决定后能推进什么：“内容工作开始前，我们需要你提供练习列表”就有行动指向；“待定”则没有。

首个版本不包含的内容

明确列出每项内容并说明原因，还要清楚标记为以后再做，而不是永远不做。没有明说的删减，一旦对方看到成品，就会被当成违背承诺。

下一步该做什么

按编号列出具体、简短的步骤。通常包括：

1. 打开计划（链接）
2. 查看原型图（链接或命令）
3. 回复“我们尚未决定的事项”中列出的内容
4. 在开发工具中打开项目，从第一个任务开始

假设对方从未使用过这些工具。**提供实际链接和实际的第一个任务，**而不是对它们的描述。

所有内容的位置

简短列出参考信息：计划链接、原型图、文档、任务看板，以及联系人。

3. 以对方真正会阅读的形式交付

询问对方，或根据你对他们的了解来选择。文档内容不变，只是交付形式不同：

• 可渲染的页面，方便对方打开和分享——通常是最佳默认选项，也能让截图直接显示在文中。
• Markdown 文件，放在代码仓库中，适合熟悉仓库的人。
• 邮件或消息正文，适合内容较短，且对方更可能在收件箱里阅读，而不是点击链接的情况。

无论采用哪种形式，**都要把截图放进去。**没有图片的计划读起来像账单；有图片的计划读起来像产品。

4. 在 CodeSpring 中记录

这样下次会话就能知道已经向客户说明了什么：

• 将项目描述设为通俗易懂的“我们要构建什么”段落，让对方打开画布时能看到熟悉的内容。
• 在项目信息或备注中记录交接日期和已发送的内容。
• 如果列出了假设或未决问题，确保它们也记在相关功能的备注中——否则它们只会留在一份没人再看的文档里。

codespring mindmap set-info --title "..." --description "<the plain-English paragraph>"

5. 说明你发送了什么

用三句话告诉委托此事的人——通常不是客户本人——发送了什么、正在等待客户提供什么，以及收到回复后会做什么。

---

做得好的标准

• 客户读完整份资料后，能够向别人讲清楚自己的应用是什么。
• 文中没有术语、文件路径、任务 ID 或框架名称。
• 原型图截图已放入文档，并紧挨着对应的功能说明。
• 开发顺序按阶段及其能推进的事项来组织，而不是列出六十行。
• **明确写出假设，**并为每项说明理由。
• **明确列出对方需要提供的内容，**并说明这些内容能推进什么。
• 明确说明删减项是以后再做，而不是默不作声。
• 下一步按编号列出，并附上真实链接和实际的第一个任务。
• 通俗易懂的摘要已添加到 CodeSpring 项目中，让对方打开画布时能看到熟悉的内容。