Claude Code 任务范围：从模糊需求到提交

模糊的功能需求为何浪费时间\n\n一句模糊的需求听起来无害：“加一个更好的搜索”、“让入职更顺畅”、“用户需要通知”。在真实团队里，它通常以一行聊天、带箭头的截图或半记得的客户通话出现。大家都同意，但每个人心里想的都不一样。\n\n成本会在后面显现。当范围不清晰时，人们基于猜测去实现。第一次演示变成另一轮澄清：“这不是我的意思”。工作被重做，变更悄然膨胀。设计调整触发代码变动，进而触发更多测试。评审放慢，因为模糊的变更难以验证。如果没人能定义“正确”的样子，评审就变成了行为争论而不是质量检查。\n\n你通常可以在早期识别出模糊任务：\n\n- 没有逐步示例说明用户应该能做什么\n- 没有边缘情况（空状态、权限、错误）\n- “以防万一”式的工作膨胀成巨大的 PR\n- 评审意见在争论行为而不是实现\n- “我们边做边想”变成了计划\n\n一个范围明确的任务会给团队一个终点：清晰的验收标准、最小化的 UI 和 API 计划，以及明确的非包含范围。这就是“改进搜索”和一个易于构建与评审的小改动之间的区别。\n\n一个实用习惯：把“完成定义”与“可选项”分开。“完成”是一份可运行的简短检查列表（例如：“搜索按标题返回结果，空时显示‘无结果’，并将查询保存在 URL 中”）。“可选项”是那些可以等的内容（同义词、排名调整、高亮、分析）。提前标注这些可以防止无意的范围膨胀。\n\n## 从结果开始，而不是解决方案\n\n模糊需求常以建议的修复开始：“加个按钮”、“换个流程”、“用不同模型”。先暂停，把建议翻译成结果。\n\n一个简单的格式有帮助：“作为 [用户]，我想要 [做某事]，以便 [达成某目标]。”保持简明。如果你不能一句话说清楚，那它仍然太模糊。\n\n接着描述完成后用户发生了什么变化。关注可见行为，而不是实现细节。例如：“提交表单后，我看到确认信息，并且能在列表中找到新记录。”这会创建一个清晰的终点，也更难让“再做一个小调整”偷偷溜进来。\n\n也写下保持不变的内容。非目标保护你的范围。如果需求是“改进入职流程”，非目标可以是“不会重做仪表盘”或“不会修改定价层逻辑”。\n\n最后，先选择一条主要路径：先支持一个端到端切片以证明功能可行。\n\n示例：不要写“到处加快照”，写成：“作为项目所有者，我可以恢复应用的最新快照，以便撤销糟糕的改动。”非目标：“不做批量恢复、不做 UI 重新设计”。\n\n## 问几个能移除歧义的问题\n\n模糊需求并非缺少工作量，它缺少决策。\n\n从那些会悄悄改变范围的约束开始。截止日期重要，访问规则和合规需要同样重要。如果你在有层级和角色的平台上构建，早点决定谁能使用此功能、在哪个计划下可用。\n\n然后要求一个具体示例。截图、竞品行为或之前的工单会揭示“更好”实际意味着什么。如果请求者没有示例，问他们重现上次感到痛点的场景：在哪个界面、点了什么、期望看到什么？\n\n边缘情况是范围爆炸的源头，所以早点点出大项：空数据、校验错误、网络慢或失败、以及“撤销”真正意味着什么。\n\n最后，决定如何验证成功。没有可测试的结果，任务就会变成主观意见。\n\n这五个问题通常能移除大部分歧义：\n\n- 谁可以访问（层级与角色）？\n- 截止日期是什么，最小可接受版本是什么？\n- 一个期望行为的具体示例是什么？\n- 空状态、错误与慢连接时应该如何表现？\n- 我们将如何确认它有效（具体准则或指标）？\n\n示例：“为客户添加自定义域”在明确属于哪个层级、谁可以配置、托管位置是否影响合规、无效 DNS 显示什么错误、以及“完成”如何定义（域验证通过、HTTPS 激活、并有安全回滚方案）后，就会更清晰。\n\n## 把凌乱笔记转成验收标准\n\n凌乱的需求混合了目标、猜测和半记得的边缘情况。你的任务是把这些变为任何人无需读心都能测试的陈述。同一组准则应该指导设计、编码、评审和 QA。\n\n一个简单的模式能保持清晰。你可以使用 Given/When/Then，或等价的短要点。\n\n### 快速验收标准模板\n\n把每条准则写成一个测试化的句子：\n\n- 给定 一个起始状态，当 用户做 X，那么 Y 发生。\n- 包含校验规则（允许哪些输入）。\n- 至少包含一个失败案例（用户看到什么错误）。\n- 定义“完成信号”（QA 检查什么、评审期望什么）。\n\n现在应用它。假设笔记写着：“让快照更容易。我想在最后一次改动出问题时回滚。”把它转成可测试语句：\n\n- 给定一个有 2 个快照的项目，当 我打开 Snapshots，那么 我看到两个快照并显示时间和简短标签。\n- 给定一个快照，当 我点击回滚并确认，那么 项目恢复到该快照且应用成功构建。\n- 给定我不是项目所有者，当 我尝试回滚，那么 我看到错误且无任何改变。\n- 给定回滚正在进行，当 我刷新页面，那么 我仍然能看到状态和最终结果。\n- 给定回滚失败，当 操作终止，那么 我看到清晰的提示且当前版本保持活动。\n\n如果 QA 能运行这些检查，评审能在 UI 和日志中验证它们，你就可以开始规划 UI 与 API 工作并把任务拆成小提交。\n\n## 起草最小化的 UI 计划\n\n最小化的 UI 计划是一种承诺：最小的可见改动，用来证明功能可行。\n\n从点明哪些界面会变化以及用户在 10 秒内会注意到什么开始。如果需求是“让它更容易”或“清理一下”，把它翻译成一个可指认的具体改动。\n\n把它写成一张小型地图，而不是重设计。例如：“订单页：在表格上方加一个筛选栏”，或“设置：在通知下加一个开关”。如果你无法点名界面与确切元素，范围仍不清楚。\n\n### 定义关键 UI 状态\n\n大多数 UI 改动需要几个可预期的状态，只需写出适用的那些：\n\n- 加载\n- 空状态\n- 错误（是否存在重试）\n- 成功（提示、内联消息、更新后的列表）\n\n### 确认用户会看到的文案\n\nUI 文案也是范围的一部分。捕获必须被确认的标签和消息：按钮文本、字段标签、帮助文本和错误信息。如果文字尚未确定，就标注为占位并说明谁来确认。\n\n保留一个小的“不做项”用于任何非必须的优化（响应式调整、高级排序、动画、新图标）。\n\n## 起草最小化的 API 与数据计划\n\n一个范围明确的任务需要 UI、后端与数据之间的小而清晰的契约。目标不是设计整个系统，而是定义最小的一组请求和字段来证明功能可行。\n\n先列出你需要的数据及其来源：可读取的现有字段、必须存储的新字段，以及可以计算得出的值。如果你不能为每个字段指明来源，就还没有计划。\n\n保持 API 面小。对很多功能来说，一次读和一次写就足够：\n\n- GET /items/{id} 返回渲染页面所需的状态\n- POST /items/{id}/update 仅接受用户可修改的字段并返回更新后的状态\n\n把输入输出写成简单对象，而不是段落。注明必需字段与可选字段，以及常见错误的处理（未找到、校验失败）。\n\n在动数据库之前快速做一次鉴权检查。决定谁能读谁能写，并用一句话说明规则（例如：“任意已登录用户可读，只有管理员可写”）。跳过这一步通常会导致返工。\n\n最后，决定哪些必须存储，哪些可以计算。一个简单规则：存事实，计算视图。\n\n## 使用 Claude Code 产出范围化任务\n\nClaude Code 在你给出清晰目标和紧箱子时表现最佳。先粘贴凌乱的请求和任何约束（截止日期、受影响用户、数据规则）。然后请求一个包含以下内容的范围化输出：\n\n1. 用通俗语言重述范围并给出简短的验收清单。\n2. 一系列小提交（目标为 3 到 7 个），每个提交都有明确结果。\n3. 每个提交可能触及的文件或文件夹，以及这些文件内会做什么改动。\n4. 每个提交的简短测试计划（一个正常路径和一个边缘情况）。\n5. 明确的不在范围内项。\n\n在它回复后像评审一样阅读。如果看到诸如“提升性能”或“更干净”之类的模糊措辞，要求把它们改为可衡量的描述。\n\n### 小示例（什么是“好”的样子）\n\n请求：“添加暂停订阅的方式。”\n\n一个范围化版本可能写成：“用户可以暂停 1 到 3 个月；下次计费日期随之更新；管理员可以看到暂停状态。”不在范围内：“不改变按比例计费”。\n\n从这里开始，提交计划变得可执行：一个提交负责 DB 与 API 结构，一个提交负责 UI 控件，一个提交负责校验与错误状态，一个提交负责端到端测试。\n\n## 把工作拆成小且易评审的提交\n\n大变动掩盖 bug。小提交让评审更快、回滚更安全，并帮助你在偏离验收标准时更早察觉。\n\n一个有用的规则：每个提交应解锁一个新行为，并包含一个快速验证其有效性的方式。\n\n一个常见的顺序如下：\n\n- 数据模型或迁移（如需）及测试\n- API 行为与校验\n- UI 联动，含空与错误状态\n- 只有在必需时再加日志或分析，并做小范围的美化\n\n保持每个提交聚焦。避免“顺手做”的重构。保持应用端到端可运行，即使 UI 很基础。除非有充分理由，不要把迁移、行为和 UI 捆绑到一个提交里。\n\n## 演练：“导出报表”\n\n某位干系人说：“我们能加个导出报表吗？”这背后有很多选择：哪个报表、哪种格式、谁可导出、如何交付。\n\n只问会改变设计的问题：\n\n- v1 包含哪些报表类型？\n- v1 要哪种格式（CSV、PDF）？\n- 谁可以导出（管理员、特定角色）？\n- 是直接下载还是邮件发送？\n- 有无限制（最大日期范围、行数上限、超时）？\n\n假设答案是：“销售汇总报表、仅 CSV、经理角色、直接下载、最长 90 天”。现在 v1 的验收标准就具体了：经理在销售汇总页点击导出；CSV 与页面表格列一致；导出遵循当前筛选；超出 90 天显示清晰错误；对于最多 5 万 行，下载在 30 秒内完成。\n\n最小化 UI 计划：在表格操作旁增加一个导出按钮，生成时显示加载状态，出错时提示用户如何修复（如“请选择 90 天或更短时间范围”）。\n\n最小化 API 计划：一个端点接收筛选并返回生成的 CSV 文件响应，重用表格查询并在服务端强制执行 90 天规则。\n\n然后用几个紧凑的提交交付：先实现固定的正常路径端点，再接 UI 联动，然后加校验与用户错误提示，最后加测试与文档。\n\n## 常见的范围化错误（以及如何避免）\n\n### 隐含需求溜进来\n\n“添加团队角色”类请求常藏着邀请、编辑和已存在用户如何处理的规则。如果你发现自己在猜，就把假设写下来并把它变成问题或明确规则。\n\n### UI 美化混进核心行为\n\n当一个任务同时包含“让它工作”和“让它好看”时，团队会损失几天。把首轮任务聚焦在行为与数据上。把样式、动画和间距留到后续任务，除非它们是使用功能所必须的。\n\n### 你试图在 v1 解决所有边缘情况\n\n边缘情况重要，但并非所有都要在初版解决。处理那些会破坏信任的（重复提交、冲突编辑），把其余清楚标注为后续任务。\n\n### 错误状态与权限被推到“以后”\n\n如果你不把它们写下来，就会漏掉。至少在验收标准中包含一条不良路径和一条权限规则。\n\n### 无法验证的准则\n\n避免使用“更快”或“更直观”这样的描述，除非你给出数字或具体检查项。用能在评审中证明的内容替代它们。\n\n## 开始编码前的快速清单\n\n把任务钉牢，让队友能在不读心的情况下评审和测试：\n\n- 结果与非目标：一句话描述结果，外加 1–3 个明确的非目标。\n- 验收标准：5–10 条可测试检查，以通俗语言表述。\n- UI 状态：最小的加载、空、错误、成功状态。\n- API 与数据注记：最小端点形态与任何数据变更，以及谁可读/写。\n- 提交计划与测试：3–7 个提交，每个带快速验证。\n\n示例：“添加已保存搜索”变成“用户可以保存筛选并在以后重新应用”，非目标如“不共享、不改排序”。\n\n## 下一步：构建时保持范围稳定\n\n一旦你有了范围化的任务，就去保护它。开始编码前，与提出者快速复核：\n\n- 朗读验收标准并确认与期望一致。\n- 确认权限、空状态和失败行为。\n- 再次确认不在范围内的项。\n- 就满足准则的最小 UI 与 API 改动达成一致。\n- 决定如何演示以及什么算“完成”。\n\n然后把准则存放在工作发生的地方：工单、PR 描述，以及团队常看的任何地方。\n\n如果你在 Koder.ai (koder.ai) 上构建，把计划先锁定再从计划生成代码会有帮助。Planning Mode 很适合这种工作流，快照和回滚在你需要尝试某种方法并回退时能保护实验安全。\n\n当在构建过程中冒出新想法时，保持范围稳定：把它们写到后续清单里，如果它们改变了验收标准就暂停并重新范围化，确保每次提交都对应一条验收准则。