Explanatory Output Style 教育输出风格插件

Explanatory Output Style 插件在每次会话开始时注入教育性输出指令，让 Claude 在完成任务的同时提供关于实现选择和代码库模式的教育性见解。

概述

Explanatory Output Style 插件重新实现了已废弃的 "Explanatory" 输出风格。通过 SessionStart 钩子，它在每次会话开始时自动注入指令，让 Claude 在编码过程中提供教育性解释。

核心特性

特性	说明
自动激活	安装后无需配置，自动生效
教育性见解	在代码前后提供关于实现选择的解释
特定格式	使用统一的 "★ Insight" 格式呈现见解
平衡输出	在任务完成和学习机会之间保持平衡

输出效果示例

安装插件后，Claude 的输出会包含这样的教育性见解：

★ Insight ─────────────────────────────────────
1. 这里使用 useCallback 是因为该函数作为依赖传递给子组件
2. React.memo 与 useCallback 配合可以防止不必要的重渲染
─────────────────────────────────────────────────

const handleSubmit = useCallback(() => {
  // 实现代码...
}, [dependencies]);

---

安装与配置

插件安装

# 安装 explanatory-output-style 插件
/plugin install explanatory-output-style@claude-plugins-official

目录结构

plugins/explanatory-output-style/
├── .claude-plugin/
│   └── plugin.json
├── README.md
├── hooks/
│   └── hooks.json              # 钩子配置
└── hooks-handlers/
    └── session-start.sh        # 会话启动脚本

配置文件 (plugin.json)

{
  "name": "explanatory-output-style",
  "version": "1.0.0",
  "description": "Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)",
  "author": {
    "name": "Dickson Tsai",
    "email": "dickson@anthropic.com"
  }
}

钩子配置 (hooks.json)

{
  "description": "Explanatory mode hook that adds educational insights instructions",
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/session-start.sh"
          }
        ]
      }
    ]
  }
}

---

工作原理

技术实现

graph LR
    A[会话开始] --> B[SessionStart 钩子触发]
    B --> C[执行 session-start.sh]
    C --> D[注入指令到 Claude 上下文]
    D --> E[Claude 开始带见解的输出]

    style A fill:#e3f2fd
    style D fill:#fff3e0
    style E fill:#c8e6c9

session-start.sh 脚本

该脚本在每次会话开始时执行，输出以下指令给 Claude：

#!/bin/bash
cat << 'EOF'
You are now in "explanatory" output style mode.

Before and after writing code, provide brief educational explanations about
implementation choices using this format:

★ Insight ─────────────────────────────────────
[2-3 key educational points]
─────────────────────────────────────────────────

These insights should:
- Focus on the "why" behind implementation choices
- Explain patterns and best practices being used
- Highlight important tradeoffs or considerations
- Be specific to the codebase and code being written

Balance educational content with task completion. When providing insights,
you may exceed typical length constraints, but remain focused and relevant.
EOF

见解格式

每个见解使用统一的格式：

★ Insight ─────────────────────────────────────
[2-3 个关键教育点]
─────────────────────────────────────────────────

格式特点：

• 视觉分隔：使用星号和横线清晰分隔
• 简洁明了：2-3 个关键点
• 位置灵活：可以在代码前或代码后

---

输出示例

示例 1：React 组件优化

用户请求：帮我优化这个 React 组件的性能

Claude 输出：

★ Insight ─────────────────────────────────────
1. useMemo 用于缓存计算结果，避免每次渲染都重新计算
2. 依赖数组 [items] 意味着只有 items 变化时才会重新计算
3. 对于大型列表，这可以显著减少渲染时间
─────────────────────────────────────────────────

const sortedItems = useMemo(() => {
  return [...items].sort((a, b) => a.name.localeCompare(b.name));
}, [items]);

★ Insight ─────────────────────────────────────
1. React.memo 包装组件可以防止父组件更新时的不必要重渲染
2. 配合 useCallback 使用效果更佳
─────────────────────────────────────────────────

示例 2：API 错误处理

用户请求：添加 API 错误处理

Claude 输出：

★ Insight ─────────────────────────────────────
1. 使用 try-catch 包装 async 操作是处理异步错误的标准模式
2. 区分网络错误和 API 错误可以提供更好的用户体验
3. 保留原始错误信息便于调试，同时向用户展示友好消息
─────────────────────────────────────────────────

async function fetchData() {
  try {
    const response = await api.get('/users');
    return response.data;
  } catch (error) {
    if (error.response) {
      // API 返回的错误
      throw new ApiError(error.response.data.message);
    } else {
      // 网络错误
      throw new NetworkError('无法连接到服务器');
    }
  }
}

示例 3：数据库查询

用户请求：优化数据库查询

Claude 输出：

★ Insight ─────────────────────────────────────
1. 使用参数化查询防止 SQL 注入攻击
2. SELECT 指定字段比 SELECT * 更高效，减少数据传输
3. 添加索引可以显著提升 WHERE 子句的查询速度
─────────────────────────────────────────────────

const query = `
  SELECT id, name, email
  FROM users
  WHERE status = $1
  AND created_at > $2
`;

// 确保 status 和 created_at 字段有索引
const result = await db.query(query, ['active', lastWeek]);

---

使用场景

适合场景

场景	说明
学习新代码库	理解现有代码的设计决策
技术培训	在完成任务的同时学习最佳实践
代码审查	理解代码变更背后的原因
新手开发者	在实践中学习编程概念

不适合场景

场景	原因
紧急修复	需要快速完成，不需要解释
重复任务	已经熟悉的操作不需要解释
令牌敏感	额外的解释会增加令牌消耗

---

与已废弃配置的对比

迁移路径

这个插件是 Claude Code 设置中 "outputStyle": "Explanatory" 配置的替代品。

旧方式（已废弃）：

// settings.json
{
  "outputStyle": "Explanatory"
}

新方式（使用插件）：

/plugin install explanatory-output-style@claude-plugins-official

功能对比

方面	旧配置	插件实现
配置方式	settings.json	插件安装
灵活性	固定	可自定义脚本
可移植性	本地配置	可共享插件
状态	已废弃	推荐使用

---

成本考虑

⚠️ 注意：此插件会增加令牌消耗

令牌影响

类型	额外消耗
输入令牌	会话启动指令 ~200 令牌
输出令牌	每个见解 ~50-100 令牌

使用建议

1. 评估需求：确认是否真的需要教育性见解
2. 临时使用：可以在需要时安装，不需要时禁用
3. 监控成本：关注令牌使用量的变化

控制方式

# 禁用插件（保留代码）
/plugin disable explanatory-output-style

# 重新启用
/plugin enable explanatory-output-style

# 完全卸载
/plugin uninstall explanatory-output-style

---

自定义修改

创建本地副本

如果你想修改输出格式或行为：

1. 复制插件到本地：

cp -r ~/.claude/plugins/explanatory-output-style ~/.claude/plugins/my-explanatory-style

2. 修改 hooks-handlers/session-start.sh：

#!/bin/bash
cat << 'EOF'
# 你的自定义指令
# 可以修改格式、添加或删除要求
EOF

3. 更新 plugin.json 中的名称：

{
  "name": "my-explanatory-style",
  ...
}

自定义示例

简化版：只在复杂代码后提供见解

#!/bin/bash
cat << 'EOF'
Only provide educational insights after writing complex code (>10 lines).
Use this format:
💡 [Brief explanation of the key implementation choice]
EOF

详细版：提供更多上下文

#!/bin/bash
cat << 'EOF'
Provide comprehensive educational insights including:
- Pattern name and origin
- Alternative approaches considered
- Performance implications
- When to use/not use this pattern
EOF

---

常见问题

Q: 插件安装后没有效果？

A: 检查以下几点：

1. 确认插件已启用：/plugins list
2. 开始新会话以触发 SessionStart 钩子
3. 检查钩子脚本是否有执行权限

Q: 如何暂时关闭见解输出？

A: 两种方式：

1. 禁用插件：/plugin disable explanatory-output-style
2. 在提示词中说明：「请直接给出代码，不需要解释」

Q: 可以只在特定文件类型时启用吗？

A: 需要自定义脚本，在 session-start.sh 中添加条件逻辑。

---

总结

Explanatory Output Style 插件通过 SessionStart 钩子实现了教育性输出：

1. 自动激活 - 安装即用，无需配置
2. 统一格式 - 使用 "★ Insight" 格式呈现
3. 平衡输出 - 任务完成与学习机会并重
4. 灵活控制 - 可以禁用或自定义

适合希望在使用 Claude Code 时学习编程最佳实践的开发者。

---

参考资源

• GitHub 源码 - 官方插件仓库
• Claude Code Hooks 文档 - 钩子系统文档

---

本文档基于 explanatory-output-style 插件 v1.0.0 编写