如何跑出一个快速、有效的 Demo

做 Demo 的目标，不是在最短时间里堆出最多代码，而是用尽可能短的路径，验证项目中最关键的假设。

一个真正有效的 Demo，至少应该回答三个问题：核心流程能不能跑通？方案中的关键接口是否合理？如果方向成立，后续能不能继续扩展？如果只是“页面能打开”，却无法解释输入、处理过程和输出，那么它更像一次性的样品，而不是可以继续生长的项目起点。

一、先把项目看成一条流程

无论项目大小，本质上都可以抽象成一条合乎逻辑的流程：输入进入系统，经过若干处理节点，最后得到输出。

每个节点都应该有清楚的职责和边界：

• 它接收什么输入？
• 它负责完成什么事情？
• 它产出什么结果？
• 失败时会返回什么状态？
• 下一个节点依赖它的哪些信息？

例如，要做一个“自动生成渠道周报”的 Demo，可以先拆成四个节点：

1. 读取数据：输入两份 CSV，输出统一字段的数据表；缺少必填列时直接报错。
2. 计算指标：输入清洗后的数据，输出销售额、环比和异常渠道等结构化 JSON。
3. 生成解读：输入指标 JSON，调用模型生成一段 Markdown 分析。
4. 导出报告：输入 Markdown 和图表数据，输出最终周报。

这样拆分后，如果模型生成的文字不稳定，只需要修改第三个节点；如果 CSV 格式发生变化，也只需要调整第一个节点。其他部分仍然可以独立测试和复用。

这种拆分看起来会增加一点前期工作，实际上是在为后面的修改节省时间。项目越大，边界清晰的价值越明显：多人协作时可以分别负责不同节点；性能优化时可以替换单个实现；出现错误时也更容易定位，而不必在一整块耦合代码里反复试探。

Agent 工作流也是如此。以 LangGraph 一类框架为例，每个 Node 负责一项明确任务，调度逻辑再根据状态和运行结果决定下一步去哪里。只要节点之间的输入输出足够稳定，就可以替换模型、工具或实现方式，而不必推翻整条链路。

二、方案设计：先借经验，再做最小闭环

1. 固定业务：优先参考成熟项目

如果要做商城、游戏或后台系统这类边界相对明确的业务，最好先研究成熟项目的结构。成熟方案通常是多轮犯错之后沉淀下来的结果，能帮助我们提前避开一些常见问题。

可以把参考项目当作“基台”，但不要直接照搬全部功能。更有效的做法是：

1. 明确这次 Demo 只验证哪个业务问题。
2. 找出完成验证所需的最短关键路径。
3. 为路径上的节点定义输入、输出和验收条件。
4. 只实现一条端到端的最小纵向切片。
5. 跑通后再决定哪些部分值得扩展或抽象。

以商城 Demo 为例，如果这次只想验证“用户能否顺利完成一次下单”，最小链路可以是：选择一个商品 → 提交订单 → 模拟库存确认 → 模拟支付成功 → 展示订单结果。优惠券、退款、真实支付、会员体系和复杂权限都可以暂时不做。

这条 Demo 的验收条件也很具体：用户提交订单后，系统能生成唯一订单号，库存失败时不会进入支付步骤，支付成功后订单状态会正确更新。它验证的是下单链路，而不是“做出一个完整商城”。

如果没有合适的参考项目，也可以先和 Codex 讨论方案。但当项目准备继续做大时，不应只让 Agent 不断“改到能跑”。更稳妥的方式，是先让它输出架构、节点契约和验证方法，再按节点逐步实现。这样既方便自己 Review，也方便后续定位错误和审查代码变更。

2. 探索型任务：把一次对话沉淀成可复用能力

如果任务是资料搜集、数据处理、Tool、脚本或 Skill，做法可以更偏探索。你可以带着 Agent 完整跑一遍真实任务，观察它在哪里需要重复提示、哪里容易出错、哪些工具调用最稳定。

第一次完成任务只是起点。更有价值的是把有效过程沉淀为：

• 明确的输入格式；
• 稳定的处理步骤；
• 可检查的中间产物；
• 失败后的恢复方法；
• 可以再次调用的脚本、模板或 Skill。

例如，第一次让 Agent 从 20 篇文章中整理调研报告时，可能需要不断补充要求：“过滤重复链接”“保存原文”“每个结论注明来源”“请求失败后继续重试”。任务跑通后，就可以把这些要求固化下来：脚本负责下载、去重和缓存，Skill 负责规定筛选与总结步骤，最终再输出统一格式的报告。下一次只需要换一组链接，而不必重新教 Agent 完整流程。

三、落地 Demo：给 Agent 足够清楚的边界

1. 在 AGENTS.md 中写清规则

Agent 会主动寻找满足目标的路径。如果目标清楚、边界模糊，它仍可能通过你不希望的方式完成任务。因此，AGENTS.md 不应只写风格偏好，还应该写清：

• 本次任务的目标和非目标；
• 允许修改与禁止修改的目录；
• 模块之间必须保持的接口契约；
• 必须执行的测试与验收标准；
• 哪些大范围改动需要先征得同意。

规则不是越多越好，而是要能约束真正高风险的决策。

例如，一个 CSV 导入 Demo 的规则可以写成：

目标：完成 CSV 导入，并返回成功条数和错误行。
允许修改：src/importer/、tests/importer/。
禁止修改：数据库结构、登录模块、现有解析库版本。
输入契约：UTF-8 CSV，必须包含 name 和 email 两列。
输出契约：{ imported: number, errors: Array<{ row, reason }> }。
验收：正常文件、空文件、缺少字段和重复邮箱测试全部通过。
大改规则：需要替换解析库或修改数据库时，先说明原因并等待确认。

这段规则没有限制 Agent 的每一个实现细节，但把影响范围、接口和完成标准都固定了下来。

2. 一次只完成一个可验证节点

不要一开始就让 Agent 同时完成架构、前端、后端、部署和文档。更有效的节奏是：先定义一个节点，再实现、测试、Review，确认结果后继续下一个节点。

这种方式看似更慢，实际上能显著减少返工，也能防止错误沿着整条流程扩散。

仍以 CSV 导入为例，可以先只完成“读取文件并报告字段错误”，确认这个节点稳定后，再增加数据校验，最后才接入数据库。每一步都有可以运行的测试，即使后一步失败，也不会破坏前面已经确认的结果。

3. 人必须保留 Review 能力

使用 Agent 团队并不意味着放弃对代码的理解。至少要能回答：每个节点为什么存在？输入输出是否合理？失败会影响哪里？当前实现是否超出了 Demo 的验证范围？

如果无法解释这些问题，项目即使暂时能跑，后续也很难维护。

4. 跑偏时先收紧边界

发现 Agent 跑偏时，可以依次采取这些措施：

1. 暂停继续修改，明确指出偏离的位置。
2. 重申目标、禁止项和需要保留的接口。
3. 把任务缩小到一个可以独立验证的节点。
4. 只有当对话上下文已经严重混乱时，再开启新对话。
5. 确实需要大改时，显式授权范围，并要求先给出迁移方案。

比如原任务只是“给周报增加 Excel 导出”，Agent 却准备顺带重写数据层，此时不必让它继续尝试。可以直接收紧为：“保留现有数据结构，只新增一个导出节点；如果当前接口无法支持，先列出缺口，不要修改上游模块。”

新开对话或全面重做会消耗额外上下文和 Token，也容易丢失已经确认的约束，所以它们应该是最后手段，而不是默认操作。

四、一份可以直接使用的 Demo 检查清单

开始前：

• 这次 Demo 只验证哪一个核心问题？
• 最短的端到端路径是什么？
• 哪些内容明确不在本次范围内？

实现时：

• 每个节点是否都有明确的输入和输出？
• 每个节点能否独立测试和替换？
• Agent 是否只修改了允许修改的范围？
• 是否保留了关键假设、失败记录和验证结果？

完成后：

• Demo 是否真的验证了最初的问题？
• 自己能否解释整条链路和关键取舍？
• 哪些步骤值得沉淀为脚本、模板或 Skill？
• 如果下一次再做，能否直接复用这套流程？

结语

快速有效的 Demo，并不等于少做设计。它真正强调的是：尽早确定边界，只实现最关键的闭环，并让每一步都可以检查、替换和复用。

架构清晰之后，Agent 才能真正放大效率；否则，它只会更快地放大不确定性。