用 ce-explain 在改动前理解某子系统的实现方式与设计原因

用 ce-explain 在改动前理解某子系统的实现方式与设计原因

【免费下载链接】compound-engineering-pluginOfficial Compound Engineering plugin for Claude Code, Codex, Cursor, and more项目地址: https://gitcode.com/GitHub_Trending/ev/compound-engineering-plugin

准备修改一个自己没写过的子系统时，最大的风险不是改动本身，而是不知道它现在的行为边界和当时的设计原因。Compound Engineering 插件里的ce-explain技能就是为这个场景准备的：它围绕一个范围明确的问题，沿着源码和测试追行为（how），沿着决策记录、注释、git 历史和 PR 追设计原因（why），并把「有证据支撑的事实」「合理推断」「未知」区分开再交付给你。它的定位是解释，不做判断——ce-pov负责判断该怎么做，ce-debug负责诊断故障，见 ce-explain 指南。

适用前提：你已经在某个 agent 宿主（Claude Code、Cursor、Codex 等插件支持的宿主）中安装了 Compound Engineering 插件，并且要在一个 git 仓库里工作。ce-explain对仓库内子系统做 grounding 时依赖真实源码；只存在于模型知识里的外部概念不走仓库取证路径。

准备：安装并确认 ce-explain 可用

以 Claude Code 为例，安装命令如下（README 的 Install 一节）：

/plugin marketplace add EveryInc/compound-engineering-plugin /plugin install compound-engineering

其他宿主的安装方式见 README 的「More Install Options」，例如 Codex CLI：

codex plugin marketplace add EveryInc/compound-engineering-plugin codex plugin add compound-engineering@compound-engineering-plugin

安装完成后确认技能已加载：不同宿主的调用语法不同——slash 类宿主（Claude Code、Copilot 等）用/ce-explain，Codex 里用$ce-explain，oh-my-pi（omp）用确定性的/skill:ce-explain。这个差别在 README 的 Philosophy 一节有明确说明。

发起解释：把「要改什么」写成一个问题

ce-explain的普通路径是自然语言，直接说明对象和意图即可。argument-hint定义为[question, concept, change, or work window] [intended use or reader]（见 skills/ce-explain/SKILL.md），即前半句定位解释对象，后半句说明这份解释给谁用。改动前理解子系统属于 concept 形态（一个主题、模式或子系统），典型调用形态如下，均为 指南 给出的示例：

/ce-explain how does cancellation propagate, and why do we retain polling? This informs the readiness plan. /ce-explain the parser split output:md audience:team

第二个示例同时演示了两个可用的 flag token：output:md请求 markdown 产物，audience:team指定读者。四个 token 及含义来自 references/intake.md：

Token	示例	作用
diff:<ref-or-range>	diff:main..HEAD、diff:PR#42	强制进入 diff 模式，解释那次改动
since:<window-or-ref>	since:monday、since:7d	强制进入 recap 模式，覆盖该时间窗
output:<md\|html>	output:md	覆盖产物格式（默认html）
audience:<who>	audience:team	为指定读者调整深度和措辞

token 只在该word:value对读起来像一个 flag 时才生效（位于请求开头或独立出现，冒号后无空格，且去掉它句子仍通顺）。普通行文里的冒号不会被当成 flag，例如 "walk me through the diff: why did we split the parser" 是 prose，按 diff 概念请求处理。如果你要解释的子系统恰好是刚合入的改动（一个可解析的 sha、分支或 PR），请求会按 tiebreak 规则归入 diff 模式，concept 作为背景框架——这是文档明确给出的判定，不需要你额外标注。

它会如何取证：how 与 why 两条线

理解「实现方式」和「设计原因」时，ce-explain走的是两条不同的证据路径（见 references/orchestration.md）：

• how：从相关触发点出发，追踪状态变化、所有权边界和效果，检查实际源码和测试；文件名或对话里的说法不足以确立行为。
• why：寻找决策记录——动机文档、注释、git 历史、PR 讨论、关联 issue，在请求允许的源范围内追到可用证据为止。

几条值得提前知道的边界：代码只证明行为，不必然证明作者动机，缺失的历史原因会保持 unknown；历史约束在被当作现行要求呈现前会被重新核对；当解释要服务于一次改动时，它会给出相关约束和风险，但不替下一步选实现方案——那属于ce-plan的职责。

验证结果：看证据分层，不只看结论

ce-explain的完成标准写在 SKILL.md 的 Done 一节：交付「带支撑证据的解释 + 重要的未解答问题」，或返回具体的阻塞项。据此核对交付物：

1. 事实有出处。每条行为断言应能对应到它引用的源；交付前的自检要求把每个事实性声称与其来源逐一比对，函数调用不会为它没检查过的实现建立保证。
2. 推断和未知被单独标出。文档化的设计原因与「有证据支持的推断」分开引用，矛盾点和查不到记录的原因直接报告，而不是被抹平。
3. 范围如实披露。当证据超出请求的范围或深度时，它会说明选了哪些线索、留下了什么，而不是把部分叙述静默呈现为完整。

请求独立教学产物时，默认产出自包含的 HTML 文件（output:md时是 markdown），文件头部带可见元数据Date、Input shape（concept/diff/idea/recap之一）、Subject，页脚标注Composed <日期> by ce-explain（见 references/explainer-html.md）。HTML 产物是单文件、无外部请求的，可以在离线或 CSP 受限的查看器里打开——这本身就是一个可执行的验证动作：打开文件，确认它不发起任何外部请求且元数据齐全。产物里的Check yourself练习区是静态内容（先问题后答案），用于记忆而非测验，不会阻塞运行，规则见 references/check-in.md。

产物默认只落在运行目录；只有归档进仓库时才写入<root>/explainers/，其中<root>由.compound-engineering/config.yaml的docs_root决定，未设置时就是docs（见 configuration 文档）。所以「解释已交付」和「文件已发布/归档」是两件事，不要因前者没出现而怀疑解释没完成。

边界与限制

• 需要判断某个方案该不该采用、要不要改，用ce-pov；解释一个历史选择不等于背书它。
• 要诊断或修复一个已发生的故障属于ce-debug；对当前机制做事实性解释仍由ce-explain负责。
• 给想法定范围、生成备选方案属于ce-ideate、ce-brainstorm、ce-plan，ce-explain只解释你给出的想法本身。
• 裸调用（没有可恢复的解释对象）时，skill 会按交互规则澄清，而不是发明一个主题或默认产物；diff:和since:同时出现会冲突，按交互规则消解。
• 交互不可用时，它会返回未解析的问题及其后果，而不是等待或编造答案。

拿到带证据和约束的解释后，下一步自然就是把这份约束交给ce-plan或ce-brainstorm（指南 的 In a workflow 一节说明这两个技能会在未解决的行为或设计原因问题实质影响其工作时复用ce-explain），或直接开始你的改动——解释已经标出了哪些是确认的约束、哪些还是未知。

【免费下载链接】compound-engineering-pluginOfficial Compound Engineering plugin for Claude Code, Codex, Cursor, and more项目地址: https://gitcode.com/GitHub_Trending/ev/compound-engineering-plugin