superpowers 多 Agent 平台的平台中立行文设计：Phase A「Claude」措辞去中心化方案全解

Superpowers 是一个同时发行到 Claude Code、Codex、Cursor、OpenCode、Copilot CLI、Gemini CLI 等多个 Agent 运行时的技能框架，但其技能文档最初是为 Claude Code 撰写的，正文中到处以第三人称直呼 "Claude"。本文基于仓库内的设计文档 2026-05-05-platform-neutral-prose-design.md，完整拆解 Phase A（平台中立行文）的范围切分、替换风格、术语改名（CSO → SDO）、提交计划与验证方法，并结合实际提交历史与当前源码状态说明方案是如何落地的。读完后你能掌握一套在"多运行时共用的文档仓库"中安全做平台中立化改造的方法论：如何划定 In/Out of scope、如何设计例外保留项（carve-out）、如何用 grep 验证替代后的完整性。

背景与问题定义

Superpowers 的技能内容与支持文档"first for Claude Code"，即先为 Claude Code 写作，因此在任何运行时的 Agent 都可能适用的位置出现了 "Claude" 字样。设计文档指出的直接风险是：OpenAI 的 vendored fork（openai/plugins#217）曾试图整体重写，却在多处改错了——改写了历史归属路径、模型名和平台专属安装说明。Phase A 的目标正是在"保留这些不应改动的内容"的前提下，去除那些真正只是行文习惯（genuinely incidental）的平台中心措辞。

整个去平台中心化工作按"引用类别"切成多个阶段，各阶段有独立的设计文档：

阶段	引用类别	设计文档
Phase A（本文）	通用第三人称 "Claude" 行文 + CSO 术语改名	prose 设计
Phase B	配置文件引用（CLAUDE.md / AGENTS.md / GEMINI.md 优先级表、"项目约定放哪"的提示）	config-refs 设计
Phase C	README 中的营销文案	独立 spec（Out of scope）
Phase D	平台/运行时陈述（"In Claude Code:"、安装说明、工具映射）	独立 spec（Out of scope）
Phase E	工具名引用（Skill、Bash、Read、Task、TodoWrite）	独立 spec

Phase B 的设计文档在开头明确回引了 Phase A 的成果："Phase A replaced generic third-person 'Claude' prose with agent-neutral forms"，并以此为基础处理下一类引用。从源码结构看，这一阶段划分在实际仓库中是真实发生的——后续 commit 历史（如 d238a48 docs: fix dead references to pruned claude-code-tools.md/copilot-tools.md）显示 references 目录下的平台工具文档确实经历了后续的增删统一，与 Phase E 的处理方向一致。

范围界定（In Scope）

Phase A 的改动面被刻意压缩到最小集合，只覆盖以下位置的通用行文（generic prose）中的 "Claude"：

• skills/*/SKILL.md 及各活跃技能目录下的支持性 .md 文件；
• skills/writing-skills/anthropic-best-practices.md——一份外部文档的 vendored 改编版；
• README.md——仅当提及处是通用行文而非平台营销文案时。

外加一处自造术语改名：Claude Search Optimization (CSO) → Skill Discovery Optimization (SDO)，位置在 skills/writing-skills/SKILL.md。

这一改名在当前仓库中已可完整核验：

• skills/writing-skills/SKILL.md#L140：章节标题已改为 ## Skill Discovery Optimization (SDO)；
• skills/writing-skills/SKILL.md#L102：正文交叉引用 "see SDO section for why"；
• skills/writing-skills/SKILL.md#L544：小节 ### Update SDO for Violation Symptoms。

spec 要求"改名标题、缩写以及文件内所有交叉引用"，这三处正好覆盖完整链条。SDO 章节本身讲的就是"未来 Agent 如何发现你的技能"——描述字段只写触发条件、关键词覆盖、描述性命名、token 效率——这个概念本身就是平台中立的（任何运行时的 Agent 都靠 description 检索技能），因此把绑定 "Claude" 的缩写改名为 "Skill Discovery Optimization" 是语义上更准确的选择。

排除清单（Out of Scope）

排除清单是这份 spec 的核心价值所在——它显式声明了哪些"看起来该改"的地方不能改，并逐一指派到后续阶段或说明保留理由：

排除项	理由 / 去向
平台/运行时陈述——"In Claude Code:"、安装说明、工具映射引用	Phase D 候选
配置文件引用——CLAUDE.md、AGENTS.md、GEMINI.md 的优先级表与"项目约定放哪"提示	Phase B（已在 config-refs 设计 中落地，如把 put in CLAUDE.md 改为 put in your instructions file）
工具名引用——Skill、Bash、Read、Task、TodoWrite	技能按 Claude Code 的工具词汇书写，现有的 references/{codex,gemini,...}-tools.md 文件负责映射。spec 写定时的计划是推迟或跳过；但 spec 自身留有更新注记：Phase E 最终处理了它们——把活跃技能中的工具名替换为动作语言，并围绕同一套词汇统一平台工具引用
README 营销文案——"Superpowers for Claude Code"、按平台命名的安装小节	Phase C
历史产物——docs/plans/*.md、docs/superpowers/specs/*.md、CREATION-LOG.md	这些是带日期的时点性文档，重写它们等于"改写历史"。当前 CREATION-LOG.md#L102 中的 "When Claude thinks..." 按此规则原样保留
模型标识符——Claude Haiku / Sonnet / Opus	真实产品名，不可替换。当前 anthropic-best-practices.md#L138-L140 的分层测试清单（Haiku 快而省 / Sonnet 均衡 / Opus 强推理）正是此类保留项
文件名/URL 引用——CLAUDE.md、claude.com、claude-plugin/、~/.claude/ 下的路径	改了就指不到真实文件
anthropic-best-practices.md 文件名本身	文件保留其来源命名，但内部行文按替换规则重写

替换风格（Replacement Style）

spec 给出了明确的文风指令：用自然的英文混用两个人称，按句子语境选择，不为强制一致而牺牲表达自然度，并在自然处用复数（"future agents"、"agents read"）而非永远说 "the agent"。

• 第二人称 "your agent"——面向技能作者谈"他的"运行时：
  • "your agent reads the description"
• 第三人称 "the agent" / "agents" / "an agent"——泛化描述系统行为：
  • "Future agents find your skills"
  • "Use words an agent would search for"
  • "Agents read SKILL.md only when the skill becomes relevant"

这套风格在当前源码中可见落地。例如 anthropic-best-practices.md 中：

Before: At startup, only the metadata ... is pre-loaded. Claude reads SKILL.md
        only when the Skill becomes relevant ...
After:  At startup, only the metadata ... is pre-loaded. Agents read SKILL.md
        only when the Skill becomes relevant ...
Before: Your Skill shares the context window with everything else Claude needs
        to know
After:  Your Skill shares the context window with everything else your agent
        needs to know

同一份文档里第二人称（谈作者的运行时）与第三人称（谈系统行为）并存，正是 spec 所要求的效果。README 的引言同样已换为 "your agent" 措辞（README.md#L3："a complete software development methodology for your coding agents ... make sure your agent uses them"）。

保留为 "Claude" 的例外（Carve-outs）

替换规则有一个硬性白名单，任何命中以下三类的位置一律不改：

1. 模型名：Claude Haiku、Claude Sonnet、Claude Opus；
2. 文件名与 URL：CLAUDE.md、claude.com、~/.claude/；
3. 平台品牌名 "Claude Code"——凡是确实指代该运行时的位置（留给后续阶段处理）。

此外 CLAUDE_MD_TESTING.md#L88 的 "Variant C: Claude.AI Emphatic Style" 标题也保留——它是一个命名特定风格示例的标签，规范化它会毁掉示例本身。

受影响文件清单

spec 基于过滤后的 grep（排除 carve-out 后）给出近似计数：

文件	通用行文提及数
skills/writing-skills/SKILL.md	~12（含 CSO 标题与正文）
skills/writing-skills/anthropic-best-practices.md	~30
skills/writing-skills/examples/CLAUDE_MD_TESTING.md	~1（文件名保留，它是 CLAUDE.md 测试产物；"Variant C: Claude.AI Emphatic Style" 标题保留）
README.md	~1

spec 注明：最终清单在实现期间通过重跑过滤后的 grep 确认。

提交计划与实际落地

spec 原计划 4 个原子提交，顺序固定：

1. CSO → SDO 改名（skills/writing-skills/SKILL.md）——纯机械改动、隔离、易回滚，万一团队对术语改主意可单独撤销；
2. 活跃技能行文——skills/*/SKILL.md 与支持 .md 中的通用 "Claude" → agent 形式，不含 anthropic-best-practices.md；
3. anthropic-best-practices.md 行文——同一替换规则，但单独成 commit，因为它是外部文档的 vendored 改编版，隔离变更便于日后与上游对账；
4. README.md 行文——仅当过滤后仍有通用行文提及时执行，否则跳过。

每个提交信息须标注阶段名（"Phase A"）与切片名（"rename CSO to SDO"、"agent prose in active skills"），使提交序列自文档化。

实际仓库历史呈现了另一种落地形态：git 历史中 Phase A 对应单一 commit f0e5117（"Phase A: agent-neutral prose + CSO → SDO + spec"），一次提交了 README、spec 文档、dispatching-parallel-agents/SKILL.md、writing-skills 的 SKILL.md 与 anthropic-best-practices.md（约 200 行新增 / 102 行删除）。其提交信息明确交代了与 spec 的偏差："Files in this commit also pick up later-phase changes that accumulated on the same files"——即同一批文件上累积的后续阶段改动被并入了这次提交，而 spec 文档随同打包，"records the original scope and the carve-outs"。也就是说：spec 的四段式原子提交是理想计划，实际执行收敛为一次提交 + spec 存档，但 carve-out 纪律（保留 "In Claude Code:" 按平台分发的列表、Variant C 标签、模型名）在 diff 中逐条可核验。

验证方法

spec 为每个提交定义了验证动作：

• 过滤 grep：grep -rn "Claude" <touched-paths>——每个剩余命中必须落入已记录的 carve-out（模型名、文件名、URL、"Claude Code" 平台名、历史产物）；
• 端到端通读改动过的文件——替换不得破坏句子流、代词一致性或列表平行结构；
• 无需运行测试——这是纯行文改动（prose-only）。
• 最终提交后：在真实会话中快速过一遍每个改动的技能，确认没有读起来拗口的地方。

用当前仓库状态执行第一条例子，验证是可通过的。对 skills/ 下全部 .md 文件执行 grep -rn "Claude"，当前仅剩以下命中，逐一可归入 carve-out：

命中位置	归入的 carve-out 类别
anthropic-best-practices.md#L138-L140	模型名（Haiku/Sonnet/Opus）
anthropic-best-practices.md#L1143-L1144	URL/平台品牌名（"Use Skills in Claude Code" 卡片）
writing-skills/SKILL.md#L12	~/.claude/skills/ 路径 + "on Claude Code" 平台名
executing-plans/SKILL.md#L14	按平台列举子代理支持的运行时列表（平台陈述，Phase D 范畴）
brainstorming/visual-companion.md#L62	"Claude Code:" 平台小节标题（Phase D 范畴）
CLAUDE_MD_TESTING.md#L88、L101	示例标签 + 文件名保留（spec 明确保留）
CREATION-LOG.md#L102	历史产物，时点性文档不改写

这正是 spec 验证标准中"every remaining hit must fall into a documented carve-out"的完整闭环。

非目标（Non-Goals）

spec 用三条禁令锁死了改动半径，防止"顺手改进"扩散：

• 不改变行为、结构、标题（CSO→SDO 除外）、示例、代码块或 YAML frontmatter；
• 不引入新章节、callout 或兼容性说明；
• 编辑时不得做超出替换本身的行文"改进"。

后续影响：Phase B 如何承接

Phase A 的直接下游是 Phase B（config-refs 设计）。它的背景一节以一句话概括 Phase A 的成果，然后处理下一个类别：技能中对平台指令文件（CLAUDE.md / AGENTS.md / GEMINI.md）的引用。Phase B 把 writing-skills/SKILL.md#L58 的 "Project-specific conventions (put in CLAUDE.md)" 替换为 "put in your instructions file"，并在每个 references/*-tools.md 中补充各平台偏好的指令文件名，让读者能把 "your instructions file" 解析回真实文件——当前 writing-skills/SKILL.md 中该行的现状（"put in your instructions file"）印证了这一替换已落地。

小结：这份 spec 的方法论价值

从 superpowers 的这份设计文档中可以提炼出一套可复用的多运行时文档治理方法：

1. 按引用类别分阶段，而非一次性大重写——每类引用（通用行文 / 配置文件 / 营销文案 / 平台陈述 / 工具名）有独立的 spec、独立的 commit 序列，单阶段出错可独立回滚；
2. carve-out 白名单先于替换规则——模型名、文件名、URL、平台品牌名、历史产物先被显式列出不许动，替换规则只在白名单之外生效，避免 fork 式重写中"改错历史归属"的事故；
3. 文风规则可执行——第二/第三人称的具体示例句 + "不为一致性牺牲自然度"，使替换结果对人和对 grep 都可验证；
4. 验证靠过滤 grep 闭环——每次提交后重跑同一过滤命令，剩余命中必须能逐条归入 carve-out，形成机械化验收标准；
5. 自造术语与平台解耦（CSO → SDO）——当概念本身（技能发现优化）是平台中立时，术语命名也应脱离任何单一供应商。

这套方法的前提是所有判定都能落到"文档、源码、grep 输出"三类证据上——本文给出的每个结论（SDO 落地位置、剩余 Claude 命中的逐条归类、Phase B 承接关系）均可按文中相对路径在当前仓库中复核。