gstack Sonnet 5 模型覆盖层：用 INHERIT 继承与次级指令驯服 Claude Code 的 Sonnet 5 行为-平芜编程栈

gstack Sonnet 5 模型覆盖层：用 INHERIT 继承与次级指令驯服 Claude Code 的 Sonnet 5 行为

【免费下载链接】gstackUse Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack

在 gstack 仓库中，model-overlays/目录为每个模型家族维护一份"行为补丁"文件，按模型差异向 Claude Code 等宿主注入针对性的提示词微调（nudge）。本文以 model-overlays/sonnet-5.md 为核心，完整解读其中针对 Sonnet 5 的三条行为指令，并结合 scripts/resolvers/model-overlay.ts 与 scripts/models.ts 的源码，说明这份覆盖层如何被解析、继承、注入到每次技能生成的 preamble 中，以及如何被单元测试与 A/B 评测框架验证。读完本文，你可以掌握 gstack 中"模型轴"独立于"宿主轴"的设计，以及如何为一个新模型家族编写、测试自己的行为覆盖层。

一、sonnet-5.md 全文：三条针对 Sonnet 5 的家族级指令

model-overlays/sonnet-5.md 全文仅 17 行，由一条继承指令和三条加粗标题的行为指令构成。原文如下：

{{INHERIT:claude}} **Instructions are read literally.** Sonnet 5 does not silently generalize an instruction from one item to the next, and it does not infer requests you didn't make. When something should apply broadly, say so ("apply this to every section, not just the first"). Re-baseline holdover style directives — they now land at face value. **Scope work to the request.** At lower effort especially, Sonnet 5 scopes to exactly what was asked rather than going above and beyond. If reasoning looks shallow on a genuinely complex task, that is an effort signal: raise effort rather than adding prose guardrails. **Verbosity tracks task complexity.** Responses calibrate length to how complex the task looks — shorter on lookups, longer on open-ended analysis. If you need a specific length or format, state it; a positive example of the target beats a "don't be verbose" instruction.

三条指令各自瞄准 Sonnet 5 在工程实践中暴露的一类偏差，且每条都给出了可直接执行的"纠正姿势"：

1. 指令被逐字执行（Instructions are read literally）

Sonnet 5 不会把一条指令"静默地"从第一个对象泛化到下一个对象，也不会推断你没提过的请求。因此：

当某条要求需要普遍适用时，必须显式声明作用域，例如写成"apply this to every section, not just the first"（应用到每个小节，而不只是第一个）；
需要"重新定基线"（re-baseline）历史遗留的风格指令——因为这类指令在 Sonnet 5 上会按字面意思原样生效（land at face value），不会再被模型"善意地"扩大或缩小解释。

对比同目录的 model-overlays/opus-4-8.md，Opus 4.8 的 "Literal interpretation awareness" 指令是反向的：它提醒模型"fix the tests" 应理解为修复全部失败测试而非只修第一个。而 sonnet-5 的写法是正向的：既然模型本来就会逐字执行，那就把"作用域"写进指令本身。两份覆盖层从相反方向收敛到同一目标——消除指令作用域的歧义。

2. 把工作量限定在请求范围内（Scope work to the request）

在较低 effort 档位上，Sonnet 5 会严格地只做被要求的事，而不是"顺手多做"。gstack 给出的操作建议是：如果某个真正复杂的任务上模型推理看起来偏浅，那本身就是一个 effort 信号——应该调高 effort 档位，而不是往提示词里堆砌更多文字护栏（prose guardrails）。这条指令隐含了 gstack 的一个工程哲学：行为问题优先用"模型能力参数"解决，而不是用"更长的系统提示"解决。

3. 详略跟随任务复杂度（Verbosity tracks task complexity）

Sonnet 5 的回复长度会校准任务看起来的复杂度——查询类（lookup）任务回复更短，开放式分析任务回复更长。如果你需要特定的长度或格式，要显式声明；并且文档明确指出：给一个目标格式的正例（positive example）比"don't be verbose"这类否定式指令更有效。这与第 1 条一脉相承：对逐字执行的模型，正面示范优于抽象禁令。

二、INHERIT 机制：sonnet-5 如何站在 claude 基线之上

文件首行的{{INHERIT:claude}}不是注释，而是覆盖层系统的一级指令。它让 sonnet-5 在自身三条 nudge 之前，先拼上 model-overlays/claude.md 的全部内容——这份 claude 基线包含三条通用指令：Todo-list discipline（多步计划逐条勾销、不批量完成）、Think before heavy actions（重操作前先陈述方案让用户低成本纠偏）、Dedicated tools over Bash（优先 Read/Edit/Write/Glob/Grep 而非 cat/sed/find/grep）。

解析逻辑在 scripts/resolvers/model-overlay.ts 中。关键实现见 readOverlay 函数：

const INHERIT_RE = /^\s*\{\{INHERIT:([a-z0-9-]+(?:\.[0-9]+)*)\}\}\s*\n/; export function readOverlay(model: string, seen: Set<string> = new Set()): string { if (seen.has(model)) return ''; // cycle guard seen.add(model); const filePath = path.join(OVERLAY_DIR, `${model}.md`); if (!fs.existsSync(filePath)) return ''; const raw = fs.readFileSync(filePath, 'utf-8'); const match = raw.match(INHERIT_RE); if (!match) return raw.trim(); const baseModel = match[1]; const base = readOverlay(baseModel, seen); const rest = raw.replace(INHERIT_RE, '').trim(); if (!base) return rest; return `${base}\n\n${rest}`; }

从源码结构看，这个设计有四个明确的边界行为（也写在该文件头部注释里）：

精确匹配优先：ctx.model === 'sonnet-5'就读取model-overlays/sonnet-5.md；
INHERIT 递归展开：只有当文件"第一个非空白行"匹配{{INHERIT:xxx}}时才触发继承，且用seen集合做环保护（cycle guard），避免a.md继承b.md又继承回a.md的死循环；
文件缺失优雅降级：读不到对应文件返回空字符串，不抛错；
未设置模型时返回空串：没有ctx.model时整个覆盖层缺席。

{{INHERIT:xxx}}语法本身由正则[a-z0-9-]+(?:\.[0-9]+)*约束，所以{{INHERIT:claude}}、{{INHERIT:gpt-5.4}}这类家族名都能被识别——这让gpt-5.4.md可以构建在gpt.md之上而不必重复内容，sonnet-5.md同理构建在claude.md之上。

三、次级定位：覆盖层永远"让位于"技能工作流

generateModelOverlay 负责把继承展开后的内容包进一个带明确优先级的区块：

export function generateModelOverlay(ctx: TemplateContext): string { if (!ctx.model) return ''; const content = readOverlay(ctx.model); if (!content) return ''; const precedence = ctx.model === 'gpt-5.6-sol' ? `...` // Sol 模型使用专门的"范围词消歧"定位语 : `The following nudges are tuned for the ${ctx.model} model family. They are **subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode safety, and /ship review gates. If a nudge below conflicts with skill instructions, the skill wins. Treat these as preferences, not rules.`; return `## Model-Specific Behavioral Patch (${ctx.model}) ${precedence} ${content}`; }

对sonnet-5（非 Sol）而言，最终注入的是标题## Model-Specific Behavioral Patch (sonnet-5)+ 一段定位语 + claude 基线 + Sonnet 5 三条 nudge。这段定位语在工程上意义重大：它把模型覆盖层声明为次级（subordinate）于技能工作流、STOP 点、AskUserQuestion 门禁、plan-mode 安全规则和 /ship 评审关卡——"如果下面的 nudge 与技能指令冲突，技能胜出；把它们当作偏好而非规则"。

结合 model-overlays/claude.md 的基线来看，最终落在 Sonnet 5 会话里的行为补丁实际是"1+3"结构：基线负责 todo 纪律、重操作前先思考、专用工具优先；sonnet-5 自身三条负责逐字执行声明、scope 收敛、详略校准。

四、从 CLI 模型名到覆盖层文件：resolveModel 的归一化

覆盖层文件名（如sonnet-5.md）与用户/宿主实际传入的 API 模型 ID（如claude-sonnet-5）之间，由 scripts/models.ts 的resolveModel完成归一化。该模块头部注释强调了 gstack 的一个核心不变量：host ≠ model（宿主 ≠ 模型）——Claude Code 可以运行任何 Claude 模型，Codex CLI 跑 GPT/o 系，Cursor 与 OpenCode 可前置多家 provider；生成器不会从宿主自动探测模型，用户可显式传--model，否则各宿主提供自己的生成默认值（唯一例外是./setup会从${CODEX_HOME:-~/.codex}/config.toml探测 Codex 模型）。

sonnet-5的选取路径有两条（见 ALL_MODEL_NAMES 与 resolveModel）：

export const ALL_MODEL_NAMES = [ 'claude', 'opus-4-7', 'fable-5', 'opus-4-8', 'sonnet-5', 'gpt', 'gpt-5.4', 'gpt-5.6-sol', 'gemini', 'o-series', ] as const; // 归一化规则（节选）： if (/^claude-sonnet-5(-|$)/.test(s)) return 'sonnet-5'; // L71：API 模型 ID → 家族 if (/^claude(-|$)/.test(s)) return 'claude'; // 其余 claude-* 落回基线

精确匹配：输入本身就是sonnet-5（ALL_MODEL_NAMES成员），直接命中；
家族启发式：claude-sonnet-5或claude-sonnet-5-*开头的 API 模型 ID 经正则/^claude-sonnet-5(-|$)/归一化为sonnet-5。

值得注意的匹配顺序细节：claude-opus-4-8、claude-fable-5、claude-opus-4-7、claude-sonnet-5等特化家族的正则都排在兜底规则/^claude(-|$)/ → 'claude'之前。也就是说，任何未列入特化家族的 Claude 模型 ID（例如未来的claude-haiku-*）都会落回通用claude基线覆盖层，而不会误挂到 sonnet-5 的特化 nudge 上——这与gpt-5.6-sol"精确匹配专属、后缀变体一律落回gpt" 的设计哲学一致。

五、注入点：preamble 组装链中的一环

覆盖层并非独立文件分发，而是在每个技能的 SKILL.md 渲染管线中生效。scripts/resolvers/preamble.ts 导入了generateModelOverlay（第 20 行），并在 preamble 组装数组中调用它（第 114 行附近）——即每次为某个宿主、某个模型生成技能前置文案时，模型行为补丁都会被合成进 preamble。这也解释了为什么 test/model-overlay-sonnet-5.test.ts 断言的是"解析后的产物"而非裸文件：

test('resolved overlay inherits from claude base (INHERIT:claude)', () => { const out = generateModelOverlay(makeCtx('sonnet-5')); expect(out).toContain('Todo-list discipline'); // 来自 claude.md 基线 expect(out).toContain('subordinate'); // 次级定位语 }); test('resolved overlay has no unresolved INHERIT directive', () => { const out = generateModelOverlay(makeCtx('sonnet-5')); expect(out).not.toContain('{{INHERIT:'); // 继承必须完全展开 });

该测试文件（test/model-overlay-sonnet-5.test.ts）共 5 个断言，形成对 sonnet-5 覆盖层的完整门禁：

断言	验证目标
裸文件含 "Instructions are read literally"	第一条家族 nudge 未被意外删除
解析产物含 "Todo-list discipline"	`{{INHERIT:claude}}`展开正确
解析产物含 "subordinate"	次级定位语随每次注入出现
解析产物含 "Scope work to the request"	第二条家族 nudge 在场
解析产物不含`{{INHERIT:`	继承指令全部展开、无残留
`claude`基线不含 sonnet 的 nudge	家族 nudge 不会泄漏到基线

六、评测纵深：overlay-nudges A/B 框架

gstack 对"nudge 是否真的改变了模型行为"有一套可复现的 A/B 评测设施，而非仅靠文本断言。test/fixtures/overlay-nudges.ts 定义了一个 fixture 注册表：每条 fixture 绑定一个覆盖层文件、一个 API 模型 ID、若干组带/不带覆盖层的试验（trials 不少于 3），并用量化指标裁决——例如bashToolCallCount（Bash 调用数，验证 claude 基线的 "Dedicated tools over Bash"）、turnsToCompletion（完成轮数，验证 "effort-match"）、uniqueFilesEdited（编辑过的文件数，验证逐字解读作用域）、firstTurnParallelism（首回合并行度，验证 fanout nudge）。test/skill-e2e-overlay-harness.test.ts 负责遍历注册表执行双臂对照，并处理并发、限流重试与产物落盘。

从当前注册表内容看（overlay-nudges.ts 第 197 行起的 OVERLAY_FIXTURES），A/B fixture 覆盖的是opus-4-7.md、claude.md在claude-opus-4-7与claude-sonnet-4-6上的表现；sonnet-5.md目前由 test/model-overlay-sonnet-5.test.ts 的单元级门禁守护。这符合该文件的注释定位："Adding a new overlay eval = one entry in this list"——为 sonnet-5 增加行为 A/B 评测只需向注册表追加一条 fixture，harness 自动接管。这也展示了覆盖层系统的扩展范式：文本改动 + 解析器单测 + （可选）行为 A/B fixture三层验证。

七、小结：如何把这套机制用到自己的模型上

以 model-overlays/sonnet-5.md 为样本，gstack 给出的"模型行为调优"完整配方可以概括为四步：

写行为补丁：用加粗标题 + 短段落描述模型的已知偏差与纠正姿势，每条 nudge 尽量给出可照抄的正面示例（如 "apply this to every section, not just the first"），避免否定式空指令；
声明继承：首行{{INHERIT:基线}}复用家族基线（sonnet-5 → claude），避免跨文件重复维护；
接受次级定位：由 scripts/resolvers/model-overlay.ts 统一包裹的 "subordinate" 定位语保证 nudge 永远不与技能工作流、STOP 点、安全门禁抢权；
加门禁：在test/下仿照 model-overlay-sonnet-5.test.ts 写"裸文件断言 + 解析产物断言"，必要时向 overlay-nudges.ts 注册表追加行为 A/B fixture。

模型轴与宿主轴解耦、INHERIT 递归展开带环保护、缺失文件优雅降级、次级优先级写死在包装头里——这些设计让"换模型不改技能、改 nudge 不动技能"成为 gstack 中一条稳定的扩展边界。

参考文件

覆盖层本体：model-overlays/sonnet-5.md、model-overlays/claude.md、model-overlays/opus-4-8.md
解析与注入：scripts/resolvers/model-overlay.ts、scripts/models.ts、scripts/resolvers/preamble.ts
测试与评测：test/model-overlay-sonnet-5.test.ts、test/fixtures/overlay-nudges.ts、test/skill-e2e-overlay-harness.test.ts

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考