discovery

探索——先揭示隐藏的约束

导致 Agent 输出不佳的最大原因是缺少上下文。在敲定决定之前，先列出你尚不了解的内容并加以说明。

探索的 7 个维度

对于任何非平凡请求，都要逐一检查以下维度，并将发现记录在报告的“Context”部分：

1. 谁依赖这项内容？

• 还有哪些服务／团队会使用你要修改的内容？
• 是否有公开用户（开放 API、OSS 用户）？
• 如果破坏兼容性，是否有弃用方案？

在仓库以及你有权访问的任何同级仓库中搜索：grep -rE "import.*<your-module>|require.*<your-module>"。

2. 当前规模如何，6 个月后又会怎样？

• 当前流量：每秒请求数、每秒查询数、MB／天、日活用户数
• 存储：主表中的行数、磁盘占用
• 成本：每月 LLM 支出、基础设施支出
• 6 个月预测：线性？指数级？未知？

如果未知，请写明：“规模未知——继续之前请向用户确认。”

3. 哪些内容绝对不能变？

• 现有 API 契约（向后兼容期限）
• 报表／BI 所引用的数据库架构列
• 其他工具使用的文件格式
• 法规承诺（审计日志保留期限、SLA RPO／RTO）

4. 预算是多少？

• 每月成本上限（LLM + 基础设施）
• 人力：1 人任务还是跨团队工作
• 时间安排：“必须在 X 前发布”还是“最好在 Y 前完成”

如果未说明，默认采用“小型项目规模、1 个工程师周、每月预算 <$200”。在报告中说明此默认值，以便用户纠正。

5. 哪种故障模式最重要？

询问：“如果此功能在凌晨 3 点出故障，会触发什么告警？”

• 数据丢失 → 严重
• 给用户错误答案 → 高
• 响应缓慢 → 中
• 糟糕的用户体验（外观问题）→ 低

故障模式决定投入程度（例如，是否需要金丝雀发布？断路器？还是只需功能开关？）。

6. 已经尝试过什么？

• 搜索 Beads：bd search "<keyword>"——之前尝试过这件事吗？
• 搜索文档／决策记录：此主题是否有已被取代的 ADR？
• 搜索 lessons.md：过去是否有关于这种模式的经验教训？

如果已有相关工作，就在此基础上继续。不要重复劳动。

7. 谁来决定？

• 是否需要 CTO 批准（gate:plan、gate:ship）？
• 是否需要合规审查人员（金融科技领域的 PCI、医疗领域的 HIPAA）？
• 是否需要 RFC（涉及多个团队的决策）？

输出

在报告开头添加探索部分：

## Context

- **Consumers:** <list, or "unknown — TBD with user">
- **Scale:** <today, 6mo projection>
- **Frozen contracts:** <list, or "none identified">
- **Budget:** <cost + time + people>
- **Failure-mode tier:** Critical | High | Medium | Low
- **Prior work:** <links to ADRs/lessons, or "none found">
- **Decision-makers:** <gate or RFC required>

何时跳过

• nano project_size——探索属于额外开销。跳过并记录：“nano——根据技能规则跳过探索。”
• 纯粹提取工具函数且不改变行为——跳过。
• 用户口头提出且复现步骤明确的 Bug 修复——跳过。

常见陷阱

• 不要假设。 如果你写“我假设用户想要 X”，就应将这一假设作为问题写入 Context，而不是当作事实。
• 不要把工作推给用户。 探索是你的职责。尽可能通过 Glob／Grep／git 找到答案。只有代码无法提供的信息才向用户询问。