why：AI Agent 工具实践指南

面对实际交付，我看why的重点不在星标，而在这项能力：在再次做这项工作之前先问为什么，对克劳德代码和法典的有证据支持的返工审查， MIT + 公共条款。从软件开发的使用方式看，依赖、接口和异常处理往往比主路径更影响采用是采用前必须回答的问题。落地前可以在隔离分支完成一个可回滚的小任务，用安装步骤、接口契约、测试结果和错误信息判断它是否真的省事。如果团队属于需要可检查开发流程而非单次演示的工程师，它有继续测试的理由；否则先看替代方案会更省时间。

why

再次做工作之前先问为什么。 对克劳德代码和法典的有证据支持的返工审查。

why 帮助编码代理停止重复无法解决原因的修复。对于真正的返工，why 会生成一个包含十个问题的 why.md，供来自不同系列的模型进行只读审查；当支票阻止你时，请回答笔记中的三个问题，但不要报告。包括技巧和钩子设计；您配置审阅者和任何钩子；未内置自动阻止。

中文說明在下方

何时使用

• 修复总是失败，或者同一类型的问题不断出现。
• 已审核或发回的工作必须重做。
• 你将尝试另一种方式来通过检查、门或失败的测试。

不适用于一次性的辑、纯粹的查询或紧急事件遏制。首先遏制事件；之后再回顾一下。

两个级别 - 大多数时候您只需要第一个

你得到什么

• 原因分析，其中每个“原因”都有证据（文件、行、运行），而不是猜测。
• 提议的更改不仅消除了可见的症状，而且还消除了原因，并列出了要删除的内容。
• 您可以衡量的验证标准：哪一层、哪些数据、哪些确切的期望值。
• 独立审稿人的六行结论：这是真正的原因还是表面结果，目的和方法是否有联系，它是否有效，什么是不相关的，以及为什么。

包含哪些内容以及您自己设置的内容

机器或团队特定的设置（您的判断命令、why.md 所在的位置、钩子适用于谁）位于技能旁边的 local.md 中。它不是此存储库的一部分。

快速入门

1. 将整个 skills/why 文件夹复制到 ~/.claude/skills/why/ (Claude Code) 或 ~/.agents/skills/why/ (Codex)。
2. 当某些内容被阻止时，请代理“使用原因技能”：它会在尝试其他操作之前回答三个问题。
3. 返工之前，代理会使用技能中的十个标题（英文或中文）在您选择的位置（例如 .why/WHY.md）写入 why.md。
4. 将why.md赋予不同的模型，只读，其判断标准和六行回复格式来自hook-design.md。
5. 過 → 返工。 不夠深 → 修复结论所指向的推理（替换表面原因，删除不相关的工作），而不是通过添加更多项目。

它有助于避免的问题

• 修复症状：修补可见的故障而不检查其发生的原因。
• 因一个原因而重复返工： 将共同原因保留在适当的位置，并在许多小部分中重试。
• 正在努力通过检查或关闭任务：绿色状态，但不会为用户带来更好的结果。
• 将解决方法视为原因：“我们添加了一个覆盖来阻止 X”，而不询问为什么 X 仍然存在。
• 设置范围而不进行测量：在检查数据流向之前选择一个补丁。
• 失败后放松验证：移动标准以匹配您刚刚看到的失败。
• 过度设计： 添加测试、规则和文书工作，但无法消除交付障碍。
• 没有理由的判决，或者“缺少什么”的评论：人们猜测，或者不断添加不相关的材料。

why — 中文

動手重做前，先想清楚為什麼。 给 Claude Code 与 Codex 用的「重做前原因审查」，每个原因都要有证据。

why 让写程式的 AI 不再一直重复没打中原因的修正。真的要重做时，写十题的 why.md，交给不同家族的另一个模型只读判断；只是被检查挡住时，在工作纪录答三题就好，不用写报告。本 repo 附技能与 hook 设计；审查模型和 hook 要自己设定，没有内建自动拦截。

什麼時候用

• 同一個修正一直失敗，或同一類問題一再發生。
• 已經審查過、被退回的工作要重做。
• 想換一種方法繞過檢查、閘門或失敗的測試之前。

一次性小改、純查詢、需要馬上止血的事故不適用。事故先處理，穩定後再檢討。

兩種深度——大多數時候只需要第一種

你會得到什麼

• 每一層「為什麼」都附證據（哪個檔、哪一行、哪次執行），不是用猜的。
• 提出拿掉原因、不只讓症狀消失的做法，以及哪些不相關的事該刪掉。
• 量得到的驗收標準：在哪一層量、用哪份資料、預期的確定值。
• 獨立審查回六行：是真的原因還是表面結果、目的和做法連不連得起來、會不會解決、哪些不相關、判斷理由。

有附的、要自己設定的

每台机器或团队自己的设定（判断指令、why.md 放哪、hook 挡谁）放在技能旁边的 local.md，不放进本 repo。

快速開始

1. 把整个 skills/why 资料夹复制到 ~/.claude/skills/why/（Claude Code）或 ~/.agents/skills/why/（Codex）。
2. 被挡住时，请 AI「用 why 技能」：它会先答三题，再决定要不要做。
3. 要重做前，AI 照技能裡的十題標題（中文或英文），在你指定的位置寫 why.md（例如 .why/WHY.md）。
4. 把 why.md 交給另一個模型，只讀，附上 hook-design.md 的判斷標準與六行回覆格式。
5. 判「過」就重做；判「不夠深」就照理由修正因果（把表面結果換成真正原因、刪掉不相關的），不是一直往上加東西。

可以避免哪些開發問題

• 只修症狀：把眼前壞掉的地方補好，卻沒有查清為什麼會壞。
• 同一原因一修再修：共同源頭沒改，拆成很多小重做。
• 為了過檢查或關單而做事：狀態變綠，使用者卻沒拿到更好的結果。
• 把绕过的手段当成原因：「加了一条规则挡掉 X」，却没问 X 为什么还在。
• 沒量就定範圍：沒查資料怎麼走，就決定只修一個地方。
• 驗證標準事後放寬：看到失敗結果，才把標準改到剛好能過。
• 過度工程：一直加測試、規則和手續，卻沒有移除交付的阻礙。
• 只有判定，或只問缺什麼：沒有理由只能猜；一直加清單反而離真正問題越來越遠。

授權

Copyright (c) 2026 Tsaitung。采用 MIT＋Commons Clause License Condition v1.0，不是单纯的 MIT。

可自由使用、修改、分享，但必须保留完整授权声明，且不可贩售：不得把 why 本身，或价值全部或主要来自 why 功能的产品或服务，提供给第三方换取费用或其他对价（包括符合该定义的代管、顾问或支援服务）。 「不可贩售」依 Commons Clause 的 Sell 定义，不是禁止所有商业情境。完整条件以 LICENSE 为准，原文：MIT、Commons Clause。