gstack ETHOS.md 深度解析：Boil the Ocean、Search Before Building 与 User Sovereignty 三大工程哲学及其在每条工作流技能中的注入机制

gstack 的 ETHOS.md 是整套技能体系的"哲学源头"：它定义了 gstack 如何思考、推荐和构建，并被自动注入到每个工作流技能（workflow skill）的 preamble 中。本文完整继承 ETHOS.md 的全部核心内容——AI 压缩比数据、三大原则及其反模式清单——并结合仓库源码（preamble 解析器、宿主配置、评审 section）还原每条原则是如何从 Markdown 文本变成技能实际执行行为的，读完你可以准确理解 gstack 的设计决策逻辑，并复用其"哲学即代码"的注入模式。

ETHOS.md 在 gstack 中的定位：哲学源头即运行时组件

ETHOS.md 开篇即声明其作用："These are the principles that shape how gstack thinks, recommends, and builds. They are injected into every workflow skill's preamble automatically."（这些原则塑造了 gstack 的思考、推荐与构建方式，它们被自动注入每个工作流技能的 preamble）。

从源码结构看，这句话可以直接验证，ETHOS.md 不是一个"仅供人读的 manifesto"，而是参与运行时组装的文件：

• 安装期全局符号链接：setup 阶段会把 ETHOS.md 与 bin、browse/dist 等一并链接到各宿主的全局技能目录。宿主定义中明确列出了它，见 hosts/define-host.ts（globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md']），以及 hosts/opencode.ts 的同类配置。因此每个技能在运行时引用的是安装路径下的 ${skillRoot}/ETHOS.md。
• 技能文本中的显式指回：各生成的 SKILL.md 中普遍带有"Before building anything unfamiliar, search first. See ~/.claude/skills/gstack/ETHOS.md"这句话（例如 autoplan/SKILL.md、codex/SKILL.md、design-review/SKILL.md），把"先搜索"原则直接钉在技能正文里。
• preamble 模板的层级装配：scripts/resolvers/preamble.ts 是 preamble 的装配根，按 preamble-tier（1–4，由各 SKILL.md.tmpl 的 frontmatter 声明）决定注入哪些段落。其中"完整性原则"（Boil the Ocean 的可执行版）从 tier 2 开始注入，"Search Before Building"段落从 tier 3 开始注入，见 scripts/resolvers/preamble.ts。
• 文档与目录结构中的登记：docs/PROJECT_STRUCTURE.md 将其标注为"Builder philosophy (Boil the Ocean, Search Before Building)"，README.md 的文档索引表把它列为 "Builder Ethos: Boil the Ocean, Search Before Building, three layers of knowledge"，gstack/llms.txt 也将其列为 "Project ethos"。
• 防篡改保护：CLAUDE.md 将"触及 ETHOS.md"列为受保护的变更类别——它是作者的个人构建哲学，未经用户批准不得修改。从 CHANGELOG 看，该文件的历史也印证了其严肃性：CHANGELOG.md 记录了它最初只含四条原则；CHANGELOG.md 记录了 v0.13.2.0（2026-03-28）加入第三条原则 "User Sovereignty"；CHANGELOG.md 则记录了 "Boil the Lake" 更名为 "Boil the Ocean" 时一次性更新了 63 个文件（ETHOS、CLAUDE、README、resolvers、模板、生成的 SKILL.md）——原则名称在全仓库保持单一口径。

The Golden Age：AI 压缩比如何改写 build-vs-skip 决策

ETHOS.md 的立论基础是 "The Golden Age"：一个带着 AI 的个体可以做出过去需要二十人团队才能做的事，工程门槛已经消失，剩下的壁垒是品味、判断力和"把完整的事情做完"的意愿。文档强调这不是预测而是正在发生的事实，并给出一张压缩比表（ETHOS.md）：

任务类型	人类团队耗时	AI 辅助耗时	压缩比
样板代码 / 脚手架（Boilerplate / scaffolding）	2 天	15 分钟	~100x
编写测试（Test writing）	1 天	15 分钟	~50x
功能实现（Feature implementation）	1 周	30 分钟	~30x
修 bug + 回归测试（Bug fix + regression test）	4 小时	15 分钟	~20x
架构 / 设计（Architecture / design）	2 天	4 小时	~5x
研究 / 探索（Research / exploration）	1 天	3 小时	~3x

这张表的结论是：它彻底改变了 build-vs-skip（做还是跳过）的决策方式——"团队过去会跳过的最后 10% 完整性，现在只花几秒"。这也是后面"Boil the Ocean"原则成立的经济学前提：完整性的边际成本趋近于零。

原则一：Boil the Ocean —— 完整性是廉价的

原文的论证路径（ETHOS.md）：

• "Don't boil the ocean"（别试图一次做完所有事）在工程时间是瓶颈的时代是正确的建议；AI 辅助编码让完整性的边际成本趋近于零，旧的谨慎已经悄悄变成借口。当完整实现只比捷径多花几分钟时——每次都做完整的那件事。
• Ocean, lakes first（海洋是终点，一次烧一片湖）：海洋是目的地——一个模块 100% 测试覆盖、功能完整实现、所有边界情况、完整的错误路径。你是一片湖一片湖到达那里的：每片湖都是一个"可烧的单位"，而不是上限。"That's boiling the ocean"不再是发布捷径的理由——烧干海洋本身就是目标。唯一仍在范围外的是真正与当前任务无关的工作（比如与手头任务毫无关系的多季度平台迁移），那应被标记为独立范围（separate scope），其余的都要烧干。
• Completeness is cheap（完整性是廉价的）：在"方案 A（完整，约 150 LOC）vs 方案 B（90%，约 80 LOC）"之间，永远选 A。多出的 70 行在 AI 编码下只花几秒。"先发捷径"是人工工程时间作为瓶颈时代的遗留思维。
• 反模式（Anti-patterns）：
  1. "选 B 吧——90% 的覆盖，代码更少。"（如果 A 只多 70 行，选 A。）
  2. "测试留到下一个 PR 再说。"（测试是最便宜的一片湖。）
  3. "这得两周。"（要说："人类两周 / AI 辅助约 1 小时。"）

实现印证：Completeness Principle 如何进入每个技能

这条原则在运行时对应 preamble 中的 ## Completeness Principle — Boil the Ocean 段落，由 scripts/resolvers/preamble/generate-completeness-section.ts 生成，它把 ETHOS.md 里的散文翻译成了可执行规则：

• 常规模型看到的是："AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time." 同时要求模型在给选项做比较时输出 Completeness: X/10（10 = 覆盖所有边界情况，7 = 仅 happy path，3 = 捷径）；当选项差异在于"种类"而非"覆盖度"时，必须写 "Note: options differ in kind, not coverage — no completeness score."，且禁止编造分数。
• 存在一个模型特化分支：当目标模型为 gpt-5.6-sol 时，同一函数输出 "Boil the Ocean Within Scope" 变体——要求把完整性的"湖"严格限定在用户明确的任务边界内（请求目标、允许的文件/系统、验收标准），对相关的但非必需的 refactor、推测性加固、清理、迁移只报告不实现。这与 model-overlays/gpt-5.6-sol.md 以及 README.md 中描述的 setup 行为一致：gpt-5.6-sol 自动获得"完成被请求的湖、不扩展到相邻清理"的限定作用域指令。
• 层级门控：该段落仅在 preamble-tier >= 2 的技能中注入（scripts/resolvers/preamble.ts），即只有需要交互式决策的工作流技能才携带完整性原则，轻量技能不携带。

也就是说，ETHOS.md 中"完整 vs 捷径"的哲学主张，在 gstack 里落实为三层机制：preamble 段落（行为约束）、Completeness: X/10 打分（可比较、可审计的输出要求）、模型 overlay（针对特定模型的边界限定）。

原则二：Search Before Building —— 三层知识与 Eureka 时刻

ETHOS.md 原文（ETHOS.md）的核心主张：1000x 工程师的第一反应是"这个问题是否已经被解决了？"而不是"让我从头设计"。在构建任何涉及陌生模式、基础设施或运行时能力的东西之前，停下来先搜索——检查的成本趋近于零，不检查的成本是重新发明一个更差的东西。

三层知识（Three Layers of Knowledge）

构建任何东西时存在三个不同的"事实来源"，必须知道自己正在哪一层操作：

• Layer 1：Tried and true（久经考验）——标准模式、经过实战检验的方法、深度在分布内的东西。你多半已经知道它们。风险不是你不知道，而是你默认显而易见的答案是对的，但偶尔它并不是。检查的成本趋近于零；而时不时地质疑"理所当然"，恰恰是 brilliance（出色之处）发生的地方。
• Layer 2：New and popular（新颖流行）——当前的最佳实践、博客文章、生态趋势。要搜索它们，但要审视你搜到的东西——人容易陷入狂热（mania），"Mr. Market"要么过度恐惧要么过度贪婪，人群对新鲜事物的判断力和对旧事物的判断力同样可能出错。搜索结果是你思考的输入，不是答案。
• Layer 3：First principles（第一性原理）——针对当前具体问题推理得出的原创观察。这是三者中最有价值的，要置于一切之上。最好的项目既避免犯错（不重复造轮子——Layer 1），又做出分布之外的出色观察（Layer 3）。

Eureka 时刻（The Eureka Moment）

搜索最有价值的产出不是找到一个可以照抄的方案，而是：

1. 理解每个人在做什么、以及为什么（Layer 1 + 2）；
2. 对他们的假设施加第一性原理推理（Layer 3）；
3. 发现一个清晰的理由，说明常规方法为什么是错的。

"这就是 11/10 分。真正卓越的项目里满是这样的时刻——当别人 zag 时你 zig。当你找到它，给它命名，庆祝它，并在它之上构建。"

反模式：

1. 运行时自带内置功能，却自研一个自定义方案。（Layer 1 失守）
2. 在新颖领域不加批判地接受博客文章。（Layer 2 狂热）
3. 不质疑前提就认为"久经考验"是对的。（Layer 3 盲区）

实现印证：preamble 搜索段落 + eureka.jsonl 日志

该原则在运行时对应 scripts/resolvers/preamble/generate-search-before-building.ts 生成的 ## Search Before Building 段落，注入到每个 preamble-tier >= 3 的技能中（scripts/resolvers/preamble.ts）。它把三层知识压缩成一行式规则——"Layer 1 don't reinvent. Layer 2 scrutinize. Layer 3 prize above all."——并指回 ${skillRoot}/ETHOS.md 获取全文。

更有工程趣味的是 Eureka 时刻的留痕机制：同一段落要求模型在"第一性原理推理与常规智慧冲突"时执行如下命令（见 scripts/resolvers/preamble/generate-search-before-building.ts 生成的 bash 模板）：

jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" \
  --arg branch "$(git branch --show-current 2>/dev/null)" \
  --arg insight "ONE_LINE_SUMMARY" \
  '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' \
  >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true

每一次 Eureka 观察都会以 JSONL 形式追加到本地 ~/.gstack/analytics/eureka.jsonl，带时间戳、技能名和分支名。ARCHITECTURE.md 对此有呼应："When first-principles reasoning reveals conventional wisdom is wrong, the agent names the 'eureka moment' and logs it. See ETHOS.md for the full builder philosophy." 这让哲学里"给它命名、庆祝它"的软性要求变成了可检索的本地审计流。

原则三：User Sovereignty —— AI 推荐，用户决定

这是三条原则中"覆盖其他所有规则"的一条（ETHOS.md）：

AI models recommend. Users decide. This is the one rule that overrides all others.

• 两个 AI 模型就一项变更达成一致是一个强信号，但不是授权（mandate）。 用户永远拥有模型缺失的上下文：领域知识、商业关系、战略时机、个人品味、尚未分享的未来计划。当 Claude 和 Codex 都说"把这两样合并"，而用户说"不，保持分离"——用户是对的。永远如此。哪怕模型能构造出有说服力的论证证明合并更好。
• 文档引用了三个佐证点：Andrej Karpathy 称之为 "Iron Man suit"（钢铁侠战衣）哲学——优秀的 AI 产品增强用户而非取代用户，人始终在中心；Simon Willison 警告 "agents are merchants of complexity"（代理是复杂度的商人）——当人把自己移出环路，他们就不再知道发生了什么；Anthropic 自身的研究显示，经验更丰富的用户打断 Claude 的频率更高而非更低——专业让你更 hands-on 而非更放手。（以上均为 ETHOS.md 原文转述的观点。）
• 正确模式是 generation-verification loop（生成-验证循环）：AI 生成推荐，用户验证并决策。AI 永远不能因为"自信"而跳过验证步骤。
• 规则（The rule）：当你和另一个模型在"改变用户既定方向"的事情上达成一致——陈述推荐、解释为什么你们都认为它更好、说明你可能缺失了什么上下文，然后询问。永远不要直接行动。

反模式：

1. "外部声音是对的，所以我把它采纳了。"（应该：陈述它，然后问。）
2. "两个模型都同意，所以这一定是对的。"（一致是信号，不是证明。）
3. "我先改了，事后告诉你。"（先问。永远。）
4. 在 "My Assessment" 一栏里把你的评估表述为既定事实。（应该：呈现两面，让用户自己填写评估。）

实现印证：User Sovereignty 写进了评审流水线

这条原则的落地最集中的地方是评审类技能的 section 文件。plan-ceo-review、plan-devex-review、plan-eng-review 三个评审技能的 section 中都有同一条硬约束（见 plan-ceo-review/sections/review-sections.md、plan-eng-review/sections/review-sections.md、plan-devex-review/sections/review-sections.md）：

User Sovereignty: Do NOT auto-incorporate outside voice recommendations into the plan.

即：评审过程中引入的"外部声音"（如 /codex 的独立审查意见）禁止被自动并入计划，必须走"陈述 + 询问"路径。这条约束同样由 scripts/resolvers/review.ts 在动态生成评审文本时注入，保证静态 section 与动态生成两条路径口径一致。从 CHANGELOG.md 可确认该原则于 v0.13.2.0（2026-03-28）正式加入 ETHOS.md，并被定义为"第三条核心原则：AI models recommend, users decide. Cross-model agreement is a strong signal, not a mandate."

三原则如何协同 + Build for Yourself

ETHOS.md 用一小节收束三者（ETHOS.md）：

• Boil the Ocean 说：做完整的那件事。
• Search Before Building 说：在决定构建什么之前，先弄清已经存在什么。
• 合起来：先搜索，然后构建正确事物的完整版本。 最坏的结果是把一个已有一行代码就能解决的东西做成了完整版本；最好的结果是把没人想到过的东西做成完整版本——因为你搜索过、理解过整个领域图景、看到了别人都错过的东西。

最后是 "Build for Yourself"（ETHOS.md）：最好的工具解决自己的问题。gstack 的存在是因为它的作者想要它；每个功能都是被需要的才被构建的，而不是被请求的。如果你也在为自己构建某个东西，相信那个直觉——真实问题的具体性，永远胜过假想问题的通用性。

使用与延伸阅读：如何把这套哲学用起来

• 直接阅读：仓库根目录 ETHOS.md 是全文；安装后每个技能实际引用的是安装目录下的同一文件（各 SKILL.md 中指向 ~/.claude/skills/gstack/ETHOS.md）。
• 看它如何生效：任何 preamble-tier: 2 及以上的工作流技能（如 /plan-ceo-review、/review、/qa）运行时的 preamble 中都能读到 ## Completeness Principle — Boil the Ocean 与 ## Search Before Building 两个段落，生成逻辑在 scripts/resolvers/preamble.ts 与各 preamble/generate-*.ts 文件中，可对照源码逐段核验。
• 想理解为什么 gstack 的技能"话多而严谨"：ARCHITECTURE.md 把 "Search Before Building" 列为架构级设计决策之一；README.md 的 Docs 表（第 481 行）是 ETHOS.md 的官方索引入口。
• 注意事项：ETHOS.md 中的压缩比数字是作者的自我测量口径（对应 docs/ON_THE_LOC_CONTROVERSY.md 所述方法论），User Sovereignty 一节引用的 Karpathy/Willison/Anthropic 观点为原文转述；引用时建议保留这一前提。另外，gpt-5.6-sol 模型下的完整性原则是"限定作用域"变体，阅读 model-overlays/gpt-5.6-sol.md 可看到该模型行为画像与 ETHOS 的衔接方式。