我把 AI 编程里的“未知项管理”整理成了一个可复用 Skill
GitHub 仓库：github.com/xu91102/Tha…
灵感来源：Anthropic Claude Code 团队工程师 Thariq Shihipar 的文章 A Field Guide to Fable: Finding Your Unknowns
这两年用 AI 写代码的人越来越多，但很多失败并不是因为模型不会写代码，而是因为它过早进入了“实现模式”。
需求还没说透，仓库上下文还没看完整，风险边界还没被识别，Agent 就开始改文件、加抽象、补测试。表面上进度很快，实际是在用代码把假设固化下来。
这篇文章的灵感来自 Thariq Shihipar 的 A Field Guide to Fable: Finding Your Unknowns。Thariq 是 Anthropic Claude Code 团队的工程师，他在文章里反复强调一个老问题：地图不是领地。
基于这个思路，我整理了一个小仓库：Thariq Skills。它不是一个框架，也不是一套复杂工具链，而是一套可复用的 agentic coding 工作流，核心目标只有一个：
在真正动手之前、动手过程中、交付之后，持续发现和管理未知项。
仓库里有什么
仓库地址：
当前主要包含一个 skill：
skills/
├── discover-unknowns/
│ ├── SKILL.md
│ ├── agents/openai.yaml
│ └── references/prompt-patterns.md
└── discover-unknowns-zh/
├── SKILL.md
├── agents/openai.yaml
└── references/prompt-patterns.md
discover-unknowns 是英文版，discover-unknowns-zh 是中文版。
它适合用在这些场景：
- 需求模糊，用户自己也还没完全想清楚
- Agent 对业务、代码库或技术栈不熟
- 改动会影响架构、数据模型、API、UX 或测试策略
- 任务链路很长，过程中容易不断暴露新问题
- 你希望 Agent 先识别盲点，而不是直接开写
核心思想：地图不是领地
这个 skill 的核心来自 Thariq 文章里的一个很实用的判断：
提示词、计划、上下文和 skill 都只是“地图”；真实代码库、用户偏好、业务约束、质量标准和评审过程才是“领地”。
AI 编程里很多问题，恰好发生在地图和领地不一致的时候。
比如：
- 需求说“加一个导出功能”，但没说数据量可能很大
- 代码里已经有一套权限体系，但 Agent 没检索到
- 用户说“界面简洁一点”，但真正想要的是高密度后台工具风格
- 测试能过，但线上有兼容旧数据的迁移约束
- 实现方案看起来合理，但评审者最关心的是灰度和回滚
这些都不是简单的“代码生成能力”问题，而是未知项没有被提前暴露。
四类未知项
我把不确定性拆成四类：
| 类型 | 含义 |
|---|---|
| 已知的已知 | 用户、代码库、文档、测试或已验证来源已经明确说明的事实 |
| 已知的未知 | 已经意识到但还没有答案的问题 |
| 未知的已知 | 用户心里有判断、偏好、品味或领域直觉，但需要看到示例才说得清 |
| 未知的未知 | 尚未意识到的概念、隐藏约束、失败模式、历史方案或评审关注点 |
最麻烦的是后两类。
“未知的已知”经常出现在产品、设计、交互、文案里。用户很难一开始就描述清楚，但看到原型后能立刻判断：“这个不对，我想要的不是这种感觉。”
“未知的未知”则更危险。它可能是历史包袱、边界数据、隐藏集成、性能瓶颈、安全问题，也可能是评审时才会被指出的质量标准。
这个 skill 的目的不是把流程变复杂，而是用最低成本把高风险未知项提前翻出来。
工作流：先找风险，再写代码
discover-unknowns 的工作流可以概括成 6 步。
1. 说明起点
先让 Agent 明确三件事：
- 用户想要什么
- 当前已经确定了什么
- 还有哪些问题没有答案
这一步的重点不是写长篇分析，而是防止 Agent 在一开始就带着错误理解往前冲。
2. 做盲点扫描
对复杂任务，先让 Agent 做一次 blind-spot pass。
它需要列出可能的未知的未知，例如：
- 隐藏集成
- 数据模型约束
- UX 预期
- 性能陷阱
- 安全问题
- 迁移风险
- 历史实现
- 测试缺口
- 评审反对点
并且每个盲点都要说明两个问题：
- 为什么重要
- 最低成本怎么验证
这里我特别强调“最低成本”。很多时候不需要完整实现，只需要读一段旧代码、跑一个现有测试、看一个日志、做一个小实验，就能排除一个大坑。
3. 选择最低成本工件
不同未知项，适合用不同工件暴露。
| 场景 | 推荐工件 |
|---|---|
| 范围或策略不确定 | brainstorm |
| 用户需要“看到才知道” | prototype |
| 一个答案可能改变架构 | interview |
| 有强参考物 | reference |
| 即将改生产代码或多文件 | implementation plan |
这一步很关键：不要所有问题都用“写计划”解决。
有些问题需要访谈，有些需要原型，有些只需要读参考物。工件越轻，反馈越快，越不容易把错误方向做重。
4. 让计划保留转向空间
如果要写实施计划，最容易变的决策要放在前面：
- 数据模型
- 接口设计
- UX 流程
- 安全边界
- 灰度策略
- 兼容性处理
机械性的重构、改名、搬文件，应该放到后面。
原因很简单：前面的决策一旦错了，后面的代码越多，返工成本越高。
5. 记录实现中的发现
实现过程中经常会发现新约束。
比如原计划是改一个接口，结果发现有旧客户端依赖；原计划是同步导出，结果发现数据量必须异步处理；原计划是统一组件，结果发现两个页面的权限语义不同。
这时 Agent 不应该偷偷绕过去，也不应该强行按原计划推进。
比较稳的方式是维护一个 implementation-notes.md，记录：
- 发现了什么边界情况
- 哪些地方偏离了原计划
- 采用了什么保守选择
- 哪些问题暂缓
- 验证证据是什么
如果新发现会改变用户可见行为、数据形状、安全或架构，就应该暂停，让用户重新审阅。
6. 实现后闭环
复杂改动完成后，最好产出一份面向评审者的说明文档。
它不需要很长，但至少讲清楚：
- 改了什么
- 为什么这么做
- 关键决策是什么
- 哪些未知项已经被处理
- 做了哪些验证
- 还剩什么风险
这对代码评审非常有用。评审者不需要重新推理整个过程，可以直接检查关键假设和验证证据。
一个可以直接用的提示词
如果你想试一下，可以从这个提示开始：
我正在做 [任务]。我当前确定的内容是 [已知的已知]。我不熟悉或还没想清楚的是 [已知的未知/经验水平]。
请做一次盲点扫描：如果有相关代码或文档，先检索它们；然后识别我的未知的未知，解释每个盲点为什么重要，并建议在实现前最低成本的验证方式。
推荐输出结构：
## 已知的已知
- ...
## 已知的未知
- 问题：
重要性：
低成本检查：
## 可能的未知的未知
- 盲点：
证据/来源：
风险：
低成本检查：
## 下一步最合适的工件
- 建议：
- 原因：
如果你要做的是产品、UI、工作流或文案类任务，也可以让 Agent 先做原型：
在触碰生产代码前，请为 [问题] 做 [N] 个明显不同的方案。目标是让我能对自己还说不清的取舍做反应。
每个方案都要给出工件或具体草图，说明它能帮助我们学到什么，以及如果选它，实现方案会发生什么变化。
什么时候不该用
这个 skill 不是让每个小任务都变成流程审批。
如果只是：
- 改一个 typo
- 调一个按钮文案
- 补一个简单配置
- 做一个非常明确的单文件修改
那就没必要上完整流程。直接最小改动、最小验证即可。
我在 skill 里也写了一个规则：
任务简单时，只使用最小有用步骤，不做仪式化流程。
流程的价值是降低风险，不是制造存在感。
参考来源
- Thariq Shihipar 原文：A Field Guide to Fable: Finding Your Unknowns
- Thariq Shihipar 个人主页：www.thariq.io/
- 我的整理仓库：github.com/xu91102/Tha…
我为什么做这个仓库
AI 编程真正进入日常工作后，我越来越觉得“会不会写代码”只是第一层问题。
更重要的是：
- Agent 是否知道什么时候该先问
- 是否知道什么时候该先查
- 是否知道什么时候该做原型
- 是否知道什么时候该暂停
- 是否能把实现过程中发现的新事实记录下来
- 是否能给评审者留下足够的判断依据
这些能力很难只靠一句“请谨慎一点”解决。它需要被沉淀成可复用的工作流、决策规则和提示模板。
这就是 Thariq-skills 这个仓库目前在做的事。
总结
discover-unknowns 解决的不是“让 AI 更快写代码”，而是让 AI 在复杂任务里少做隐性假设。
它把任务推进方式从：
直接实现，遇到问题再补救
调整为：
先识别未知项，用最低成本工件验证，再进入实现
对我来说，这比单纯追求生成速度更重要。
如果你也在用 Codex、Claude Code 或其他 agentic coding 工具，可以试试把这套思路放进自己的工作流里。
GitHub 仓库：
