企业官网建设流程全解析

kotlin-footguns 是一套从生产级跨平台音乐应用 SimpMusic 中挖掘出来的 Kotlin 与 Compose Multiplatform 实战技巧库，收录了 224 个"踩坑地图"式技能。其中工程方法论组沉淀了三条最值钱的做事原则：判别性实验、战报式 Changelog 和 Commit 考古学。它们能帮你少走弯路、少烧构建、少踩已经有人付过学费的坑。

一、kotlin-footguns 是什么：先看懂这张"踩坑地图" 🗺️

kotlin-footguns 的每个技能都是一份独立的SKILL.md，而且最大的章节永远是Traps（陷阱）——某个技术在实际开发中具体会怎么翻车，以及如何在你自己的代码树上验证失败、验证修复。

• 来源不是官方文档，而是三年生产环境的崩溃报告、失败发布和用户反馈
• 每个文件控制在 60–140 行，两分钟就能读完
• 每条结论都配了"验证命令"，让你能自查，而不是照单全收

想看完整索引，打开 CATALOG.md；想了解整体背景，读 README.md。本清单的主角，是工程方法论组（N 组，共 7 个技能）。

二、判别性实验：先数变量，再动手改代码 🔍

适用场景：两个几乎一样的东西，一个正常工作、一个坏掉了；同一个问题你已经试过两三次修复都没用。

新手最常见的坏毛病是"按最强的猜想去改，改完验证，不行再换下一个猜想"。这个循环代价极高：每次猜错都要付出一次完整的验证成本，而猜错时你什么信息都没得到。

判别性实验的思路是：先数一数两边还有几个变量没对齐，只要大于 1，就不允许你写修复。先设计一个"交换或互换"实验，让一次构建就能砍掉一半的嫌疑原因。

真实案例：一个页面头部有两个控件共用同一个视觉特效——圆按钮没有效果，长条药丸控件有效果。前四轮都在换形状、去包裹层、喂真实内容，全错了。第五轮把两个控件的位置互换，特效跟着药丸走、而不是跟着位置走。位置这一个变量被一次排除，剩下的才是控件自身几何形状的问题。

几条可落地的口诀：

• 动手前先写两句话："如果特效跟着控件走，那么……""如果它留在原地，那么……"。写不出来，说明这个实验没有区分度，别花冤枉轮次
• 交换时只动两个位置，别顺手改缩进、别改名、别整理——那就不再是一次干净的交换了
• 实验代码要打个标记，清理时别把"还没读数的实验"删掉
• 只改善症状、却说不清为什么，那是第二份待解释的观察，不是可以上线的修复

完整规则见 skills/run-discriminating-experiment-first/SKILL.md。

三、战报式 Changelog：把"试过又否掉"的东西写下来 📝

Commit message 只说"改了什么"，很少说"试过哪些、为什么放弃、什么时候才能拆掉这个临时方案"。这些信息没地方放，最后只能由一个不知道它存在的人重新踩一遍。

kotlin-footguns 提倡的做法：在仓库根目录维护一个按日期记录条目的 markdown 文件，每进一个不熟的领域之前先读它。一条有用的战报要带四样东西：

1. Symptom（症状）——别人当时看到了什么，用他们自己的话说
2. Mechanism（机制）——为什么会这样，讲到让修复说得通的那个层面
3. What was ruled out（否掉了什么）——试过但不管用的合理替代方案，明确点名
4. The exit condition（退出条件）——上游或平台发生什么变化后，这条才可以删掉

最高价值的部分是"否掉了什么"，也是赶时间时第一个被砍掉的。没有退出条件的临时方案会永远留在原地，永远算"必需"。

几条关键纪律：

• 条目要和代码改动一起落，别想着"之后再补"——那条永远等不来的后续提交，本身就是陷阱
• 查问题时先搜这个 markdown，再搜 commit message
• 满足退出条件的条目应该删除，而不是原地归档

模板与自查命令见 skills/changelog-as-war-story/SKILL.md。

四、Commit 考古学：别被 git 历史骗了 ⛏️

历史是那些"正忙着、还不知道什么才重要"的人写下的证据。三条红旗，占了从历史里得出错误结论的大部分：

红旗 1：没有正文的 commit。标题会同时"说少"和"说多"，文件统计（--stat）才是它真正的摘要。比如一条end of friday标题什么都没交代，却可能是历史中改动最大的提交之一；一条refactor code folder标题夸大了重构，其实只是搬文件。

红旗 2：子仓库指针更新。当一部分项目放在子仓库（submodule）里，推进它的 commit 在统计里只显示 1 个文件、1 行改动，真实内容全藏在另一侧仓库的那两个指针之间，普通历史命令在这里看不见它们。

红旗 3：压扁的合并。merge 的标题只是分支名，不写决策。一个来回一周的分支，抵达时只剩一行；若先被 rebase 或 squash，中间的推理根本不在这个仓库里。

几条保命的习惯：

• 想引用哪个 commit，就读一遍它的统计，一条命令的代价
• 别把"一行改动"读成"很小的改动"，子仓库指针、生成文件、锁文件都会这样
• blame 落到一次搬移动画上时别停，先跟着文件穿过搬移
• 别只搜默认分支，也别只按当天用过的词去搜

方法详见 skills/commit-archaeology-red-flags/SKILL.md。

五、同组的三块"补强"方法论 🧩

工程方法论组还有几个和上面三条互相成就的技能，值得一起带走：

• 空实现不是平台限制——多平台项目里一个空的、直通的平台实现，通常意味着"还没人写"，而不是"平台做不到"。判断前先查依赖的解析变体和源集。见 skills/noop-actual-not-platform-limit/SKILL.md。
• 从下往上读构建日志——去底部找结论，再去第一个错误标记找原因，永远别用一个固定行数的窗口去截日志。见 skills/read-build-logs-bottom-up/SKILL.md。
• 这套仓库自己的写作风格——描述里同时带上触发场景和读者正盯着的错误症状，Traps 章节占大头，验证命令要真跑过。见 skills/writing-agent-skill-house-style/SKILL.md。

六、如何上手这套工程方法论清单 🚀

1. 打开 CATALOG.md，定位 N 组（工程方法论 / 纪律，共 7 个技能）
2. 挑你当前正在卡的场景：修不好同样的 bug → 判别性实验；要进一个不熟的领域 → 战报式 Changelog；想搞清楚"为什么代码长这样" → Commit 考古学
3. 每个技能末尾都带"Verifying it"自查命令，对着你自己的仓库跑一遍，把结论落到自己树上

kotlin-footguns 的价值不在教你某个 API 怎么用，而在把这些已经用崩溃报告、失败发布和评审轮次付过学费的教训，提前摆到你面前。三条方法论记住一句话就够：先数变量再动手、把否掉的东西写下来、读历史前先怀疑它。