把需求拆成可检查的步骤

如果一句请求就能明确完成条件，不需要额外写一份规格文档。涉及多个入口、未定规则或跨会话工作时，才值得把决定留下来。

这里用一个尚未实现的教学需求演示：给本站工具目录增加文字搜索。示例不是宣布网站已具有这个功能。

先确定行为，再列修改文件

“加一个搜索框”只是控件描述，至少还有这些问题：

• 搜索名称，还是也搜索说明？
• 搜索和左侧分类叠加，还是互相重置？
• 没结果时显示什么？
• 刷新后是否保留搜索词？
• 是否向服务端发送查询？

若这些规则没定，Agent 即使写出了能输入的框，也未必做对功能。文件数量不能衡量需求是否清楚。

一份足够小的任务说明

下面是为演示选定的一组规则，不是通用最佳答案：

# 工具目录本地搜索
 
目标：访客能在现有工具卡片中按名称或说明找到工具。
 
行为：
- 去掉查询首尾空格，忽略英文大小写，按子串匹配。
- 当前分类与搜索条件取交集。
- 空查询显示当前分类的全部工具。
- 零结果显示“没有匹配的工具”，并允许清除查询。
- 仅当前页面状态；不改变 URL，不持久化，不上传查询。
 
不做：
- 不新增标签体系、模糊搜索、排序或搜索服务。
- 不改工具数据字段，不改变既有卡片目标地址。
 
交付：
- 实现及必要测试，桌面和手机检查。
- 本地 diff 与验证记录；不提交、不发布。

“仅当前页面状态”也有代价：分享链接不能保留查询。它是这份需求的取舍，需要你接受，而不是 Agent 自行认定最省事就一定正确。

提前写三个会失败的场景

使用一组隔离的教学测试数据，不依赖真实工具数量：

[
  {"name":"JSON Formatter","description":"格式化 JSON","category":"开发测试"},
  {"name":"DNS Lookup","description":"查询 DNS 记录","category":"网络检测"}
]

再补一个失败路径：查询输入 [ 时应作为普通字符处理，不能触发正则语法错误。这能帮助你提前决定使用普通字符串匹配，而不是拿用户输入直接构造正则。

这些预期必须来自需求，不能在实现后按照代码当前行为倒写。

计划按可验证产物拆，而不是按文件拆

合理的三个步骤是：

1. 确认数据流。 找到工具数据、分类导航和卡片的消费位置，确认哪些运行在服务端。
2. 实现筛选行为。 先用固定数据验证大小写、空白、分类交集和零结果；再接到现有目录。
3. 检查真实页面。 验证键盘输入、清除、分类切换、窄屏布局与卡片链接，运行项目既有测试。

“修改 A.tsx、修改 B.tsx、修改 C.tsx”不能解释为何这样拆，也无法说明完成第二步后能验证什么。涉及 Next.js 的服务端与客户端边界，还应先查当前版本文档，不要把整个页面无条件改成客户端组件。

发现新情况时怎样调整

如果调查发现分类只是锚点滚动，没有“选中分类”状态，原计划需要调整实现方案。但不能因此把“取交集”悄悄改为“搜索忽略分类”。

应报告：“现有分类行为与这份需求不同；实现交集筛选会改变导航交互。”先确认这项产品变化，再继续依赖它的工作。其他只读调查可以继续。

小任务与大任务的分界

改一句卡片文案，用一条请求即可；新增搜索行为，用上面的任务说明；引入账号、保存数据或第三方服务，还要先说明数据流、权限和成本。

计划的价值是让关键决定有依据、步骤可检查，不是让每个任务都多出一份长文档。