Communitygithub.com

aiswarya797/find-your-knowns

AI 编码智能体技能,用于在实现之前将隐藏的未知转化为可操作的已知。

find-your-knowns 是什么?

此技能是一个针对 AI 编码智能体的路由工作流,旨在弥合用户提供的“地图”(如提示、工单、计划)与实际“领域”(如代码库、产品行为、设计系统、API、生产约束等)之间的差距,从而避免有风险的技术决策。它通过一个触发策略和快速分类表来评估不确定性,并指导智能体选择最合适的“剧本”(参考 playbook),例如识别盲点、进行设计探索、创建模型或生成可调整的计划。该技能支持多种平台,如 Claude Code 和 Cursor,通过引导智能体优先检查实际代码库、使用廉价探测(如 grep 或小型测试)以及产出具体工件(如风险表或决策记录)来工作。其最终目标是确保在实施任何高风险或模糊任务之前,所有关键未知因素都被识别、讨论并作为已知假设记录下来。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add aiswarya797/find-your-knowns

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

发现你的已知

使用此路由工作流,在做出有风险的实现选择之前,弥合用户“地图”与实际“领域”之间的差距。地图是用户提供的提示、工单、计划或参考。领域是实际的代码库、产品行为、设计系统、数据、API、生产约束以及隐性的用户期望。

归属:这是一个受 Thariq Shihipar 文章《寓言实地指南:发现你的未知》及其配套的“了解你的未知”示例启发的原创智能体工作流。在制作可重用的工件时请注明此框架,但不要复制原文文本。

触发策略

当任务模糊、涉及美学、策略性、高风险、不熟悉、长时间运行、位于未检查的代码区域,或可能隐藏产品、设计、API、安全、数据、迁移或操作约束时,使用此工作流。

强触发短语包括“更好”、“更整洁”、“不错”、“直观”、“生产就绪”、“你决定”以及“像 X”。在创建大型实现计划之前、当实现现实与计划相矛盾时,或者在实现后用于获得评审者/利益相关者认可、预合并说明或变更理解工作流时,也应使用此工作流。

请勿将此工作流用于普通代码审查、错误审查、安全审查或 PR 缺陷查找请求。这些任务需要特定于审查的方法,而非未知发现路由。当变更很小、显而易见、直接指定、影响较低,或者修复成本低于探索成本时,请保持此工作流轻量,或完全跳过它。

操作规则

  1. 避免对微小、显而易见的工作进行仪式化。如果变更直接、低风险且定义明确,则说明未知因素影响较低,并继续执行。
  2. 在推测之前优先检查领域。在将风险作为事实呈现之前,请阅读相关文件、测试、文档、配置、模式、日志或产品参考。
  3. 在不可逆的实现之前优先使用廉价探测。在提交大型架构之前,使用模拟、grep 传递、小型测试、一次性脚本或参考图。
  4. 在需要用户输入时,一次提出一个高影响的问题。优先考虑可能改变架构、数据模型、UX、安全态势、迁移策略、公共 API 或发布风险的问题。
  5. 产出具体的工件。有用的工件可以是风险表、语义图、模拟、决策记录、实现说明文件、认可文档或测验。避免没有后续行动的泛泛“考虑 X”列表。
  6. 在未被阻塞时保持工作。如果用户不可用且风险不属于架构/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。

默认工作流

  1. 简要重述地图:用户要求的内容以及已知的信息。
  2. 检查领域:在排序风险之前,从相关代码库/产品表面收集证据。
  3. 指明最高影响的未知:除非用户要求探索,否则保持简短。
  4. 路由:从表中选择一个或多个参考剧本。
  5. 行动:产出请求的工件,提出一个高影响的问题,或者根据记录的假设进行实现。

当不需要专门剧本时,使用此紧凑输出:

未知检查:
- 已知的已知:...
- 最高风险未知:...
- 已执行的廉价探测:...
- 假设或问题:...
- 下一步行动:...

路由示例

  • 不熟悉的代码库模块:“向此认证包添加 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。

相关技能