Folly 项目 AI 代理设计审查指南Design Vetting在实现前用证据锁定正确方案【免费下载链接】follyAn open-source C library developed and used at Facebook.项目地址: https://gitcode.com/GitHub_Trending/fol/folly设计审查Design Vetting是 Folly 仓库中 folly/agents 规则包的一等公民规则在选择任何实质性设计或正确性修复方案之前先系统性地界定问题、排查未知、筛掉不可行方案再对幸存方案做证据驱动的比较。本文基于 folly/agents/design-vetting.md 完整展开其决策流程并结合仓库中 critic-iterate.md、writing.md、CONTRIB.md 等配套规则说明它在实际工程任务中如何运转。读完你将掌握一套可复制的五阶段设计审查方法从只陈述决策需要的内容到用最难用例检验领先候选让设计决策在方案硬化之前就建立在可验证的证据之上。一、规则定位为何 Folly 需要一份设计审查规则FollyFacebook 开源 C 库越来越多的工作由编码代理coding agent完成但贡献者的严谨程度差异很大。folly/agents/README.md 指出生产力提升只有在产出保持高质量、且人类评审成本低时才有意义。其中design-vetting.md的作用被明确描述为——在方案硬化之前把需求、约束、失败模式和选择所需证据摆上台面。配套文件进一步圈定了它的边界folly/agents/design-vetting.entrypoint.md 是加载入口声明触发条件在做出实质性设计或正确性修复选择之前加载 agents/design-vetting.md。folly/agents/design-vetting.contrib.md 记录了规则的目的阻止代理在找到缺失需求、核查可能改变选择的假设、拒绝不可行选项之前就急着打磨第一个看起来可行的设计。它还强调该规则必须保持为独立的一级规则因为它管辖的是选择设计方案而不是解释设计方案。需要特别说明README.md、*.contrib.md、*.entrypoint.md都是规则开发材料不是运行时的任务策略正常任务中只有用户规则文件点名时才加载。换句话说design-vetting.md解决的是一个非常具体的工程问题设计选择发生在信息最不完整、沉没成本最低的时刻而此时恰恰最容易犯确认偏误——拿着第一个方案就冲。本规则把这个时刻变成一道强制闸门。二、界定决策Frame the decision只陈述决策需要的内容设计审查的第一步不是列方案而是把决策本身界定清楚。规则要求只陈述决策需要的东西共四要素设计必须产出的结果outcome明确这个设计要达成的目标而不是过程或手段必须处理的触发条件与失败模式triggers and failure modes什么输入、什么运行条件会走到这条路径出错时会有哪些失败方式必须保持的约束与不变量constraints and invariants无论方案怎么选都不能破坏的边界条件可能改变胜负的未知项unknowns哪些尚未确认的事实会让不同的设计胜出。其中有一条重要的反模式提示一个复现reproduction只是一个用例不是问题定义。当你手里只有一个已知失败案例时要明确指出已知案例可能是不完整的——否则你会把一个局部现象当成完整的问题陈述设计出来的方案只能修好这一个案例。这条在 Folly 这种体量跨algorithm、concurrency、futures、coro等数十个模块的代码库中尤其关键同一类正确性问题可能由完全不同的机制触发把复现当定义是正确性修复中最常见的系统性错误。三、尽早解决重要未知Settle important unknowns early界定完决策后不要急着展开任何一个方案分支。规则给出的策略是只把候选方案勾画到能暴露它们之间假设差异的程度而不是完整设计。不要为了凑数而发明一个明显很弱的选项。随后在任何分支深入开发之前先找廉价工作cheap work来消除它或改变它的排名。优先做最可能推翻某个候选、或解决多个候选共有的假设的那个检查。规则给出的有用检查清单包括阅读定义该行为的接口reading the interface that defines the behavior追踪一条真实路径或运行一个端到端小用例tracing a real path or running a tiny end-to-end case测量有争议的量measuring the disputed quantity构建一次性原型building a throwaway prototype。一旦某个决定性的约束或观察排除了一个分支就立即停止探索不要因为已经投入了而继续。对于不便宜的重要未知规则给出两条指导优先选择不依赖该未知的设计prefer a design that does not depend on it只有当未知的可能结果确实会改变候选的可行性或最终选择时才在该未知上分叉不要探索通向同一决策的组合。这与 folly/agents/critic-iterate.md 的证据Evidence小节一脉相承它要求只用最便宜的直接检查来定论一个主张不要把一个任务输入当作已独立验证的事实不要声称超过证据支持的程度。设计审查阶段做的每一个廉价检查产出的正是这些证据条目。四、在展开前筛选候选Screen candidates before elaborating them候选方案在付出设计成本之前先过一道可行性筛查viability screen。只要满足以下任一条立即拒绝漏掉了某个必需的触发条件或失败模式破坏了某个约束或不变量依赖于一个已被证伪的主张depends on a contradicted claim可能以不可接受的后果失败can plausibly fail with unacceptable consequences。规则特别强调一个判断陷阱一个没有依据的假设是一个需要去解决或绕开的未知而不是把候选排为可行的理由。换句话说也许能行不等于可行——在证据层面悬而未决的假设只能把候选降级或打回验证阶段不能把它当作可行项参与排名。这一条与critic-iterate.md对设计审查的批评维度直接对应其 General Cycle 中列出的设计维度包括问题是否被完整覆盖Full problem covered?、排名前是否做了可行性检查Viability checked before ranking?、不变量是否被保留Invariants preserved?——正是本节三条筛查标准的运行时复现。五、比较幸存方案Compare the survivors正确性优先成本殿后通过筛查的方案才有资格进入比较。规则明确规定只使用可能改变本次决策的因素并针对正确性修复工作给出强制优先级——先比较下面三个维度再谈便利性优先级维度核心问题1覆盖与放置Coverage and placement设计是否覆盖了每一个必需的触发条件和失败模式是否在一个拥有所需信息、且掌管该不变量的层次上实现2假设Assumptions哪些断言必须保持为真它们被支持得有多好3失败行为Failure behavior如果设计是错的、或某个依赖失败它是暴露问题并限制损害还是继续给出一个貌似正确但实际错误的结果关于用现有生产设计佐证候选规则给出严格前提只有当现有设计产生相关行为的原因是相同的、且当前场景的条件也成立时它才能支持该候选。必须陈述行为、原因、匹配条件三者相似性本身既不能证明也不能推翻候选。这三个维度比较完之后才比较只在这里有意义的成本实现与维护的复杂度性能或能力损失上线与回滚rollout or reversal风险。规则有两条刚性约束成本不能挽救一个未通过可行性筛查的候选——顺序不可颠倒在可行候选之间必须明确说出决定最终选择的那笔权衡tradeoff而不是含糊地说各有优劣。六、没有可行方案或没有明确赢家时停下来如实说设计审查最容易被忽略的一步是承认决策无法在当前证据下收敛。规则明确授权当必须做出选择、而合理调查后既没有可行设计、也没有明确赢家时停下来陈述仍然悬而未决的是什么以及什么证据或决策能够解决它只有当请求的产出物确实能用条件分支时才提供条件分支不要为了凑完设计而凭空发明行为。这在大型 C 代码库中极其重要一个为了交付而编造的设计会把不变量破坏的风险从设计阶段推迟到线上故障而那时修复成本已经放大了一个数量级。规则的设计哲学是诚实的未解决好过虚假的已完成。七、落地用最难用例检验领先候选并记录不确定性在写实现计划implementation plan之前设计审查还有最后一关用已知最难的用例检验领先候选test the leading candidate against the hardest known case——如果最强候选连最苛刻的用例都过不了现在发现比实现后才发现便宜得多对每个未解决的未知只考虑可能改变可行性或选择的结果——不要为每个未知枚举所有可能世界记录仍然不确定的内容以及什么观察结果会证明应该重新审视这个选择what observation would justify revisiting the choice。这一步让设计决策从一次性快照变成可复审的基线未来一旦出现规则所说的观察结果就有明确依据回访决策而不是靠感觉返工。这条记录不确定性的要求与critic-iterate.md的双重修订Dual Revision机制衔接当评审发现一个MUST_TAKE级别的问题改变了所提修复的行为、使某个回退方案失效、或暴露了一个决定性的正确性假设时必须重新应用design-vetting.md之后再编辑——设计审查不是一次性的它贯穿到评审闭环结束。八、与其他规则的协作边界design-vetting.md不是孤立文件它与 folly/agents 规则包的其余部分有明确的触发边界加载时机按 folly/agents/critic-iterate.md 的加载清单作者与编排会话在选择实质性设计或正确性修复之前加载design-vetting.md同时默认加载core/breadcrumbs.md与core/conflicts.md后者用于裁决规则冲突例如评审发现与已加载规则冲突时先应用core/conflicts.md再做分流。与写作规则的衔接folly/agents/writing.md 在Document小节规定任何实质性设计或修复提案都必须先应用design-vetting.md且提案要说明问题发生在哪里、提案必须产出什么结果——这正是第一节Frame the decision的写作层落地。提案的正文结构Motivation / Mechanism / Alternatives rejected / Killswitch rollback也与第五节先正确性、后成本的排序一致。与维护规则的衔接folly/agents/CONTRIB.md 要求编辑规则前阅读最近的.contrib.md理解规则为何存在、改动必须保留什么阅读name.entrypoint.md了解什么触发这条规则并遵循每条规则都是用血写成的原则。如果你想修改design-vetting.md本身必须先读 design-vetting.contrib.md 和 CONTRIB.md。注意加载边界design-vetting.md只在用户规则文件或另一条运行规则点名时才被加载design-vetting.entrypoint.md 中的触发文本应被复制进用户规则文件其中的路径以用户规则文件所在位置为基准。.contrib.md与.entrypoint.md是开发材料不得作为任务策略加载。九、一张可复用的检查清单把design-vetting.md的五阶段浓缩成一张在任何设计任务开始前都可以逐项打勾的清单阶段一界定决策设计必须产出的结果是否一句话可说清所有必需的触发条件与失败模式是否已列出必须保持的约束与不变量是否明确可能改变胜负的未知项是否已命名是否已声明已知复现案例可能不完整阶段二解决未知是否已用最廉价的直接检查推翻或验证关键假设读接口、跑端到端用例、测量、一次性原型被决定性约束排除的分支是否已停止探索是否倾向于选择不依赖未解决未知的设计是否避免了探索通向同一决策的组合阶段三筛选候选每个候选是否覆盖全部触发条件与失败模式是否保持全部约束与不变量是否不依赖任何已被证伪的主张是否会以不可接受的后果失败无依据的假设是否被当作待解决未知而非可行理由阶段四比较幸存者是否按覆盖与放置 → 假设 → 失败行为的顺序比较用现有生产设计佐证时是否陈述了行为、原因、匹配条件三者成本比较是否只包含在此处有意义的项是否明确说出了决定选择的那笔权衡无法决策时是否停下并如实说明需要什么证据阶段五落地与记录是否用最难的已知用例检验了领先候选对未解决未知是否只考虑可能改变结果的情形是否记录了不确定性以及什么观察结果会触发重新决策这套流程的最终目的正如规则原文所强调的不要让第一个貌似可行的设计在需求尚未挖全、假设尚未核查、不可行选项尚未剔除之前就被打磨成型。在 Folly 这样复杂、跨模块、且大量依赖不变量如并发数据结构的内存序、futures 的回调生命周期、coro 的取消语义的代码库中设计阶段多花一次廉价检查往往能省掉实现阶段一整轮的返工与线上事故。【免费下载链接】follyAn open-source C library developed and used at Facebook.项目地址: https://gitcode.com/GitHub_Trending/fol/folly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 18:30:13 · 阅读 1.2k Folly 项目 AI 代理设计审查指南（Design Vetting）：在实现前用证据锁定正确方案
Folly 项目 AI 代理设计审查指南Design Vetting在实现前用证据锁定正确方案【免费下载链接】follyAn open-source C library developed and used at Facebook.项目地址: https://gitcode.com/GitHub_Trending/fol/folly设计审查Design Vetting是 Folly 仓库中 folly/agents 规则包的一等公民规则在选择任何实质性设计或正确性修复方案之前先系统性地界定问题、排查未知、筛掉不可行方案再对幸存方案做证据驱动的比较。本文基于 folly/agents/design-vetting.md 完整展开其决策流程并结合仓库中 critic-iterate.md、writing.md、CONTRIB.md 等配套规则说明它在实际工程任务中如何运转。读完你将掌握一套可复制的五阶段设计审查方法从只陈述决策需要的内容到用最难用例检验领先候选让设计决策在方案硬化之前就建立在可验证的证据之上。一、规则定位为何 Folly 需要一份设计审查规则FollyFacebook 开源 C 库越来越多的工作由编码代理coding agent完成但贡献者的严谨程度差异很大。folly/agents/README.md 指出生产力提升只有在产出保持高质量、且人类评审成本低时才有意义。其中design-vetting.md的作用被明确描述为——在方案硬化之前把需求、约束、失败模式和选择所需证据摆上台面。配套文件进一步圈定了它的边界folly/agents/design-vetting.entrypoint.md 是加载入口声明触发条件在做出实质性设计或正确性修复选择之前加载 agents/design-vetting.md。folly/agents/design-vetting.contrib.md 记录了规则的目的阻止代理在找到缺失需求、核查可能改变选择的假设、拒绝不可行选项之前就急着打磨第一个看起来可行的设计。它还强调该规则必须保持为独立的一级规则因为它管辖的是选择设计方案而不是解释设计方案。需要特别说明README.md、*.contrib.md、*.entrypoint.md都是规则开发材料不是运行时的任务策略正常任务中只有用户规则文件点名时才加载。换句话说design-vetting.md解决的是一个非常具体的工程问题设计选择发生在信息最不完整、沉没成本最低的时刻而此时恰恰最容易犯确认偏误——拿着第一个方案就冲。本规则把这个时刻变成一道强制闸门。二、界定决策Frame the decision只陈述决策需要的内容设计审查的第一步不是列方案而是把决策本身界定清楚。规则要求只陈述决策需要的东西共四要素设计必须产出的结果outcome明确这个设计要达成的目标而不是过程或手段必须处理的触发条件与失败模式triggers and failure modes什么输入、什么运行条件会走到这条路径出错时会有哪些失败方式必须保持的约束与不变量constraints and invariants无论方案怎么选都不能破坏的边界条件可能改变胜负的未知项unknowns哪些尚未确认的事实会让不同的设计胜出。其中有一条重要的反模式提示一个复现reproduction只是一个用例不是问题定义。当你手里只有一个已知失败案例时要明确指出已知案例可能是不完整的——否则你会把一个局部现象当成完整的问题陈述设计出来的方案只能修好这一个案例。这条在 Folly 这种体量跨algorithm、concurrency、futures、coro等数十个模块的代码库中尤其关键同一类正确性问题可能由完全不同的机制触发把复现当定义是正确性修复中最常见的系统性错误。三、尽早解决重要未知Settle important unknowns early界定完决策后不要急着展开任何一个方案分支。规则给出的策略是只把候选方案勾画到能暴露它们之间假设差异的程度而不是完整设计。不要为了凑数而发明一个明显很弱的选项。随后在任何分支深入开发之前先找廉价工作cheap work来消除它或改变它的排名。优先做最可能推翻某个候选、或解决多个候选共有的假设的那个检查。规则给出的有用检查清单包括阅读定义该行为的接口reading the interface that defines the behavior追踪一条真实路径或运行一个端到端小用例tracing a real path or running a tiny end-to-end case测量有争议的量measuring the disputed quantity构建一次性原型building a throwaway prototype。一旦某个决定性的约束或观察排除了一个分支就立即停止探索不要因为已经投入了而继续。对于不便宜的重要未知规则给出两条指导优先选择不依赖该未知的设计prefer a design that does not depend on it只有当未知的可能结果确实会改变候选的可行性或最终选择时才在该未知上分叉不要探索通向同一决策的组合。这与 folly/agents/critic-iterate.md 的证据Evidence小节一脉相承它要求只用最便宜的直接检查来定论一个主张不要把一个任务输入当作已独立验证的事实不要声称超过证据支持的程度。设计审查阶段做的每一个廉价检查产出的正是这些证据条目。四、在展开前筛选候选Screen candidates before elaborating them候选方案在付出设计成本之前先过一道可行性筛查viability screen。只要满足以下任一条立即拒绝漏掉了某个必需的触发条件或失败模式破坏了某个约束或不变量依赖于一个已被证伪的主张depends on a contradicted claim可能以不可接受的后果失败can plausibly fail with unacceptable consequences。规则特别强调一个判断陷阱一个没有依据的假设是一个需要去解决或绕开的未知而不是把候选排为可行的理由。换句话说也许能行不等于可行——在证据层面悬而未决的假设只能把候选降级或打回验证阶段不能把它当作可行项参与排名。这一条与critic-iterate.md对设计审查的批评维度直接对应其 General Cycle 中列出的设计维度包括问题是否被完整覆盖Full problem covered?、排名前是否做了可行性检查Viability checked before ranking?、不变量是否被保留Invariants preserved?——正是本节三条筛查标准的运行时复现。五、比较幸存方案Compare the survivors正确性优先成本殿后通过筛查的方案才有资格进入比较。规则明确规定只使用可能改变本次决策的因素并针对正确性修复工作给出强制优先级——先比较下面三个维度再谈便利性优先级维度核心问题1覆盖与放置Coverage and placement设计是否覆盖了每一个必需的触发条件和失败模式是否在一个拥有所需信息、且掌管该不变量的层次上实现2假设Assumptions哪些断言必须保持为真它们被支持得有多好3失败行为Failure behavior如果设计是错的、或某个依赖失败它是暴露问题并限制损害还是继续给出一个貌似正确但实际错误的结果关于用现有生产设计佐证候选规则给出严格前提只有当现有设计产生相关行为的原因是相同的、且当前场景的条件也成立时它才能支持该候选。必须陈述行为、原因、匹配条件三者相似性本身既不能证明也不能推翻候选。这三个维度比较完之后才比较只在这里有意义的成本实现与维护的复杂度性能或能力损失上线与回滚rollout or reversal风险。规则有两条刚性约束成本不能挽救一个未通过可行性筛查的候选——顺序不可颠倒在可行候选之间必须明确说出决定最终选择的那笔权衡tradeoff而不是含糊地说各有优劣。六、没有可行方案或没有明确赢家时停下来如实说设计审查最容易被忽略的一步是承认决策无法在当前证据下收敛。规则明确授权当必须做出选择、而合理调查后既没有可行设计、也没有明确赢家时停下来陈述仍然悬而未决的是什么以及什么证据或决策能够解决它只有当请求的产出物确实能用条件分支时才提供条件分支不要为了凑完设计而凭空发明行为。这在大型 C 代码库中极其重要一个为了交付而编造的设计会把不变量破坏的风险从设计阶段推迟到线上故障而那时修复成本已经放大了一个数量级。规则的设计哲学是诚实的未解决好过虚假的已完成。七、落地用最难用例检验领先候选并记录不确定性在写实现计划implementation plan之前设计审查还有最后一关用已知最难的用例检验领先候选test the leading candidate against the hardest known case——如果最强候选连最苛刻的用例都过不了现在发现比实现后才发现便宜得多对每个未解决的未知只考虑可能改变可行性或选择的结果——不要为每个未知枚举所有可能世界记录仍然不确定的内容以及什么观察结果会证明应该重新审视这个选择what observation would justify revisiting the choice。这一步让设计决策从一次性快照变成可复审的基线未来一旦出现规则所说的观察结果就有明确依据回访决策而不是靠感觉返工。这条记录不确定性的要求与critic-iterate.md的双重修订Dual Revision机制衔接当评审发现一个MUST_TAKE级别的问题改变了所提修复的行为、使某个回退方案失效、或暴露了一个决定性的正确性假设时必须重新应用design-vetting.md之后再编辑——设计审查不是一次性的它贯穿到评审闭环结束。八、与其他规则的协作边界design-vetting.md不是孤立文件它与 folly/agents 规则包的其余部分有明确的触发边界加载时机按 folly/agents/critic-iterate.md 的加载清单作者与编排会话在选择实质性设计或正确性修复之前加载design-vetting.md同时默认加载core/breadcrumbs.md与core/conflicts.md后者用于裁决规则冲突例如评审发现与已加载规则冲突时先应用core/conflicts.md再做分流。与写作规则的衔接folly/agents/writing.md 在Document小节规定任何实质性设计或修复提案都必须先应用design-vetting.md且提案要说明问题发生在哪里、提案必须产出什么结果——这正是第一节Frame the decision的写作层落地。提案的正文结构Motivation / Mechanism / Alternatives rejected / Killswitch rollback也与第五节先正确性、后成本的排序一致。与维护规则的衔接folly/agents/CONTRIB.md 要求编辑规则前阅读最近的.contrib.md理解规则为何存在、改动必须保留什么阅读name.entrypoint.md了解什么触发这条规则并遵循每条规则都是用血写成的原则。如果你想修改design-vetting.md本身必须先读 design-vetting.contrib.md 和 CONTRIB.md。注意加载边界design-vetting.md只在用户规则文件或另一条运行规则点名时才被加载design-vetting.entrypoint.md 中的触发文本应被复制进用户规则文件其中的路径以用户规则文件所在位置为基准。.contrib.md与.entrypoint.md是开发材料不得作为任务策略加载。九、一张可复用的检查清单把design-vetting.md的五阶段浓缩成一张在任何设计任务开始前都可以逐项打勾的清单阶段一界定决策设计必须产出的结果是否一句话可说清所有必需的触发条件与失败模式是否已列出必须保持的约束与不变量是否明确可能改变胜负的未知项是否已命名是否已声明已知复现案例可能不完整阶段二解决未知是否已用最廉价的直接检查推翻或验证关键假设读接口、跑端到端用例、测量、一次性原型被决定性约束排除的分支是否已停止探索是否倾向于选择不依赖未解决未知的设计是否避免了探索通向同一决策的组合阶段三筛选候选每个候选是否覆盖全部触发条件与失败模式是否保持全部约束与不变量是否不依赖任何已被证伪的主张是否会以不可接受的后果失败无依据的假设是否被当作待解决未知而非可行理由阶段四比较幸存者是否按覆盖与放置 → 假设 → 失败行为的顺序比较用现有生产设计佐证时是否陈述了行为、原因、匹配条件三者成本比较是否只包含在此处有意义的项是否明确说出了决定选择的那笔权衡无法决策时是否停下并如实说明需要什么证据阶段五落地与记录是否用最难的已知用例检验了领先候选对未解决未知是否只考虑可能改变结果的情形是否记录了不确定性以及什么观察结果会触发重新决策这套流程的最终目的正如规则原文所强调的不要让第一个貌似可行的设计在需求尚未挖全、假设尚未核查、不可行选项尚未剔除之前就被打磨成型。在 Folly 这样复杂、跨模块、且大量依赖不变量如并发数据结构的内存序、futures 的回调生命周期、coro 的取消语义的代码库中设计阶段多花一次廉价检查往往能省掉实现阶段一整轮的返工与线上事故。【免费下载链接】follyAn open-source C library developed and used at Facebook.项目地址: https://gitcode.com/GitHub_Trending/fol/folly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考