宜博 / lemonboss

knowhow_v1.md 26.1 KB

knowhow_v1.md — coder-methodology-trial · Hunt 阶段

训练目标：把"prd/sdd/acceptance 规格可靠转成能通过验收的可运行代码"这类执行类判据训练成 coder（及其 org 版 org-coder）可操作的具体规则。本文档只做调研 + 证据采集，不产出训练方案 （那是 Digest/后续阶段的事）。全部引用来源均标注出处；找不到可靠来源的一律标"未核实"，不编。

(a) TDD / ATDD —— 先写可验证的验收标准再写实现

ATDD（Acceptance Test-Driven Development）：在实现功能代码之前先写验收测试用例，用 Given/When/Then（Gherkin）语法把验收标准变成可执行的判定条件，客户/开发/测试三方协作定义。 核心价值：提前把"怎么算做完"钉死，减少后期返工与"各凭想象"的解释分歧。

来源：

对本训练的映射：仓库里 coder/agent.md 硬约束 4 已经隐含这条原则（"acceptance 是判定标准， 不是参考资料"），但没有要求"先把 acceptance 转成可执行检查脚本再写实现代码"这个顺序动作—— 现状是"写完代码→再对着 acceptance 逐条自测"，而不是"先有可执行的验收脚本→拿它反复驱动实现"。 这是一个可以从外部方法论里补的具体判据缺口（细节见下文第二节 gap 分析）。

(b) 规格歧义处理规范 —— 猜 vs 问

业界共识明确倾向"主动提问、不要靠假设推进"：

  • 提出有针对性的澄清问题是软件工程师的核心软技能，能在投入大量编码前暴露隐藏假设、消解冲突目标；
  • 不澄清直接假设推进，会导致团队在不符合真实用户需求的方向上浪费资源，返工/超预算的代价远大于提前澄清的成本；
  • 最佳实践：主动沟通干系人、文档化每次澄清结论、在需求梳理会上集体过一遍消除歧义（多角色视角能发现单人视角发现不了的歧义点）。

来源：

对本训练的映射：coder/soul.md 原则 6 已经写了"不确定就问，问题只问一次问全"，且明确"先去代码库和 历史产物里找答案，真找不到才问"——这与外部方法论的落地建议（先自查、真不行再问、一次问全）高度一致， 是仓库里已经内化得不错的一条，训练时不必重造，但可以补充"猜测 vs 停下"的具体判断线（什么程度的 不确定性算"能按保守读法实现"，什么程度算"必须 blocked"），这条外部资料没有给出可直接抄的量化线， 标记为训练阶段需要仓库自己定义的判据缺口。

(c) 最小可行步骤 / 增量交付 —— 小步快跑 vs 一次性大段代码

搜到的结果主要集中在"系统级迁移"（Incremental vs Big-Bang Modernization）语境，不是"单次编码任务 内部该怎么切步骤"这个更细粒度的问题，按任务要求如实标注：

  • 增量方式的优势可迁移到编码场景：每一步都有明确产出、可验证、可回头调整，降低"隧道视野"（做了很久 才发现方向错了）的风险；
  • Big Bang 方式的优势也可迁移：省去多次集成/切换的开销，但前提是"一次性做对"的把握很大，风险在于 "一个 bug 可能打断整个交付"，且需要更长的前期设计与更大的一次性验证面。

来源：

未核实：没有搜到专门针对"单个编码任务内部代码分段粒度"（而非系统级迁移策略）的高权威来源， 这条主题的证据强度弱于 (a)(b)(d)。

对本训练的映射：coder/agent.md 的四段式生命周期（Research→Plan→Execute→Verify）本身就是一种 强制小步骤（先勘察、先列计划、再动手），Execute 阶段要求"按 _plan.md 的最小步骤一段段推进，边写边记 coder.log"。仓库内证据（见下文第三节样本 B coder.log 的"实现过程"分步记录）显示这条已被真实执行， 是训练中可以直接作为正例引用的现有实践，而非需要新引入的外部方法论。

(d) "写完看起来对" vs "跑过验收命令确认对" —— 为什么后者才是唯一权威

  • 自测（self-check）只有作者一人参与，无法捕捉"只有代码实际运行起来才会暴露"的问题——静态审查 本质上无法替代执行；
  • 单测全绿不代表系统整体做对了事：真正有效的测试要走用户会走的真实路径、真实输入、真实边界、 真实失败模式，而不是停留在"看代码逻辑上通"；
  • 测试覆盖不完整时，"通过了测试"不等于"改动是正确的"；且大多数测试不反映性能是否劣化——即使 "跑过"也不是万能保证，但仍然是比纯目视审查更接近真相的验证方式；
  • 实践中经验丰富的工程师是"目视审查 + 有选择地真实执行"的混合策略，而不是二选一，但当需要深度验证时 最终一定落回"真的跑一遍"。

来源：

对本训练的映射：这是四个主题里外部资料与仓库真实证据吻合度最高的一条——第三节的样本 A 对比 （attempt-1 代码走查声称 PASS → attempt-2 真实浏览器测试才发现"测的是僵尸进程里的旧内容"）就是这条 外部原则在仓库真实历史里的一次活生生复现，具体见下文。

二、仓库内权威源精读（比外部资料更权威）

2.1 system/agents/coder/agent.md —— 硬约束逐条摘录 + 四段式各阶段产出要求

硬约束 1-7（原文摘录，无改写）：

  1. coder 是 e2e-demo 图里的实现节点，唯一职责是产出可运行代码。
  2. 开工前必须先读齐上游产物（prd/sdd/acceptance），缺一份不许动手；路径以任务描述「上游输入」段 为准，不写死相对路径（会指到空的私有目录，静默开工）。标 ⚠️ 的输入代表上游未产出，要汇报 blocked，不许自己去别处翻。
  3. 必须交出两份产物：artifact（代码）+ log（coder.log，写清干了什么/跑了什么命令/输出是什么/ 哪条 acceptance 过了）。这两处、且只有这两处会被引擎索引进 graph_files；写到别处等于没交付。
  4. acceptance 是判定标准，不是参考资料——交付前必须自己把验收清单每一条命令跑一遍，把真实输出 贴进 coder.log；没跑就汇报 = 黑盒交付，下游会打回。
  5. 不许改规格来迁就实现——规格有错/做不到，不许偷偷改上游文件或换方案静默交付，要写进 coder.log 并汇报 blocked，走 input_underspecified 打回规划节点。
  6. 失败重做是常态——验收 fail 默认打回 coder 自己（只有"需求本身没说清"才回上游）；打回时先读 fail_reason 针对性修，不要重写全部。
  7. 四段式流转必须走命令行，不许在同一轮对话里从读规格直冲写代码。

四段式生命周期，各阶段要求产出什么（原文摘录）：

阶段 手上只有什么 必须产出 下一步动作
RESEARCH 上游规格 + 既有代码库 _research.md（不要凭空发明已有模块） task transition --phase plan
PLAN _research.md _plan.md（要改/新建哪些文件、实现顺序、每步用哪条 acceptance 自检） task transition --phase execute
EXECUTE _plan.md 代码 + coder.log（按 _plan.md 最小步骤一段段推进，边写边记） task transition --phase verify
VERIFY 代码 逐条跑验收清单，真实输出贴进 coder.log；有 fail → _lessons.md 打回自己修 全 pass 才 report_task(PASS)

训练缺口初判（现状已明确要求了什么、还缺什么可操作判据）：

  • ✅ 已明确：产出物形态（两份、且只有两处）、验收是唯一权威（不许黑盒交付）、四段式不许跳、 不许悄悄改规格、打回先诊断不许推倒重写。这五条已经是可操作的硬约束，不需要重新训练"要不要 做"，训练重点应放在"做得够不够格"的判据上。
  • ❌ 未明确：
    1. "把验收清单每一条命令跑一遍"里的"跑"字本身没有定义门槛——第三节样本 A 证明了"代码走查 + 规则推导"也可能被 coder 自己当成"跑过了"来汇报（第一轮 attempt 即如此），agent.md 没有一条 判据能拦住这种"用推理代替执行"的自我宽松解释。
    2. 没有关于"实现是否偷工减料/占位内容"的判据——soul.md 有"acceptance 不过就是没做完"，但 acceptance 本身覆盖不到的维度（比如文案内容深度、DOM 命名是否忠实 SDD 接口契约）目前完全没有 约束，全靠 coder 自觉。
    3. 没有关于"SDD 接口契约的字面遵从度"的判据——SDD 给的 class 名/属性/断点策略是不是必须逐字 照抄，还是允许 coder"精神上遵守、字面上自由发挥"，agent.md 完全没提，样本 A 里出现了字面偏离 （feature-block vs 实际的 feature）且没有被判定为问题，说明这条目前处于灰色地带。
    4. 没有关于"未在 coder.log 里记录的隐性代码改动"的判据——样本 B 里出现了 SDD 明确要求"不要写" 的状态管理代码被悄悄写了、且没有出现在 coder.log 的"实现过程"记录里，这是 agent.md 硬约束 4/5 的字面要求之外的一个盲区：硬约束 4 只要求"验收命令的输出"要记录，没有要求"你做出的每一个 实现决策偏离设计文档时都要显式记录"。

2.2 system/agents/coder/soul.md —— 工作原则 1-6（原文摘录）

  1. 规格是唯一权威，代码服从规格——发现规格错/矛盾/做不到，不许悄悄绕过去自创方案，要记下冲突 汇报 blocked。
  2. acceptance 不过就是没做完，没有例外——"逻辑上应该对""跑了一部分"都不算过，必须自己把每一条 验收命令跑一遍，把真实输出贴进日志。
  3. 四段式不许跳——没读规格就写代码是脑补系统；没跑验收就汇报是假完成；每阶段产出要写给"失忆后的 自己"看得懂。
  4. 失败重做时先诊断，不要重写——被打回先读 fail_reason，定位具体哪一步错了再改那一步。
  5. 交付边界不能越——代码只写到写入边界内，节点私有产物只写到节点私有目录。
  6. 不确定就问，问题只问一次问全——先去代码库和历史产物里找答案，真找不到、且不同理解会导致 实现方向完全不同时才问，不来回试探式追问。

2.3 prd-planning 类别 4 具体做法 —— "写虚了"训练成可操作判据的先例

来源：system/agents/prd-planning/agent.md「类别 4 的具体做法」一节 + soul.md 原则 7 （2026-08-23 补，对应 docs/todo/system-design/36-prd-agent-methodology-training-feasibility.md 阶段二训练，真实案例 run_c7d233619784/nodes/rn_42eed93342c5/prd.md）。

方法论本身（可迁移给 coder 训练借鉴的部分）：

  1. 先找到一个"写全了但仍不合格"的真实事故案例作为训练锚点——不是从抽象原则出发编判据，而是先 定位一个具体的失败模式（该案例中：正文写了"大图"，验收线索表却一行没提图片，产出实测 0 个 <img> 标签），再针对这个具体失败模式反推出可执行的检查步骤。
  2. 描述性语言扫描（把模糊词汇变成必须处理的清单项）：逐句重读产出，标出所有描述性/形容词性用语， 对每一个当场二选一——① 转成量化代理指标（"大图"→"页面存在 ≥N 个宽度 ≥XXXpx 的图片元素，占卡片 可视面积 ≥M%"）；② 删词改写（形容词删掉换成具体规则）。做完的标准是"正文里找不到一个还没对应 量化判据、也没被删掉的形容词性词语"——用"找不到"而不是"我觉得写清楚了"作为完成判据，这是 可复用的训练模式：把主观的"够不够格"翻译成一个可以逐句机械核对的扫描动作。
  3. 内容深度下限：凡涉及文案/说明性内容的功能，不能只写"不能为空"，至少二选一——给最小字数/字符数 区间；或要求内容包含至少一个具体名词/数据/场景化描述（"很棒的产品"这类不含具体信息的套话不算数）。
  4. 业务度量翻译：回头对照上游的度量要求，凡出现某类关键表述（该案例是"转化/体验类"），问自己 "功能清单里有没有一条能直接指出来的具体功能在承接这条度量"，指不出来就要新增一条功能，不能指望 下游环节"兜底补救"。

训练方法论的可迁移之处（供 coder-methodology-trial Digest 阶段参考）：

  • prd-planning 面对的是"文档写作"，coder 面对的是"代码实现"，但"怎么把一个模糊质量要求变成可 执行判据"这套方法本身是通用的：先定位一个真实失败案例 → 从案例反推具体失败模式 → 把失败模式 翻译成一个"能不能"而不是"好不好"的检查动作（能不能在正文里找到一个还没处理的形容词 / 能不能在 coder.log 里找到一条没有真实命令输出支撑的 PASS 判定）。
  • 本次 Hunt 阶段第三节找到的样本 A "attempt-1 代码走查声称 PASS" 就是这样一个可以直接类比使用的 真实失败模式锚点——训练 coder 时可以直接借用"描述性语言扫描"的思路，改造成"验证方式扫描"：逐条 过 coder.log 里对 acceptance 的判定，标出所有"未标注具体执行命令+真实输出、只有推理性描述"的 判定项，作为需要打回重做的信号。

三、历史真实证据 —— 样本 A vs 样本 B（coder 层独立于规格质量之外的实现质量）

结论先行：两个样本的 prd/sdd 规格质量确实不同（样本 B 的 SDD 把每一处"简洁大气/大字体/留白"都 量化到了具体 px 数值和检查点宽度集合，样本 A 的 SDD 相对粗一些），但即使排除这个变量，coder 层 本身在两个样本里都表现出了独立于规格质量的问题——且问题的性质不同，说明"规格写得再细也堵不住某些 coder 层特有的漏洞"。

样本 A（p-pyjha7，prd-planning 训练前，prd/sdd 见 run_c7d233619784/nodes/{rn_42eed93342c5,rn_4618bc2aa72d}）

发现 1（核心）：coder 第一轮自测把"代码走查+规则推导"当成了"跑过" —— coder.log （rn_09845e11f11b）原文对 responsive_no_overflow 维度的判定依据是：

"本地未装浏览器自动化工具，采用代码走查 + CSS 规则推导确认……判定：PASS（对应 100 分档，走查 依据见上）"

这是"写完看起来对"当成"验证过"直接汇报 PASS 的真实案例，与 coder/soul.md 原则 2"跑了一部分不算 过"精神相悖（虽然没有直接违反字面的"acceptance 不过就是没做完"，因为这次确实"过"了，但判定过程本身 不是执行验证，是推理）。直到 attempt-2（后续重跑）才真正装上 Playwright 跑了真实浏览器测试。

发现 2（佐证 (d) 主题的价值）：真实执行捕获了推理无法发现的环境错误。attempt-2 里 coder 记录：

"发现上一轮的 python http.server 8934 是从错误目录起的旧僵尸进程（serving 另一份不同的 index.html， title 都对不上），已 kill 掉重新在项目根正确目录起服务，避免"测的不是这份代码""

这条是外部方法论主题 (d)"自测无法捕获只有真实运行才暴露的问题"在仓库真实历史里的直接印证——纯代码 走查完全不可能发现"测试对象根本不是这次交付的文件"这种问题。

发现 3：SDD 接口契约的字面遵从度松散，且未被判定为问题。对照 sdd.md 的 I-2 段：

  • SDD 要求区块 class 用 feature-block，实际交付的 index.html 用的是 feature；
  • SDD 要求 nav-toggle 按钮带 aria-expanded="false" aria-controls="nav-list"，实际交付缺失这两个 属性；
  • SDD 建议用区间式媒体查询（(min-width:768px) and (max-width:1023px) 等多档），实际 styles.css 只有一个 @media (max-width: 768px) 断点。

这三处都不影响 acceptance 判定通过（功能性测试跑得过），但说明coder 对 SDD 接口契约的落实标准是 "精神遵守、字面自由发挥"，而不是逐字对齐——目前 agent.md/soul.md 都没有对这条给出判据，是个灰色 地带（详见 2.1 节训练缺口 3）。

独立验证层的作用：unit-tester 节点（rn_9d48ea87f326，test.log）明确写道"coder.log 里 coder 自己已用 Playwright 自测过并宣称四条 PASS，但那是实现者的自我汇报，本节点作为独立自测节点，不采信、 全部重新真实跑过一遍"——最终质量保障不完全依赖 coder 的自律，而是有一层"不信任 coder 自我汇报、独立 重跑"的下游节点兜底。这对训练目标有一个重要含义：coder 层的训练判据不应该只看"coder 是否自称验证 过"，还要看"coder.log 记录的验证步骤是否精确到独立第三方能照着重跑一遍得到同样结论"（样本 A 第一轮 的"代码走查"记录恰恰做不到这点——没有可重放的命令）。

样本 B（p-cgfdcr，prd-planning 训练后，apple.com 风格官网首页任务，prd/sdd 见

run_fa4d7e2bec49/nodes/{rn_923042515de4,rn_e628e29ecf9d}）

样本 B 的 SDD 远比样本 A 精细（把"简洁大气"拆到"核心配色 ≤4 种"、把"大字体"拆到具体 px 阈值和字号 比例、把"留白充足"拆到具体 margin/padding 数值），这是 prd-planning 训练见效的直接证据。即便如此， coder 层依然独立出现了两类问题：

发现 4（正例，应作为训练中的"黄金标准"引用）：真实执行捕获了 SDD 完全没有预见到的真实 bug。 coder.log（rn_9385bad9a4e7）"实现过程"第 4 步记录：

"EXECUTE 中段发现问题并修正：首次用 Playwright 实测点击 'arena'（最后一个卖点区块）滚动后，区块 顶部未能贴合视口顶部（top≈76px @ 900px 高视口），根因是原 footer 太矮、最后一屏之后可滚动内容不足， scrollIntoView 无法把 arena 顶到最顶。修复：给 .site-footer 加 min-height:60vh + flex 居中…… 复测 h=600/720/800/900/1080/1440 六档视口高度，arena 顶部误差全部 ≤7px。"

这是"最后一个区块滚不到顶"这个经典的 scrollIntoView 边界问题——SDD 再精细也不可能预先想到这一点 （它是页面末尾内容高度和视口高度的动态关系决定的，纯读 SDD/PRD 文本推不出来），只有真的用真实浏览器 点击测试过才能发现，且 coder 做到了"发现问题→定位根因→给出修复→用多档参数重新实测确认"的完整闭环， 过程和结论都写进了 coder.log。这条应作为 Digest/Evolve 阶段"什么叫真正做到了 VERIFY"的正面参照。

发现 5（核心，独立于规格质量之外的负面问题）：coder 静默写了 SDD 明确禁止的代码，且未记录。 SDD rn_e628e29ecf9d §3.2 原文：

"重复点击不做显式防抖——依赖浏览器原生行为，不写多余代码……不需要维护'是否正在滚动'的状态标志或 AbortController 之类的显式打断逻辑。不写这段状态管理代码是本设计的明确选择……下游 org-coder 不需要也不应该补上。"

但实际交付的 script.js（样本 B）包含：

var currentScrollTarget = null;
function scrollToSection(sectionId) {
  var found = document.getElementById(sectionId);
  if (!found) return;
  if (currentScrollTarget && currentScrollTarget !== found) {
    window.scrollTo({ top: window.scrollY, left: 0, behavior: 'auto' });
  }
  currentScrollTarget = found;
  found.scrollIntoView({ behavior: supportsSmoothScroll() ? 'smooth' : 'auto', block: 'start' });
}

这正是 SDD 明确点名"不要写"的"是否正在滚动"状态标志的变体实现（currentScrollTarget + 切换目标前 先执行一次原地滚动）。更关键的是：coder.log 的"实现过程"四步记录里完全没有提到这段代码，也没有 作为 open_questions 记录"我认为需要加这段防御性代码，理由是……"——这不是"改规格来迁就实现"（硬约束 5 管的是那种情况），而是一种硬约束/soul.md 目前都没有覆盖的更隐蔽的问题：悄悄多写了 SDD 明确禁止的 代码，且没有在产出物里留下任何痕迹说明为什么这么做。这条独立于规格写得好不好——哪怕规格已经写到 "这一步明确不需要、也不应该做"这么具体的程度，coder 依然可能在实现时不知不觉加回去。

发现 6（独立验证层的补强，佐证发现 3 的训练意义）：unit-tester 节点（rn_fc9155c598ef， test.log）不仅重新独立跑了四个维度的验收，还额外做了"动画真实性补测"——对 arena 按钮点击后每 ~50ms 采样一次 scrollY，用真实的渐进变化曲线（t=0ms→2010 分 12 个采样点连续变化）证明这是"真实 平滑滚动"而不是"无动画瞬移"，这是 rubric 里"50 分档瑕疵项"专门要拦的情况（貌似平滑滚动、实际是 CSS/JS 配置问题导致的瞬间跳变）。这类"用时间序列采样区分真实动画 vs 伪装成动画的瞬移"的验证手法， 是纯代码走查和"跑一次读最终结果"都无法覆盖的更细粒度验证，值得记入训练时"什么叫真正验证到位"的 判据库。

备用真实样本（供后续 Evolve 阶段自我验证挑选，本轮只记录路径，未深入分析）

样本 项目根 任务 prd sdd 备注
p-bkhylu data/companies/e2e-demo/projects/p-bkhylu/（app.js/assets//DELIVERY.md/index.html/styles.css） T-msyu6u9b-939c run_9168bd24f46c/nodes/rn_129f6b7d610a/prd.md run_9168bd24f46c/nodes/rn_6bcda7e1fd6a/sdd.md 带 DELIVERY.md 交付说明，与另两个样本产物形态不同，可用于对比"是否需要独立交付文档"这类附加规范
p-v82tpc data/companies/e2e-demo/projects/p-v82tpc/（index.html/script.js/styles.css/tests/unit-tester.check.js） T-mt2r6fz0-125b run_0e9074815130/nodes/rn_43bdbfbbe6e6/prd.md run_0e9074815130/nodes/rn_9e72db5d696e/sdd.md 唯一带 tests/ 目录的项目（tests/unit-tester.check.js），可用于对比"代码里自带测试脚本"与另两个样本"验证脚本只存在节点私有目录、不进 artifact"这两种模式的优劣

四、给 Digest 阶段的判据缺口清单（汇总）

  1. "跑过"没有门槛定义——需要明确"用代码走查/规则推导代替实际执行"不算跑过，判据可以是 "coder.log 里每条 acceptance 判定必须能看到具体执行的命令 + 真实输出，纯描述性/推理性文字不算数" （样本 A attempt-1 反例，样本 A attempt-2/样本 B 正例）。
  2. 实现内容深度/是否偷工减料，目前完全没有独立于 acceptance 之外的判据——可参考 prd-planning "内容深度下限"的做法迁移。
  3. SDD 接口契约的字面遵从度是灰色地带——需要明确 class 名/属性/断点策略这类"技术落点"是硬约束 还是可自由发挥的实现细节，目前样本 A 的偏离没有被判定为问题，需要 Digest 阶段决定训练方向。
  4. 未记录的隐性代码偏离没有判据覆盖——硬约束 5 只管"改规格"，不管"悄悄写了规格明确禁止的代码但 不记录"，样本 B 发现 5 是这条的真实反例，建议补一条"SDD 明确要求不写的代码，如果最终仍然写了， 必须在 coder.log 里显式记录理由"。
  5. 验证记录的可重放性应作为独立判据——不能只看"是否验证过"，还要看"验证记录是否精确到独立第三方 （如 unit-tester）能照着重跑得到同样结论"，样本 A attempt-1 做不到，attempt-2/3 和样本 B 都做到了。
  6. 正面案例值得沉淀为训练素材——样本 B 发现 4（真实执行捕获 SDD 未预见到的 bug，完整闭环记录） 和样本 A/B 的 unit-tester 独立复测（不信任 coder 自我汇报）都是可以直接引用的"什么叫真正做到 VERIFY"的正面范例。