Communitygithub.com

ajitta/know-your-unknowns

Claude Code 插件:知己所不知 —— 盲点排查、领域入门、实施前访谈、调整可能性计划、偏差日志与合并测验

know-your-unknowns 是什么?

“知己所不知”(Know Your Unknowns)是一款专为 Claude Code 设计的插件技能,其核心是一套结构化的操作循环(Unknowns Loop),旨在帮助开发者和 AI 模型在复杂任务中缩小“规划(地图)”与“现实(领土)”之间的差距。该技能包含10个步骤,从定义成功标准、盲点调查、架构访谈,到可调整的计划制定、实施中的偏差日志记录、独立验证、以及最终的价值回顾。它支持根据不同任务规模进行灵活裁剪(如小型修复只需第7步,中型工作走1-2-3-6-7-9步骤链),并能通过 `.unknowns/loop.json` 文件在会话压缩、恢复或新会话中保持状态。该技能适用于 Claude Code 等支持 Agent Tool 和 Artifact 的 AI 编码助手,通过系统化地暴露未知、记录偏差和衡量真实价值,帮助用户避免盲目实施,提升决策质量和代码的最终效果。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add ajitta/know-your-unknowns

在你喜欢的 AI 中提问

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

文档

未知循环 —— 与强模型协作的操作循环

核心原则:强模型的瓶颈不在于模型本身,而在于用户将地图(计划)与领土(现实)保持匹配的能力。这个差距就是未知。 设计 探索 → 提问 → 规划 → 实施 → 记录偏差 → 验证 的循环比一个良好的提示更重要。 来源:11 个“知己所不知”示例;该循环本身是一个插件扩展——详见 skills/loop/references/talk-source.md。

输出:Artifact 工具 → .unknowns/<YYYY-MM-DD>-loop-<slug>.html → markdown。 每个阶段的工件都保留其自身技能的反应控制;循环自身的控制是每个阶段的检查点,这些检查点会汇编到 .unknowns/loop.json 追踪器中。 详情:skills/loop/references/output-routing.md

步骤(10 步 —— 根据规模缩减)

1. 定义价值与完成标准

在开始前与用户确定:目的 / 对用户的价值 / 完成标准 / 绝对不能破坏的现有行为 / 允许的成本与变更范围。 没有成功标准,实施量就会被误认为是进展。

2. 盲点调查 → /unknowns:blindspot(或 /blindspot 用于复制的安装)

仅调查,不实施。发现未知的未知、冲突点、回归风险;生成改进后的提示。如果领域本身不熟悉(由于术语未知导致需求模糊),请同时运行 /unknowns:teach-me。

3. 访谈 → /unknowns:interview

先提架构变更问题,每轮最多 4 个。

4. 探索解决方案并塑形(按需)

  • 该做什么 未定 → /unknowns:brainstorm(解决方案空间地图)
  • 无法用语言描述它应该长什么样 → /unknowns:prototypes(发散型模型)
  • 有可供模仿的示例 → /unknowns:reference(参考分析)

5. 高风险假设原型(按需)

在全面实施之前,构建最小原型,仅验证最不确定的技术假设。首先说明假设和成功/失败标准。

6. 计划 → /unknowns:plan

可调整的计划,按修订概率排序,而非执行顺序。需要用户输入(模式、接口、UX 契约)的决策放在最上面。

7. 实施 + 偏差日志 → 应用 /unknowns:notes 规则

记录计划中未包含的任何内容;在触及架构、用户可见行为、数据或安全性的决策上停下来询问。如果对话已被压缩,在继续实施前重新调用 /unknowns:notes(以及此技能以获取步骤列表)。

8. 独立验证 → unknowns:independent-reviewer 代理

使用 Agent 工具(subagent_type: unknowns:independent-reviewer)生成该代理。绝对不能使用 fork 或 /subtask——它们会继承实施者的上下文,而这正是此步骤旨在排除的。向代理提供:完成标准(步骤 1)、批准的计划(步骤 6)、IMPLEMENTATION_NOTES.md 路径、差异范围/触及的文件,以及如何运行测试。绝对不能提供实施者自己的总结。

9. 理解检查与交接 → /unknowns:quiz

验证用户能够在 PR 或交接中解释这项工作。如果工作需要审查者或利益相关者批准,还需生成一份 /unknowns:buy-in 文档。

10. 价值回顾

以实际价值而非代码质量评判:谁的问题缩小了、什么方面、速度提高了多少、可能未被使用的原因、指标、移除条件。构建容易,创造价值仍然困难。 最后收集一行评分记录——询问用户这项工作是否揭示了某些他们不知道的东西,以及是否改变了某个决策,然后将该行追加到 .unknowns/scorecard.md。切勿替用户回答这两个问题,即使两个答案都是“否”也要写入该行。详情:skills/loop/references/scorecard.md

缩减标准

  • 小型修复(1–2 个文件,清晰说明):仅适用步骤 7 的规则(笔记)——无需完整循环。
  • 中型工作:1(一轮交流)→ 2 → 3 → 6 → 7 → 9。
  • 大型或不熟悉的工作:所有步骤,步骤 4 和 5 按需执行。
  • 步骤 1 在每个层级中均执行。不确定层级 → 询问用户,然后记录选择。

循环状态(在压缩、恢复、新会话中存活)

维护 .unknowns/loop.json —— {task, tier, stage, decisions[], artifacts[]} —— 并在每个阶段边界处重写它。每个阶段结束时用一个 AskUserQuestion 检查点(继续 / 跳过 / 停止)来关闭,并在此记录答案。

  • 参数 status:读取文件;报告当前层级、阶段、剩余步骤。
  • 参数 resume:读取文件;从记录阶段继续。
  • 任何其他参数文本为任务描述。
  • 无参数:如果 .unknowns/loop.json 存在则恢复,否则先询问任务。

操作原则(压缩版)

  1. 定义目的。2. 在实施前发现盲点。3. 让模型提问问题。4. 提供参考和原型而非文字。5. 按修订概率排序计划。6. 记录未知和计划偏差。7. 通过测试和独立审查验证。8. 确认用户能够解释结果。9. 以可反应形式交付成果。10. 衡量真实价值,而非代码量。

相关技能