AI 辅助工程直觉

解决什么问题

AI 编程助手最常见的工程事故不是写不出代码，而是过度设计和掩盖问题。用户提一句"加个导出功能"，它可能顺手把项目重构成插件架构；一个空指针崩溃，它可能在调用处加 try/catch 再补个默认值，根因仍留在原处。更常见的是：改完代码不留注释，下一个维护者——无论是人还是另一个 AI Thread——只能靠猜；声称"测试通过"但其实只跑了编译；项目代码变了，仓库里的交接文档停留在三个月前。

技能如何工作

这不是一套强制流程，而是一组工程提醒，按信号触发：

• 先理解目标，不把实现方式当需求。 用户说"用 Redis"，真正需求可能是"降低延迟"——两者不总是等价。
• 信号驱动的参考读取。 一次任务通常只需读一到两个最相关的 references/ 文档。比如发现代码里在用默认值和兼容函数反复兜底时，才去读 references/root-cause-and-contract-boundaries.md；没有这类信号就直接跳过。
• 最小完整改动。 修复放在真正拥有该责任的位置——症状最后出现的地方不一定是根因所在。不预先设计所有未来，也不为追求最少行数留下半个修复。
• 注释是实现的一部分。 每个新建或实质修改的文件，顶部必须有块注释说明功能、职责边界和关联；符号级别有行注释或文档注释。空泛的"处理数据""业务逻辑"不算完成。
• 验证看行为，不看编译。 根据变更的影响面和失败代价选择检查。能跑真实测试就优先真实测试；测不了就拆出可测部分，用模拟和推理补足，并明确说出哪些风险还没被证明。
• 项目代码变了，交接就要更新。 仓库没有交接约定就按 assets/HANDOFF_TEMPLATE.md 在 docs/handoffs/ 下新建日期文件，写清目标、行为变化、决策、证据和下一步。

适用边界

• 这是提醒，不是流程——不需要向用户展示完整检查清单，只说明会影响结果的判断、证据、取舍和风险。
• 机械的代码修改（改字段、改类型、搬函数）只做必要实现和相称验证，不因为触发了本技能就自动扩大架构或安全调查。
• 会改变产品方向、重大成本、安全边界或外部状态的取舍，交还用户决定。
• 纯信息查询、只读审查或只诊断且没改项目代码的任务，不创建交接文档。
• 源码理解类任务建议与 $progressive-pseudocode-review 组合使用。