Axıs
随笔
技能目录

Creation Log: lean

Creation Log: lean

来源项目

  • 项目：Hertz（本地优先 AI 内容工作台，~91k 行源码 / 857 条 pytest / 2,164 行活跃文档）
  • 路径：审计对象全仓（外部仓库 ~/Code/Hertz，下列文件名均相对其根）；证据集中在 monoline 域、MD_STUDIO.md、tests/、telemetry.py
  • 时间：2026-10-25（三路只读审计：代码与注释债、文档债、测试债）

提炼触发条件

同一模式在 ≥3 个独立场景重复出现：

  1. 重造轮子：monoline 域 5 处手写 ffmpeg exec→communicate→rc→raise 样板（错误尾长 [-400:]/[-300:]/[-200:] 各自漂移），而带取消与超时的 _run_cmd 在 common.py（pipeline/producers 下，:37）现存、零引用——agent 会话局部性的实证。
  2. 过程叙事沉淀进设计文档：MD_STUDIO.md（docs/ 下，524 行）沉淀 10+ 段「早先是 bug、切片 N 修好」的修复叙事，违反该仓自家「一个事实一个权威 / 修复叙事进 ADR」规矩；同类叙事另见于 CHANGELOG 与注释中的 v0.x 引用（backend ~605 处，构成与 CHANGELOG 平行的第二份时间线）。
  3. 注释与代码事实矛盾：telemetry.py:28 与 registry.py（factory/ 下，:177）的 docstring 写「失败吞掉」而代码 raise（registry 另有 5 处同款注释）；tts_zh.py（monoline/ 下，:38）注释承认「不再使用」而死代码未删。
  4. 跨项目重复：用户独立报告 Hertz 之外的多个 vibe coding 项目同病（随意注释、丑文档、越开发越慢）——模式不是单仓特有。

反向锚点（防止把 skill 写成「多测试文化」的对立面）：同一次审计证明该仓 857 条测试可直言删除的仅 4 条（<0.5%），断言普遍为相对断言，~120 条为变异验证红线，D-233/D-234 的真实缺陷正是判据测试抓住的。故「少测试」的正确形态是增量准入高门槛 + 性质断言 + 速度分层，不是删存量——这条写进了 §3。

包含决策（为什么放进 skill）

  • 按「产出物类型」分节（注释/文档/测试/轮子/提交），因为 agent 的失误发生在「写某类东西的那一刻」，按处境切分才能在触发时被用到。
  • 每条原则配可执行判据（三段式：原则/推导/判据），判据全部是问句或动作，没有口号。
  • 外部交叉验证（见下）与亲历证据互证的部分：注释写不写（Ousterhourt/Linux style）、删不诚实测试（Google flaky tests）、重复与错误抽象的张力（Sandi Metz × Rule of Three）、git 检查点与定性判断（Willison vibe engineering）。

排除决策（为什么没放进 skill）

  • 测试覆盖率数字、marker 具体名、pytest/xdist 配置：分层原则通用，落点是项目事实，写进来即分层泄漏。
  • 命名规范、模块划分、依赖纪律：axiom 第三部五、六章已有，重述即双真相源。
  • 结构治理与深打磨流程：butler / overhaul 的职责，只留分工表互链。
  • 「每次会话全仓扫债」：与 butler 的反仪式设计冲突，收窄为两个时机（交付前/接手陌生模块）。
  • 「删掉所有注释/文档」的反向极端：审计实证问题注释仅 0.2–0.3 条/千行，病不在量在质（说谎、叙事、复述三类）。

外部交叉验证

  • Simon Willison《Vibe engineering》（2025-10）：写下来、定性判断、git 检查点——与 §5 负熵提交、§6 扫债互证。
  • Google《Flaky Tests at Google》：隔离/删除不诚实的红——§3 flaky 判据来源。
  • Ousterhout《A Philosophy of Software Design》注释章 + Linux kernel style(9)：注释记录不变量与 why，不复述代码——§1 判据来源。
  • Sandi Metz「duplication is cheaper than the wrong abstraction」与 Rule of Three——§4 双向张力来源。
  • 《Software Engineering at Google》Testing Overview 的脆断言/过度指定论述——§3 性质断言来源。

验证方式

  • 首次实测：Hertz 债清偿批次（P0 安全修 → P1 结构债 → P2 文档瘦身 → P3 测试分层），每批以仓库门禁 verify.sh --quick 验收
  • 在 Hertz 之外的项目各试一轮（待后续会话）