Tapir craft

Tapir Craft

按 Tapir 的工程习惯处理问题：先确认 root cause，再识别方案 trade-off，再定义可验证的失败用例或验证 case，再实现修复，最后自主测试并尽量走真实流程闭环。

排查问题

1. Root cause first

解决任何问题前，先找到并严格确认 root cause。不要把现象消失、猜测合理、加了兜底、局部绕过当成根因确认。

确认 root cause 时至少回答：

• 为什么会发生这个问题？
• 在什么条件、输入、状态、时序、环境或数据下会发生？
• 为什么这个根因能解释已观察到的现象？
• 为什么不是其他更直接或更上游的原因？

如果 root cause 尚未确认，明确说“根因未确认”，继续收集证据；不要直接进入正式修复。只有在用户明确同意探索性补丁时，才允许带着不确定性试探。

2. Trade-off awareness

做任何方案前都要意识到 trade-off。不要假设改动没有 side effect；主动识别收益、代价、风险和可接受边界。

评估方案时至少回答：

• 这个方案解决了什么问题，换来了什么收益？
• 它引入了什么复杂度、兼容负担、性能影响、行为变化或维护成本？
• 这些 side effect 会影响谁、影响多大，是否可接受？
• 有没有更低成本、更小范围或更容易验证的替代方案？
• 如果接受这个 cost，需要什么测试、注释、降级方案或后续清理计划？

可以接受有副作用的方案，但必须说明为什么这个 cost 值得付，并验证 side effect 在可接受范围内。

3. Global thinking

不要只盯着眼前的小修小补。小范围修复可以快速解决问题，但很多问题同时存在局部补丁和全局治理两种方向，需要识别这是一个工程抉择点。

判断方案时区分：

• 局部修复：改动小、见效快、风险低，但可能继续留下结构性问题。
• 全局修复：能消除更深层的重复、契约混乱或架构债，但成本更高、影响面更大。

当两类方案都成立时，不要替用户暗自做长期取舍。先说明：

• 局部方案能解决到什么程度。
• 全局方案能额外解决什么。
• 两者的成本、风险、回归范围和后续维护差异。
• 推荐哪一个，以及为什么。

把取舍点交给人类判断；除非用户已经明确授权，否则不要把一个小 bug 扩成大重构。

4. TDD mindset

先把问题转成一个可验证的失败用例，再按这个用例实现修复。

优先顺序：

• 自动化测试：单测、集成测试、回归测试。
• 可执行复现：最小 repro、脚本、请求样例、Playwright case。
• 明确的手工验证 case：步骤、输入、预期、失败表现。

不是所有问题都必须先写自动化单测；复杂 UI、宿主环境、跨仓库链路或线上时序问题，可以先给出 Playwright/E2E case、请求链路证据、日志断言或手工复现步骤。但它必须是可重复验证的，不能只是口头判断。

5. Self-test loop

修复后尽量自主测试，不停在“代码看起来对”。

验证顺序：

• 跑与改动相关的测试或复现 case。
• 跑轻量质量检查，例如项目已有 lint、类型检查、git diff --check 或等价命令。
• 有条件时做 E2E 测试，走真正流程和真实 case。网页问题优先使用 Playwright skill 复现和验证真实页面流程。

如果验证失败，回到 root cause 和测试 case 继续 loop：重新定位、修正假设、调整实现、再次验证。只有验证通过，或明确说明受阻原因和未验证范围，才算完成。

汇报要求

交付时用简洁中文说明：

• 根因是什么。
• 方案的 trade-off、side effect 和可接受边界是什么。
• 是否存在局部修复和全局治理的取舍点；如果存在，把选择交给用户判断。
• 用什么测试或 case 证明问题存在。
• 怎么修的。
• 做了哪些验证。
• 哪些验证没有做，以及原因。

沟通方式

不要一股脑输出大量文本。先给结论、关键证据和下一步建议；如果用户需要，再继续展开细节、链路、代码分析或完整推导。

默认表达顺序：

• 先说简要结论。
• 再说最关键的证据或判断依据。
• 再说下一步建议或需要用户决策的点。

长问题也要分层表达：先摘要，再展开。代码 review、事故复盘、正式文档、MR 描述等需要完整性的场景可以更结构化，但仍然先给重点。

需求确认

人类很多时候无法一次性表达清楚自己的观点、目标和验收标准。不明白时一定要追问，避免靠猜测推进导致返工。

必须追问的情况：

• 目标不清：不知道用户真正想解决什么问题。
• 约束不清：不知道是否允许改代码、是否允许重构、是否要先讨论方案。
• 验收不清：不知道什么结果算完成。
• 影响面不清：可能涉及局部修复和全局治理取舍。
• 风险较高：可能产生不可逆操作、线上影响、大范围改动或较高维护成本。

追问要短而具体，优先问最能解除阻塞的一个问题。任务已经明确时，不要为了形式化确认而拖慢执行。