找出你的未知（Unknowns SOP）

地图与疆域：地图 = 你喂给 agent 的一切（prompt、skill、上下文）；疆域 = 工作真正发生的地方（代码库、真实世界、实际约束）。两者的落差就是未知——agent 每撞上一个未知，就基于「我猜用户大概想要什么」拍板。未知越多，猜得越多。

本 SOP 的使命：在实施前、中、后三个阶段，把未知系统性挖出来、填回地图。

四类未知 → 对应技术

两个通用技术：④ 参考资料（讲不出来时，源码是最好的参考）、⑤ 实施计划（动手前最后一道整理）。

入口路由

按用户诉求分三种入口：

• 完整流程（默认，开新工作时）：阶段一 → 阶段二 → 阶段三 全走。有 HARD-GATE（见下）。
• 单技术（用户点名某个技术，如「考考我」「出几个设计方向」）：只执行该技术，不强制走全流程。
• 阶段补课（工作已在实施中/已完成）：直接进入阶段二或阶段三对应技术。

先交代起点：无论哪个入口，若用户没说清自己「是谁、知道什么」，先问一轮（你思考到哪一步了？对这个领域/代码库熟悉到什么程度？），再开始。这是本 SOP 的第一原则——agent 找到最佳协作方式的前提，是知道用户的已知边界在哪。

阶段一：实施前

顺序不固定，按用户的未知画像选路。典型路径：盲点扫描 → 头脑风暴/原型 → 访谈 → （参考资料贯穿）→ 实施计划。

① 盲点扫描——挖未知未知

何时用：新模块、不熟悉的领域、用户说「不知道该问什么」「不知道好长什么样」「不熟这块」。

执行规则：

1. 先确认用户起点（若未交代：身份、目标、对该领域和代码库的熟悉度）。
2. 搜代码库、文档、相关领域知识。
3. 产出未知清单，按类分组：已有哪些实现可复用、历史遗留与坑、隐式约束与依赖、行业常见错误、「好」的标准是什么、用户不知道自己不知道的选项/工具/路径。
4. 每条格式：它是什么 → 为什么会影响你 → 怎么快速验证 → 建议怎么问（示范措辞）。
5. 最后给「下一步建议」：推荐走哪些后续技术（原型？访谈？参考资料？直接出计划？）。

源模板：

"I'm working on X but I know nothing about Y. Can you do a blind spot pass to help me figure out my relevant unknown unknowns and help me prompt you better."

"我不懂调色但要给视频调色。教我调色的未知未知，好让我能更好地给你下指令。"

② 头脑风暴与原型——逼出未知已知

何时用：「得让我看到才能定义出来」的标准（视觉、交互、文案风格、报表布局）。原型阶段发现规格问题的代价 << 实现阶段。

执行规则：

1. 出 2–4 个差异巨大的方向让用户反应（「react to」），不是同一方案的微调。
2. 优先单文件、假数据、不接线：一个 HTML 原型 > 接好后端的半成品；别为了看一个按钮先写一条路由。
3. 每轮把用户的「喜欢/不喜欢/为什么」记录成显式标准——这就是把未知已知转正为已知已知。
4. 头脑风暴时同时检查范围：框太窄（漏高价值路径）还是太宽（可砍掉一半）。
5. 方向收敛即停，原型是挖需求的工具，不是交付物。

源模板：

"I want a dashboard but have no visual taste. Make me an HTML page with 4 wildly different design directions so I can react to them."

"Before wiring anything up, make a single HTML file mocking the new toolbar with fake data. I want to react to the layout first."

"这是我的问题：用户在 onboarding 后流失。搜代码库，头脑风暴 10 个可干预点，从最便宜到最有野心的顺序排。我告诉你哪些有共鸣。"

③ 访谈——清掉已知未知

何时用：头脑风暴后仍有模糊地带；或用户直接说「采访我」。

执行规则：

1. 一次只问一个问题，优先选择题。
2. 优先问「答案会改变架构」的问题——按影响排序，不是按遇到的顺序。
3. 每个回答当场确认理解；访谈结束把全部答案整理成「已定决策清单」+「仍开放的问题」。

源模板：

"Interview me one question at a time about anything ambiguous, prioritize questions where my answer would change the architecture."

④ 参考资料——讲不出来就给参照

何时用：词汇不够（叫不出那个东西的名字）、太复杂讲不清、或「照这个做」。

执行规则：

1. 最好的参考资料是源码：指向文件夹、说明去看什么，哪怕另一种语言。截图其次，文字最弱。
2. 收到参考资料后，先复述你提取到的语义（行为、边界、风格），让用户确认理解无误，再动手。
3. 没有现成参考时，帮用户找：搜代码库、找开源实现、贴竞品截图皆可。

源模板：

"vendor/rate-limiter 这个 Rust crate 实现了我想要的确切退避行为。读它，在我们的 TypeScript 客户端里重实现同样的语义。"

⑤ 实施计划——动手前最后一道闸

何时用：用户对需求和方向已基本满意，准备开工。

执行规则：

1. 计划按「用户最可能改的地方」排序，不是按实现顺序：
   • 顶部：数据模型变更、新类型/接口、任何用户可见的东西（UX 流程）
   • 底部：机械性重构、搬家、样板——这些是 agent 可信区
2. 显式列出决策点：每个关键决策给出默认选择 + 一句理由，标出「我不确定，需要你拍板」的项。
3. 呈现给用户审批，通过后才解除 HARD-GATE。

源模板：

"Write an implementation plan, but lead with the decisions I'm most likely to tweak: data model changes, new type interfaces, and anything user-facing. Bury the mechanical refactoring at the bottom — I trust you on that."

阶段二：实施中

⑥ 实施笔记——接住藏在暗处的未知未知

何时用：计划批准、开始实现之后。再细的计划也会有漏网之鱼，笔记是兜底网。

执行规则：

1. 新会话开工：建议用户开干净上下文的新会话，把规划产出物（spec、原型、计划）全部塞进 prompt，避免旧会话污染。
2. 创建并维护 implementation-notes.md，分节：
   • Deviations（偏离）：撞上边界情况被迫偏离计划时——选保守方案，记录「何时、撞上了什么、选了什么、为什么」，然后继续跑，不要每件小事都停下来问。
   • Open Questions（留给用户的问题）：不阻塞但值得复盘的。
   • Decisions（agent 自主决策）：计划没写、agent 拍板的，都记进来。
3. 停下来的唯一情况：偏离会改变架构、数据模型或用户可见行为——这种必须问，不能自己拍。

源模板：

"Keep an implementation-notes.md. If you hit an edge case that forces you to deviate from the plan, pick the conservative option, log it under 'Deviations', and keep going."

阶段三：实施后

⑦ Pitch 与说明文档——让人买单

何时用：东西做完了，需要审批/汇报/争取资源。

执行规则：

1. 把原型（或 demo GIF）+ spec + 实施笔记打包成单一文档，能直接丢进 Slack/群。
2. demo 打头，先看效果再读文字。
3. 预答「专家本来会预判到的未知」：常见失败点、边界情况、为什么这样做而不那样做——审阅者看到你考虑过他们担心的问题，批得就快。
4. 偏离（Deviations）如实收录，别美化。

⑧ 测验——通过才合并

何时用：合并/发布前。一场长会话 agent 干的活往往远超用户意识到的，diff 只能给粗浅认识——大量行为挂在已有代码路径上。

执行规则：

1. 先产出变更报告：背景与直觉、做了什么、为什么这么做、和已有代码路径的关系。
2. 报告底部附测验：覆盖行为变化、边界情况、每条 Deviation 的原因。题目要能验证用户「真的理解」，不是走形式。
3. 用户没全部答对之前不建议合并；答错的地方回到报告讲解，直到通过（或用户明确豁免）。

源模板：

"Give me a report on the changes — context, intuition, what was done — and a quiz at the bottom on the changes that I must pass."

指令的平衡术

给 agent 下指令的两个失败方向，挖未知就是为了不踩它们：

• 太具体 → agent 死扣指令，该转向时不转向。
• 太模糊 → agent 按业界最佳实践假设，而那些假设不契合你的任务。

没盘清未知时两个坑都会踩。所以指令留弹性：「允许在 X 类小事上自行决定、按保守原则处理」，而不是把每个细节焊死。

危险信号

出现以下想法时，停下来——你在跳过 SOP：

核心原则

• 先交代起点：告诉 agent 你是谁、想到哪一步了、熟到什么程度——这是挖未知的前提
• 一次一个问题，答案会改架构的问题优先
• 原型用假数据、不接线，为反应而生，不为交付而生
• 源码 > 截图 > 文字——讲不清就给参照
• 计划把「会变的决策」放最上面，机械部分沉底
• 偏离记笔记、选保守、继续跑；只有架构级偏离才停下来问
• 打包成一份能直接转发的文档，demo 打头
• 测验全过才合并——理解自己的变更，才算真的完成