claude-howto 实战：用 Claude Code 编写 Incident Commander 子代理，把生产事故响应交给 AI 指挥官

导读

本指南以 claude-howto 仓库中的 incident-commander.md 为骨架，讲解如何在 Claude Code 的 devops-automation 插件内，用一个 Markdown 文件定义负责生产事故协调的 Incident Commander 子代理。读完你将掌握：子代理定义文件（frontmatter + 职责清单）的编写规范、Incident Commander 的五大职责与其在 /incident 七步流程中的落地方式、它与告警分析器、部署专家、Kubernetes MCP 的协同调用关系，以及如何将其嵌入一条"发现告警 → 研判 → 处置 → 复盘"的完整事故响应链路。

---

一、Incident Commander 在插件架构中的定位

在 claude-howto 仓库的插件示例中，devops-automation 是一个把部署、监控与事故响应打包成一体的完整 DevOps 自动化插件，安装命令只有一条：

/plugin install devops-automation

安装后，插件内共提供三类可被 Claude 调度的能力（见 07-plugins/devops-automation 目录结构）：

类型	成员	职责
斜杠命令（Slash Commands）	/deploy、/rollback、/status、/incident	面向用户的结构化任务入口
子代理（Subagents）	deployment-specialist、incident-commander、alert-analyzer	被主线程委托的领域专家
MCP 服务器	kubernetes-config.json	提供 kubectl 能力的实时集群访问
脚本与钩子	deploy.sh、rollback.sh、health-check.sh、pre-deploy.js、post-deploy.js	可执行的底层运维工具

Incident Commander 是其中面向"事故"的核心专家：它不与用户直接交互，而是当事故（如生产故障告警、服务不可用）发生时，由主线程 Claude 依据 /incident 命令的流程逻辑，把协调工作委托给它执行。

关于子代理在整个扩展体系中的层级，仓库在 07-plugins/README.md 中有一张清晰的对比表：子代理与斜杠命令、Skill、Plugin 相比，定位是"单领域专家"，靠人工拷贝文件或 settings.json 指定 agent 键来接入；而插件则是把这些专家与命令、MCP、钩子一次性打包分发的最高级扩展机制。这正是 incident-commander 以插件子代理（而非独立配置）形式存在的原因——它必须和部署、告警、健康检查等能力天然同生。

---

二、逐行拆解 incident-commander.md 子代理定义

Incident Commander 的全部定义只有一份 Markdown 文件：incident-commander.md。它的结构由 YAML frontmatter + 正文职责清单两部分组成。

2.1 frontmatter：声明身份与工具边界

---
name: incident-commander
description: Coordinates incident response
tools: Read, Write, Bash, Grep
---

字段	取值	含义与影响
name	incident-commander	子代理唯一标识，主线程 Claude 用它发起委托（如 "delegate to incident-commander"）
description	Coordinates incident response	一段面向主线程的"自荐语"，决定 Claude 在何种场景下选择唤醒该代理
tools	Read, Write, Bash, Grep	允许该代理使用的工具白名单，即它的"权限边界"

值得特别说明的是 tools 字段——这是从仓库源码可直接观察到的安全设计约束。在 07-plugins/README.md 的 "Plugin Security" 一节明确写到：插件子代理运行在受限沙箱中，其定义中不允许声明 hooks、mcpServers、permissionMode 三个键，即子代理不能注册事件钩子、不能自行配置 MCP 服务器、也不能覆盖权限模型。因此 Incident Commander 要读日志、写事故记录、跑诊断命令，只能依靠 Read / Write / Bash / Grep 这四个工具完成——这从设计上保证了它"只能处置、无法越权"。事故处置期间真正需要的高权限集群访问，是经由插件级 MCP 服务器（见第五节）以主线程为中介间接获取的。

2.2 正文：五大职责即它的"指挥手册"

正文部分以清单形式定义了该代理的全部专业职责：

• Severity assessment（严重度评估）
• Team coordination（团队协调）
• Status updates（状态更新）
• Resolution tracking（解决跟踪）
• Post-mortem facilitation（复盘推进）

这五条既是写入文件的"人物设定"，也是它在被委托后应当主动执行的任务清单。从命令文件 incident.md 的七步工作流可以反推出它们在实战中的先后次序，详见第三节。

2.3 版本与兼容性元信息

文件尾部标注了来源与运行环境约束，是评估"这个子代理能否在我的 Claude Code 环境中跑起来"的直接依据：

• Last Updated: August 4, 2026
• Claude Code Version: 2.1.220
• Compatible Models: Claude Fable 5、Claude Opus 5、Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.8、Claude Haiku 4.5

即：该定义按 Claude Code 2.1.220 的插件/子代理规范编写，兼容的模型是 Claude 5 / 4.8 / 4.6 / 4.5 系列（Fable、Opus、Sonnet、Haiku 各档位）。如果你的 Claude Code 或模型版本远低于此范围，子代理的加载与工具白名单行为可能不一致，建议先核对版本。

---

三、把五大职责落进 /incident 七步事故流程

文档本身是"静态定义"，而真正让 Incident Commander 动起来的是配套斜杠命令 incident.md。该命令描述了一套结构化事故响应工作流，共七步：

1. Create incident record（创建事故记录）
2. Assess severity and impact（评估严重度与影响面）
3. Notify on-call team（通知值班团队）
4. Gather diagnostic information（收集诊断信息）
5. Coordinate response efforts（协调处置力量）
6. Document resolution（记录解决过程）
7. Schedule post-mortem（安排事后复盘）

下面把 Incident Commander 的五项职责与这七步逐一对应，形成完整的"被委托后的行动序列"：

流程步骤	Incident Commander 的动作	对应职责
1. 创建事故记录	用 Write 工具落盘事故单：时间、影响服务、当前状态	Resolution tracking
2. 评估严重度与影响	结合告警文本、日志证据做 Severity 分级（P0/P1/P2…）	Severity assessment
3. 通知值班团队	通过 Bash 调用通知渠道（如 Webhook、IM），说明分级结论	Team coordination
4. 收集诊断信息	用 Read/Grep 检索日志，用 Bash 跑诊断命令，必要时向主线程请求 Kubernetes MCP 查询	Team coordination（信息汇聚）
5. 协调处置	识别需要谁出手，如把修复委托给 deployment-specialist，或驱动 /rollback	Team coordination
6. 记录解决过程	更新事故记录，写明根因、处置动作与时间线	Resolution tracking
7. 安排复盘	产出复盘议程、召集相关方、输出待办	Post-mortem facilitation

从这里可以看出该设计的精妙之处：Incident Commander 不做"单点英雄式"修复，而是做全流程的指挥与记录——评估、调度、跟踪、复盘由它负责，而具体的 kubectl 操作、部署/回滚执行则交给专门的能力（部署专家 + Kubernetes MCP + 运维脚本）。这与真实 SRE 团队中 Incident Commander（IC）角色的分工模型一致：IC 的职责是指挥而不是亲自修服务器。

从 07-plugins/devops-automation 目录结构还可以观察到，alert-analyzer.md（告警关联、趋势分析、根因定位）与 deployment-specialist.md（蓝绿发布、金丝雀、回滚、健康检查、数据库迁移）正是它在步骤 4 与步骤 5 可调度的"专家同事"。

---

四、实战演练：一次完整的 AI 事故响应会话

将以上机制拼装起来，一次真实的生产事故处理可以这样发生（入口与仓库中描述的命令一致）：

用户：/incident
      「生产环境 API 错误率飙升到 35%，PagerDuty 已触发告警，
       请按流程处置。」

Claude 主线程：
 1. 解析 incident 命令，加载七步流程上下文
 2. 委托 incident-commander 子代理 → 创建事故记录（Write）
 3. incident-commander 评估严重度：判定为 P1（严重度评估）
 4. 通知值班团队（Team coordination）
 5. 收集诊断：让 alert-analyzer 分析告警关联与时间线，
    同时用 Grep/Bash 查看应用日志（收集诊断信息）
 6. 若怀疑与上次发布相关 → 协调 deployment-specialist
    评估是否需要回滚，或驱动 /rollback production
 7. 更新事故单，记录根因与处置时间线（Resolution tracking）
 8. 调度 post-mortem：输出复盘议程与改进待办（Post-mortem facilitation）

返回给用户的处置小结：
 ✅ 事故记录已创建（INC-2026-0814-01）
 🚨 Severity: P1 → P2（恢复后降级）
 🛠 处置动作：rollback 至 revision 12，Pods 3/3 ready
 📋 复盘安排：明日 10:00，参与人 SRE / DBA / 后端

这个演练不是仓库代码，而是对文档职责与命令流程的合理编排演示；真正落到代码层面的支撑在第五节。

---

五、Incident Commander 背后的"武器库"：仓库源码级支撑

Incident Commander 的定义文件本身不含可执行逻辑，它的"执行力"来自插件内其他组件。理解这些源码文件，才能理解它能协调什么、如何协调。

5.1 Kubernetes MCP：事故现场的"眼睛和手"

事故诊断与处置离不开集群实时状态。插件通过 kubernetes-config.json 注入 kube 能力：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-kubernetes"],
      "env": {
        "KUBECONFIG": "${KUBECONFIG}"
      }
    }
  }
}

关键点：env.KUBECONFIG 复用宿主环境变量，KUBECONFIG 指向你的 kubeconfig 文件（默认 ~/.kube/config）。这意味着事故发生时，Incident Commander 可以让 Claude 通过该 MCP 查询 Pod 状态、事件与负载——但如前所述，MCP 的配置权在插件层而非子代理层，Incident Commander 只能"借用"，不能"自建"，这正是插件安全模型的体现。

5.2 健康检查脚本：事故定级前先量化"不健康程度"

health-check.sh 是 Incident Commander 做 Severity assessment 与根因收敛时可直接调用的量化工具：

#!/bin/bash
ENV=${1:-production}

# 检查 API
echo -n "API: "
if curl -sf http://api.$ENV.example.com/health > /dev/null; then
  echo "✅ Healthy"
else
  echo "❌ Unhealthy"
fi

# 检查数据库
echo -n "Database: "
if pg_isready -h db.$ENV.example.com > /dev/null 2>&1; then
  echo "✅ Healthy"
else
  echo "❌ Unhealthy"
fi

# 检查 Pods
PODS_READY=$(kubectl get pods -n $ENV --no-headers | grep "Running" | wc -l)
PODS_TOTAL=$(kubectl get pods -n $ENV --no-headers | wc -l)
echo "$PODS_READY/$PODS_TOTAL ready"

它一次性覆盖三层探活——HTTP 健康端点、数据库连通性（pg_isready）、K8s Pod 就绪率——且默认环境为 production，也接受 staging 等参数。该脚本可作为 Incident Commander 判断"影响面多大、是否需要升级或回滚"的第一手数据来源。

5.3 回滚脚本：P1 事故的"止血按钮"

当事故被判定为与最新发布强相关、需要立即止血时，Incident Commander 协调的执行单元是 rollback.sh 与 deploy.sh。回滚脚本的关键链路为：

set -e
ENV=${1:-staging}

# 从 rollout 历史中取上一次稳定版本
PREVIOUS=$(kubectl rollout history deployment/app -n $ENV | tail -2 | head -1 | awk '{print $1}')
echo "🔄 Rolling back to revision: $PREVIOUS"

kubectl rollout undo deployment/app -n $ENV     # 执行回滚
kubectl rollout status deployment/app -n $ENV   # 等待回滚完成
sleep 5
curl -f http://api.$ENV.example.com/health      # 回滚后健康检查

set -e 保证任一步失败立即中断并以非零码退出；回滚后强制做健康检查，避免"回滚到另一个坏版本"。这套语义使得 Incident Commander 调用它时能获得确定性成功/失败信号，从而准确更新事故单状态。

5.4 前后置钩子：错误处置本身也受流程约束

事故若发生在部署窗口，pre-deploy.js 与 post-deploy.js 构成了旁路的防御线：前者校验 kubectl 是否安装、能否连通集群（不可用直接 process.exit(1) 拒绝部署）；后者等待 Pod 就绪并预留 smoke test 插槽。也就是说，插件在"事故响应"之外还有一层预防性把关，Incident Commander 复盘时也应把这类钩子的命中记录纳入根因分析。

5.5 完整的组件调用链

综合 devops-automation 目录内全部源码文件，可绘制出事故响应时子代理的实际协作拓扑：

/incident（命令入口）
   └─→ incident-commander（事故指挥官：评估 / 协调 / 跟踪 / 复盘）
          ├─→ alert-analyzer（告警关联与根因分析：Read/Grep/Bash）
          ├─→ deployment-specialist（需发布/回滚处置时：蓝绿、金丝雀…）
          ├─→ Kubernetes MCP（kubectl 实时状态：查询 Pods、events）
          ├─→ health-check.sh（三层健康量化：API/DB/Pods）
          ├─→ rollback.sh / deploy.sh（止血与恢复的执行脚本）
          └─→ pre-deploy.js / post-deploy.js（预防性流程把关）

需要说明的是，这一拓扑中"谁调用谁"的先后决策并非硬编码在某个文件里，而是由主线程 Claude 依据各子代理的 description 与 /incident 命令的七步语义，在会话中动态编排；仓库文档与源码所能确认的是"这些能力被捆绑进同一插件、且各自的 description 描述了互补的职责"。

---

六、团队落地：安装、运行与适配建议

安装与运行

整个插件的使用前提，参见 devops-automation README：

• Claude Code 2.1+
• Kubernetes CLI（kubectl）
• 已配置可访问的集群

# 1. 安装插件
/plugin install devops-automation

# 2. 指向你的集群
export KUBECONFIG=~/.kube/config

# 3. 触发事故处置
/incident

由于 Incident Commander 是子代理而非命令，你在会话中通常不会直接"呼叫"它；正确用法是触发 /incident（或描述事故场景），让主线程 Claude 依据 description: Coordinates incident response 自动判断并委托给它。

若要复用或定制这份定义

把该文件当作团队自建事故响应子代理的模板时，可直接复制 incident-commander.md 并调整三处：

1. name：改为团队命名规范下的唯一标识；
2. description：措辞决定 Claude 在什么场景唤醒它，建议包含"incident / on-call / 事故 / 故障"等触发词与明确的职责边界；
3. tools：按需裁剪。若你只希望它"读与协调"而不允许改文件，可去掉 Write；若不需要 shell，可去掉 Bash，但注意那会同时失去调用诊断脚本与通知脚本的能力。

同时务必遵守插件安全约束：不要试图在该文件中声明 hooks、mcpServers、permissionMode——插件子代理沙箱不允许这些键（见 07-plugins/README.md 的 Plugin Security 一节），若需要更高权限的集群访问，应像 devops-automation 一样把它配置在插件级的 MCP 服务器（如 kubernetes-config.json）中。

版本兼容性提醒

如文件尾部所示，本定义面向 Claude Code 2.1.220 编写，并声明兼容 Claude Fable 5、Claude Opus 5、Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.8、Claude Haiku 4.5 等模型。团队落地前建议核对自身的 Claude Code 与模型版本，避免因插件/子代理规范差异导致加载异常。

---

七、小结：一份子代理文件背后的工程思想

回看这份只有十几行的 incident-commander.md，它浓缩了 Claude Code 插件生态中"用文档定义专家、用工具划定边界、用协作完成处置"的设计理念：

• 文档即定义：一个 Markdown 文件的 frontmatter + 职责清单，就能塑造一个可被主线程按需调度的领域专家；
• 边界即安全：tools 白名单 + 插件沙箱禁令，让高权限能力只在插件层显式配置、按需注入；
• 指挥而非执行：Incident Commander 的定位决定了它调用 health-check.sh、rollback.sh、Kubernetes MCP 等能力完成全流程闭环——评估分级、团队协调、状态同步、解决跟踪、复盘推进，一气呵成。

对于想在自己的 Claude Code 工程中建立"告警 → 研判 → 止血 → 复盘"事故闭环的团队，这份文件是轻量且可直接模仿的起点。

文中核心资源索引（均可点击跳转源码查看）：

• Incident Commander 子代理定义
• /incident 七步流程命令
• devops-automation 插件总览与安装说明
• Kubernetes MCP 配置
• 健康检查脚本
• 回滚脚本 与 部署脚本
• 插件安全约束与结构规范
• 同类子代理：告警分析器、部署专家