engineering-method-footguns

工程方法中的常见陷阱

从生产环境中的 Kotlin 和 Compose Multiplatform 应用中整理出的 9 个陷阱，每个都位于 references/ 下的一个简短文件中。每个文件都介绍可行模式、陷阱（实际使用中会出问题的具体方式及其原因），以及包含可针对用户自己的代码树运行的命令的验证方法部分。

如何使用此索引。 将即将编写的代码或正在排查的症状与下方条目进行匹配：每个条目都会说明主题，以及遇到哪种症状时应查看该条目。在提出代码或修复方案前，请使用 Read 工具阅读所有可能适用的文件；每个文件都不到 150 行。如果验证命令中提到了源项目的路径，请替换为用户代码树中的对应路径。

交叉引用。 文件中以反引号括起来、但未在此列出的陷阱名称，位于同级区域的技能中；使用 glob ../*/references/<name>.md 打开。

工程方法

• run-discriminating-experiment-first — 当两个几乎相同的事物表现不同时，先计算仍有差异的变量数量，并进行一次替换或交换测试，至少排除一半变量，再编写任何修复方案。当同一症状在两次或更多次修复尝试后仍然存在、某个组件或屏幕或平台正常工作而紧挨着的近似版本却不行，或者每次尝试都需要漫长的构建并占用他人的精力时使用。
• noop-actual-not-platform-limit — 在多平台项目中，空的或直通式的平台实现意味着没人实现它，而不是平台做不到——在告诉任何人某项功能不可能在该平台实现之前，先检查依赖项解析出的变体和声明该功能的源集。当某项功能“在桌面端/iOS 上无法正常工作”、某个平台文件原样返回输入或函数体为空，或者准备将某项功能归结为平台限制时使用。
• read-build-logs-bottom-up — 阅读构建日志时，先翻到末尾查看结果，再找到第一个错误标记以确定原因——不要从任一端截取固定长度的窗口，因为因果消息和失败横幅分别位于输出的两端。当后台构建结束而你正准备总结结果、日志只显示“task X FAILED”却没有原因，或者筛选结果为空而你正准备称构建成功时使用。
• changelog-as-war-story — 维护一个有版本控制的 Markdown 文件，记录带日期的条目，包括症状、机制、已排除的可能性以及移除变通方案的条件；并通过一条规则确保条目随改动一同提交。当修复依赖于不明显的行为，之后可能有人会“清理”掉相关代码、同一调查不断重复，或者要引导人类或 Agent 熟悉一个布满高成本陷阱的领域时使用。
• writing-agent-skill-house-style — 编写一项经得起对抗性审查的 Agent 技能：描述中同时包含触发条件和读者眼前的错误症状，提供简短的背景说明，以占据文件主要篇幅的陷阱章节为核心，并附上实际运行过的验证命令。当编写或审查 SKILL.md、技能读起来像文档而非来之不易的经验，或者审查时总发现源代码仓库无法佐证的说法时使用。
• xml-to-compose-sequencing — 规划大型 XML 到 Compose 的迁移顺序：先处理最棘手的屏幕；预计真正的工作是整合分散的状态，而非替换组件；还要预留时间处理导航，因为它会连带要求迁移路由序列化。当规划跨多个版本的 UI 迁移、尽管屏幕“已迁移”而布局文件数量却不见减少，或者决定下一步转换哪个屏幕时使用。
• commit-archaeology-red-flags — 挖掘仓库历史时避免被误导——没有正文的提交，其文件统计才是它真正的摘要；嵌套仓库的版本更新会用一行指针改动隐藏全部内容；合并提交则会将分支的决策过程压缩成一个主题。当追溯某项设计的来由、blame 指向的提交说明不了任何事情，或者某项改动看似只涉及一行代码却不可能如此简单时使用。
• removing-a-feature-audit-shared-handles — 删除与较新功能重复的功能——同一输出上的两种效果会相互叠加——之前先审计其他哪些代码也在使用那个被移除功能似乎独占的句柄，删除其他平台上的空操作存根，并在判断移除是否生效前强制停止，因为已经附加的外部效果会在改动后继续存在。当用应用内实现替换委托式集成，或者移除某项功能后它似乎仍在运行时使用。
• a-stated-rule-needs-annotated-exceptions — 设计规则只有在每个合理例外都在调用处注明原因，并且规则本身可通过 grep 查找时，才能长期有效——否则无法区分例外与违规，规则也会悄然失效。涵盖规则声明应放在哪里、原因应写在哪里、如何将审计范围限定在规则实际管辖的代码，以及基于注释进行检查的局限性。当既定约定逐渐偏离、审查者无法分辨有意为之还是疏忽大意，或者准备把规则写进文件头并以为这样就能确保遵守时使用。