十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Archon Simplify Review 透镜实战解析:用“最小自洽形态“审查 AI 代码变更中的过度设计

Archon Simplify Review 透镜实战解析:用“最小自洽形态“审查 AI 代码变更中的过度设计 Archon Simplify Review 透镜实战解析用最小自洽形态审查 AI 代码变更中的过度设计【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon导读本文深入剖析 Archon 开源仓库中 SDLC 审查工作流的一个专职透镜lens——review-simplify.md。它只负责回答一个问题这次变更是否用超出结果所需的结构才交付了既定的产出读完本文你将掌握该透镜的完整审查契约——如何锚定验收契约、如何用结构决策测试与惰性测试识别过度设计、如何用四条证据字段证明一个更小的形态、如何划分 Important/Suggestion 严重级别并写入标准化产物simplify.md 与 discoveries JSON以及它在 Archon 多透镜并行审查架构中的精确位置与执行细节。一、透镜定位它是结构审查不是代码审查在 Archon 的 SDLC 审查包中一次完整审查由多个并行运行的专家透镜组成而 Simplify Review 是其中专职负责结构形态的一路。它的核心信条在文档开篇即已点明写代码是廉价的维护它、以及回收其中的选择权option value才是昂贵的。只猎捕一种缺陷变更通过超出结果所需的结构才交付了既定产出。这句话定义了整个透镜的审查边界保护的对象是有意义的不可变约束invariants、受支持的行为、有长期价值的既有基础——而不是偶然形成的实现形态accidental implementation shape只读永远不修改文件、不提交、不向任何外部平台发布内容唯一允许的写操作是写入$ARTIFACTS_DIR下的产物文件单一定义域简化simplify与正确性code、边界类型seams、测试覆盖tests严格分工互不越界。从工作流定义 archon-review.yaml 可以看到它的调度位置code、seams、simplify、tests四个透镜默认全开errors仅在失败路径相关时开启docs为 auto 模式。特别值得注意的是 YAML 中针对 simplify 的一段注释——它原本被置于仅建议的宪章之下、实测产出为零于是被重构为每个变更都必跑、且永远不做门控选择的默认透镜零产出度量的是降级本身而不是这个问题。这说明该透镜在 Archon 中是被明确当作结构性退化drift的第一道防线来对待的。二、审查前的契约锚定scope.md 与风险分级Simplify Review 从不直接面对仓库而是先读取两个输入$ARTIFACTS_DIR/review/scope.md—— 由前置节点 review-scope 写入精确记录本轮要审查什么验收契约required outcome 与显式非目标、审查对象PR 或工作区 diff、模式全量或增量、变更文件清单、复现 diff 的确切命令、上一轮报告路径与已审查 head SHA 游标项目的architecture.md如果存在。审查必须锚定在已接受的工单accepted work order所声明的不可变约束上而不是锚定在这段代码看起来还能更好的主观印象上。深度按变更能摧毁什么来缩放——文档给出了六个高危维度每个都需要显式尝试去证伪其所依赖的不变量不可逆或破坏性路径生命周期所有权持久化契约与 schema凭据与认证边界集成边界共享状态上的并发。而纯文本prose-only改动只需最浅的审查深度。关于 Light Mode增量模式当存在上一轮报告时本透镜进入 light moderesolve-review-mode.py 会校验prior_report路径存在且是文件缺失即抛错终止这是断掉的延续契约绝不能静默当作全量审查。在 light mode 下Simplify Review 的流程是先核验上一轮分配给自己这个透镜的发现仍是 open / 已在某 SHA 修复 / 被证伪然后只审查 delta——即git diff cursor..HEAD这段增量绝不重做全量扫描。三、结构决策测试五类先行的怀疑对象文档要求先看那些引入协调成本或过早关闭选项的决策并列出五类具体怀疑点怀疑对象要问的问题数据形态与所有权Data shape and ownership核心类型是否匹配主导访问路径数据是否被复制、拍平、重建、缓存、或以多重表示存在而其实一个所有者就能承载它能力内聚性Coherent capability变更是在加深一个真正有用的抽象还是把特殊情况的协调摊薄到调用方、层级和 schema 各处并发Concurrency如果另一个参与者并发修改共享状态答案是否安全地是什么都不做如果不能是否应隔离状态而不是同步它基础原语Foundations是否一个更小的原语就能让下游逻辑豁然开朗先删死重再加脚手架只有每个后续阶段都受益时才提前加脚手架。过早的机制Premature machinery每一个新增的状态、生命周期、包装器、配置面、回退、扩展点分别对应哪个真实受支持的变体这五类问题的共同指向是区分必要结构与协调成本——前者加深单一抽象后者把同一个决策分散到多处。四、惰性测试The Laziness Test删除优先扁平优先结构决策测试之后文档给出了一套操作性的惰性测试优先删除与直接控制流而不是引入 helper 或抽象保持调用链足够扁平让所有权与决策易于追踪——一个隐藏了大量实际工作的丰富接口本身并不构成深层调用链即接口丰富 ≠ 深链隐藏工作是负债不是资产每个决策收敛到单一事实来源one source of truth并把解析后的结果以平凡的方式传递下去质疑穿过类型、schema、流水线或层级的新信号——去找那个本就知道答案的所有者或原语在小透传pass-through、表示泄漏、重复选择变成长期协调成本之前抓住它们DRY 的对象是共享结构与数据模型而不是每一行重复代码——显式重复有时比一个过早的抽象更简单。紧随其后的是整个透镜最容易被误读的一句行数不是不变量。更少的状态、表示、概念、同步点、分支和所有权边界才是。如果结果会耗尽人类维护者请重新考虑它。这句话把简化的定义从代码变短精确校正为结构变少也是后面证据门槛与严重级别设计的理论基础。五、证据门槛Require Proof四条字段一条都不能少文档明确规定只有当证据同时建立以下四件事时才允许报告一条简化发现所需的产出与不可变约束required outcome and invariant可避免的机制及其具体的维护或正确性成本avoidable machinery concrete cost一个承载相同行为的、已存在的或更小的原语existing or smaller primitive支持替换的调用方、测试、契约或针对性验证callers / tests / contracts / focused validation。这四条合起来把简化从主观品味提升为可仲裁的技术主张。随后文档强制要求证伪在相关处针对并发、顺序、持久化、兼容性、错误语义尝试证伪这个更小的形态禁止用聪明的代码替换显式代码、把复杂度移进 helper、为假设中的复用发明新抽象、或把审查扩大成无关清理。同时Simplify Review 严守透镜分工不做重复劳动——这三类问题被明确划给别的透镜错误的产出结果→ code 透镜review-code.md 的行为缺陷未被保护的行为→ tests 透镜边界上缺失的类型→ seams 透镜review-seams.md 的hand-synced pair类发现。Simplify 只报告结构本身重叠部分交给下游的合成器synthesize合并合成规则见 review-synthesize.md——合并后的因果发现必须保留每个贡献透镜的sources列表。关于最小可证伪命令文档要求当执行可行时运行能证伪某个替换方案的最小命令而且必须以本仓库记载的方式调用——即 steering 文件如 AGENTS.md、CLAUDE.md点名的包脚本与调用规则绝不使用它们警告过的临时变体。这条规则与 code 透镜共享同一原则确保验证结果在项目自己的约定下可复现。六、严重级别只有 Important 与 Suggestion没有 CriticalSimplify Review 的严重级别体系非常克制Important—— 一个具体的、保持行为不变的更小形态且携带上述完整证据。审查中发现的可简化项必须在本次产出的变更上修正而不是延期合并起来的复杂度会累积成漂移drift让之后每一次变更都为之买单而且一个裁决可能仅仅取决于简化即 verdict 可能因简化发现而被阻塞。Suggestion—— 更小的形态是推测性的或替换方案有无法证伪的行为风险。非阻塞但必须指明什么证据能让它升级。最关键的一条边界是本透镜没有 Critical。理由在文档中说得非常直白更小的形态本身永远不是紧急事故真正错误的机制属于 code 透镜。这与 review-code.md 中Critical 仅限安全破坏、数据丢失、不可恢复的契约破裂的定位形成对照——结构问题再严重也只是维护负债不是线上事故。而在合成阶段review-synthesize.mdCritical 与 Important 都会阻塞ready: trueSuggestion 永不阻塞。七、输出契约simplify.md 的精确格式审查结束后透镜必须向$ARTIFACTS_DIR/review/simplify.md写入结构化产物格式被严格规定每条范围内的发现以sources: [simplify]开头紧跟严重级别Important / Suggestion上述四条证据字段且必须带file:line引用更小的形态the smaller shape会消失的东西what disappears任何真实的权衡real tradeoff。之后是examined-and-clean 清单逐一命名让你决定放过这些结构的决定性原语、不可变约束或受支持变体。在 light mode 下则是对每条先前发现给出判定。若没有任何东西可以消失就简短说明并列出检查过什么——但永远不要声称该变更是最优的never claim the change is optimal。范围外发现的处理discoveries JSON如果证明出 scope.md 验收契约之外的有用工作绝不能把它变成阻塞性发现。正确做法是写入$ARTIFACTS_DIR/discoveries/review-simplify.json它是一个 JSON 数组每条记录含title—— 标题claim—— 主张evidence—— 具体的file:line事实或命令结果relation——adjacent相邻或scope_conflict与范围冲突source_node—— 固定为simplify。无发现则不写文件绝不追加到其他透镜的文件也绝不记录单纯的怀疑。这些原始发现随后由合成器统一校验、去重并合并进discoveries.json/discoveries.mdreview-synthesize.mdadjacent记录永不阻塞就绪状态。收尾自检文档要求两条硬性收尾逐条核实引用的每个file:line真实存在然后以一行汇报结束review findings: $ARTIFACTS_DIR/review/simplify.md并附上按严重级别统计的发现数。八、辨析Simplify Review顾问与 Simplify Changed Code执行者仓库里还有一份名称相近但性质完全相反的文档archon-simplify-changes.md。二者容易混淆务必区分维度review-simplify.md本透镜archon-simplify-changes.md角色只读顾问产出sources: [simplify]的发现文件执行者直接编辑文件、bun run type-check、bun run lint、分阶段git add指定文件后提交推送产物$ARTIFACTS_DIR/review/simplify.md discoveries JSON$ARTIFACTS_DIR/review/simplify-report.md的 Before/After 对照报告变更控制永不修改仓库只允许 stage 自己编辑过的文件禁止git add -A/./-u判断准则结构形态、证据门槛、最小自洽形态可读性优先清晰优于紧凑、小且自明正确的改动前者是 SDLC 审查流水线中的结构透镜后者是独立的一次性简化执行命令。二者共享同一条底线简化不得改变行为。九、在 Archon 审查流水线中的完整闭环把 Simplify Review 放回整条流水线它的上下游是清晰定义的mode节点调用 resolve-review-mode.py依据是否存在先验报告判定全量 / 延续模式scope节点生成 scope.md含验收契约、目标、head SHA、diff 复现命令四个默认透镜code / seams / simplify / tests在fresh上下文中并行独立运行各自产出发现文件——Simplify Review 就在这一步执行本文描述的完整契约review-complete屏障以all_done容忍个别透镜的流中断synthesize节点review-synthesize.md重新以fresh上下文读全部透镜产物按因果合并、对抗性核验每条 Critical/Important 的file:line、分配稳定 IDR1、R2…产出裁决ready/action与报告并在 PR 模式下以带!-- archon-review-report --标记的单条规范评论发布。其中 Simplify Review 的发现以sources: [simplify]进入合并若某条发现跨透镜重叠合并后保留全部贡献 lens 的sources如sources: [code, simplify]。一次延续轮中先验报告的 review-coverage 是权威依据透镜不会重跑。结语最小自洽形态是一种可证明的技术主张Simplify Review 透镜最值得借鉴的设计是把简化从审美判断改造成证据驱动的工程判断先锚定验收契约与不可变约束再用结构决策测试与惰性测试定位过度结构用四条证据字段证明更小的形态用证伪对抗并发、顺序、持久化、兼容与错误语义最后以高度结构化的产物simplify.md、discoveries JSON、一行汇报完成闭环。它的存在本身也说明了一个设计立场结构审查不是锦上添花的建议而是每个变更都必须经历的默认关卡——正如 archon-review.yaml 中那句注释所言结构问题一旦被降级为仅建议它的产出会归零而代价将由每一个后续变更的维护者持续偿还。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表