WhyBuddy: Instructions file for Claude Code

给接手这个仓的人（含 AI）

这个仓的知识不在文档里，在代码注释和测试 docstring 里。随便打开一个 services/*.py，模块头往往是几百字的事故记录：哪天真机踩了什么、为什么这么写、 上一版错在哪。那不是话多，是这个仓的记忆方式——读代码前先读它的注释。

下面是从那些注释里反复出现的纪律，按被违反的频率排。

---

一、动手之前，先确认哪条链真的在跑

这是本仓最贵的一条。 2026-08-16 一天之内因为违反它打偏三次：

改了闭环重建那一步      而模型是主循环里生成的      （v5_full_driver:1260 vs :531）
改了提示词的收尾        同样在没被使用的那一步
把合并接在老生成器上    真正在跑的是 spec-first     （v5_capability_executor:492）

三次的代码本身都是对的，三次都因为装在不通电的插座上而毫无效果，三次都靠真机 日志才发现——每次损失 25 分钟真机跑 + 一次部署。

做法：改之前先在目标路径打一行日志或加一条断言，确认它真的被执行到。 tests/test_refine_merge_reaches_the_live_path.py 就是这条纪律的具象化。

一之二、护栏装对了地方，条件却永远不成立

这是第一条的变种，2026-09-04 一夜里发作两次，同一个人写的两条护栏。 两次都不是装错位置——装在真跑的那条路上，但它依赖的输入在真机上根本不出现：

护栏  「文本只许压残留 hop，不许压显式意图」        写成 forced is None or forced in FACTORY_HOPS
真机   首轮点火按设计不传 forcedTool → forced is None → 文本照样赢
       [control] forced hop=structure hasSpec=0 hasPages=0   后面连 capabilityPlan= 都没有

护栏  「已有 SPEC、host 没点 spec，不许把 spec 塞回去」  加在 _factory_tools_from_state
真机   run_spec_first 转手 select_workflow(tools=…) 拿 preset.tools 当计划，
       ['pages','structure','bind'] → ['spec','pages','structure','bind']   spec 又回来了
       stage=specfirst.spec ms=18428 …… 页面落库：0 份

两次的单测都是绿的，因为判据自己构造了护栏需要的那个输入（喂 {'forcedTool':'rehearse'}），而真机不喂。第二次更贵：用户答完假设卡点确认， 整跳预算烧在重起草一份不一样的 SPEC 上（5 页 16 节点 → 6 页 17 节点）， 页面一页没画，而刚确认的假设是针对旧那份的。

做法：护栏的判据必须喂真机那一发的原样载荷，不许自己拼一个。 拿不到就先去日志里抄一行。写完再问一句：这个条件在真机上真的会成立吗？ tests/test_topic_is_not_an_instruction.py 与 tests/test_remaining_chain_does_not_redraft_spec.py 是这条的具象化—— 前者第一条判据先证明「不设边界时文本确实会赢」，后者干脆直接执行产线源码， 不重抄逻辑（重抄的判据只能证明"我抄对了"）。

二、判据必须能被变异咬住

写完测试，把修复改回去，确认它变红。没红就是判据没用。

本仓被这条抓到过的真实形态：

• 判据 grep 源码里的标识符，而那个词同时出现在文档字符串里 → 变异后照样绿。 修法：匹配前先剥注释。
• 判据写 "Produce the complete" not in tail，而实际收尾是 "Produce the five-system JSON now."（不含 complete）→ 断言直接打空。 修法：盯语义（还在要求"产出一份"），别盯某句话的字面。
• 11 条测试全绿，但把调用点删掉照样全绿——它们只直接调那个函数，从没验证 它接在链路上。这就是下面第三条。

三、"闸全绿但东西没了"

本仓数到第十次以上的失败形态：正向判据齐全，反向判据缺失。