发现你的已知
使用此路由工作流,在做出有风险的实现选择之前,弥合用户“地图”与实际“领域”之间的差距。地图是用户提供的提示、工单、计划或参考。领域是实际的代码库、产品行为、设计系统、数据、API、生产约束以及隐性的用户期望。
归属:这是一个受 Thariq Shihipar 文章《寓言实地指南:发现你的未知》及其配套的“了解你的未知”示例启发的原创智能体工作流。在制作可重用的工件时请注明此框架,但不要复制原文文本。
触发策略
当任务模糊、涉及美学、策略性、高风险、不熟悉、长时间运行、位于未检查的代码区域,或可能隐藏产品、设计、API、安全、数据、迁移或操作约束时,使用此工作流。
强触发短语包括“更好”、“更整洁”、“不错”、“直观”、“生产就绪”、“你决定”以及“像 X”。在创建大型实现计划之前、当实现现实与计划相矛盾时,或者在实现后用于获得评审者/利益相关者认可、预合并说明或变更理解工作流时,也应使用此工作流。
请勿将此工作流用于普通代码审查、错误审查、安全审查或 PR 缺陷查找请求。这些任务需要特定于审查的方法,而非未知发现路由。当变更很小、显而易见、直接指定、影响较低,或者修复成本低于探索成本时,请保持此工作流轻量,或完全跳过它。
操作规则
- 避免对微小、显而易见的工作进行仪式化。如果变更直接、低风险且定义明确,则说明未知因素影响较低,并继续执行。
- 在推测之前优先检查领域。在将风险作为事实呈现之前,请阅读相关文件、测试、文档、配置、模式、日志或产品参考。
- 在不可逆的实现之前优先使用廉价探测。在提交大型架构之前,使用模拟、grep 传递、小型测试、一次性脚本或参考图。
- 在需要用户输入时,一次提出一个高影响的问题。优先考虑可能改变架构、数据模型、UX、安全态势、迁移策略、公共 API 或发布风险的问题。
- 产出具体的工件。有用的工件可以是风险表、语义图、模拟、决策记录、实现说明文件、认可文档或测验。避免没有后续行动的泛泛“考虑 X”列表。
- 在未被阻塞时保持工作。如果用户不可用且风险不属于架构/API/安全/数据关键,则选择最保守的可逆默认值,记录该假设,然后继续。
快速分类
在选择剧本之前对任务进行分类:
- 已知的已知:用户明确给出的需求。
- 已知的未知:用户已经指出或明显暗示的开放问题。
- 未知的已知:用户一旦看到就会认识到品味、惯例、质量标准和领域期望。
- 未知的未知:双方都未揭示的隐藏约束、行为、风险或缺失的领域知识。
然后对不确定性进行分类:
- 低不确定性,低影响:直接实现。可选地说明你使用的一个假设。
- 中等不确定性:运行一个重点剧本并继续。
- 高不确定性或高影响范围:检查代码库,运行盲点扫描,然后路由到访谈、参考搜索、模拟或可调整计划。
- 计划与实现现实矛盾:使用实现说明并重新规划受影响的部分。
- 工作已完成但理解或认可缺失:使用认可文档或变更测验。
路由表
仅加载当前任务所需的剧本:
- 不熟悉的代码库模块、隐藏约束或高风险区域:阅读
references/blindspot-pass.md。 - 用户缺少领域词汇或专家质量标准:阅读
references/teach-me-my-unknowns.md。 - 模糊的设计、UX 品味、“让它更好看”、“直观”或“像 X”:阅读
references/design-directions.md。 - 在后台、API 或状态工作前 UX/产品形态不清晰:阅读
references/mock-before-wire.md。 - 解决方案空间开放且成本/风险权衡重要:阅读
references/effort-axis-brainstorm.md。 - 已知的模糊性需要用户决策:阅读
references/interview.md。 - 现有实现、产品或竞争对手行为应作为规范:阅读
references/reference-hunt.md。 - 即将制定大型计划:阅读
references/tweakable-plan.md。 - 实现揭示意外或使计划无效:阅读
references/implementation-notes.md。 - 已完成工作需要评审者或利益相关者认可:阅读
references/buy-in-doc.md。 - 用户希望在合并前理解大型变更:阅读
references/change-quiz.md。
默认工作流
- 简要重述地图:用户要求的内容以及已知的信息。
- 检查领域:在排序风险之前,从相关代码库/产品表面收集证据。
- 指明最高影响的未知:除非用户要求探索,否则保持简短。
- 路由:从表中选择一个或多个参考剧本。
- 行动:产出请求的工件,提出一个高影响的问题,或者根据记录的假设进行实现。
当不需要专门剧本时,使用此紧凑输出:
未知检查:
- 已知的已知:...
- 最高风险未知:...
- 已执行的廉价探测:...
- 假设或问题:...
- 下一步行动:...
路由示例
- 不熟悉的代码库模块:“向此认证包添加 SSO;我之前从未接触过它” ->
blindspot-pass.md,如果风险高则接着使用tweakable-plan.md。 - 模糊的设计请求:“让审查仪表板更整洁、更高级” ->
design-directions.md,可选mock-before-wire.md。 - 已知的架构模糊性:“这应该放在 API 网关还是 worker 中?” ->
interview.md,然后tweakable-plan.md。 - 基于参考的实现:“将此 Rust crate 的重试行为移植到我们的 TypeScript 客户端” ->
reference-hunt.md。 - 实现中途偏离:“该模式不支持计划中的迁移” ->
implementation-notes.md,然后仅在新路径更改数据/API 契约时询问。 - 合并前测验:“确保我在合并前理解此分支” ->
change-quiz.md。