Claude Code 完整指南4-10

1. 引言

在这里插入图片描述

在前面的博客，博主已经讲解了 Claude Code 相关的概念，有兴趣的同学可以参考下：

如果你已经在用 Claude Code 写代码，你一定遇到过这些“重复但必要”的动作：

  • 写完文件要跑格式化、lint、单测
  • 运行危险 Bash 之前想要一层保险（尤其是 rm -rf、git push --force）
  • 想在会话开始时自动检查环境（Node/Python 版本、依赖是否安装）
  • 想在 Claude “准备停下”时强制做一次自检：测试过了吗？有未提交的改动吗？

Hooks 的价值就在于：把这些动作从“ 你记得做” 变成 “系统自动做” ，并且可以做到“该阻断就阻断、该后台跑就后台跑、该提醒就提醒”。

2. Hooks 是什么？

Hooks 是 Claude Code 的事件驱动自动化系统：在特定事件触发时，自动执行一组 Hook。

它主要有两种形态：

  1. 命令型 Hooks（command）：运行 Shell 命令/脚本，适合自动化与校验（格式化、检查、通知、跑测试……）。
  2. 提示型 Hooks（prompt）：在 Stop / SubagentStop 事件里，让 Claude 再做一次“停下前的质量检查”，根据结果决定继续还是停止。

你可以把它理解为：

  • SessionStart/End：会话生命周期钩子
  • PreToolUse/PostToolUse：工具执行前/后钩子（Write/Edit/Bash/Read…）
  • Stop/SubagentStop：模型准备结束前的“收尾门禁”
  • Notification：系统通知的自定义处理

3. Hooks 配置（用户级 vs 项目级）

Claude Code 支持分层配置，Hooks 通常按是否团队共享来决定目录。

项目级（推荐团队共享）:

  • 文件：{project}/.claude/settings.json
  • 适合：团队统一的格式化、测试、危险命令拦截、质量门禁等
  • 配套建议：把脚本也放进仓库，例如 {project}/.claude/hooks/*.sh，让团队开箱即用

项目级本地（仅自己用，不提交）:

  • 文件：{project}/.claude/settings.local.json
  • 适合：个人路径相关脚本、个人通知方式、私有工具等
  • 配套建议：加入 .gitignore

用户级（跨项目生效）：

  • 文件：~/.claude/settings.json
  • 适合：你个人的通用 Hooks（比如任何项目都启用的通知/危险命令拦截）

小贴士：团队规范建议 “项目级为主、用户级为辅”，项目级让仓库可复制；用户级放个人偏好。

4. 八种事件类型汇总

事件 触发时机 Hook 类型 常见用途
SessionStart 会话开始 命令型 初始化环境、检查依赖、打印提示
SessionEnd 会话结束 命令型 清理临时文件、记录统计
UserPromptSubmit 用户提交输入前 命令型 输入验证、关键词拦截、注入上下文
PreToolUse 工具执行前 命令型 危险命令拦截、参数校验、审计
PostToolUse 工具执行后 命令型 自动格式化、自动测试、生成变更摘要
Stop Claude 决定停止前 提示型 质量门禁（lint/test/git status）
SubagentStop 子代理停止前 提示型 子任务验收（比如“测试是否补齐”）
Notification Claude 发送通知时 命令型 转发通知（系统通知/Slack/飞书等）

5. 命令型 Hooks

写脚本就能自动化

5.1 基础语法（最常用）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/format.sh",
            "blocking": false
          }
        ]
      }
    ]
  }
}
json

关键点：

  • matcher：用于筛选工具（通常写正则/或模式串），比如 Write|Edit、Bash。
  • blocking：
    • true：Hook 失败会阻断当前动作（适合安全校验、门禁）
    • false：Hook 失败不阻断（适合格式化、统计、通知）

5.2 Hook 能拿到什么上下文？

命令型 Hooks 通常可以通过环境变量拿到上下文（不同事件变量略有差异，常见如）：

变量名 说明
TOOL_NAME 工具名称（如 Write/Edit/Bash）
TOOL_INPUT 工具输入（JSON 字符串）
TOOL_INPUT_FILE_PATH 文件路径（Write/Edit 常用）
TOOL_OUTPUT 工具输出（PostToolUse 常用）
USER_MESSAGE 用户输入（UserPromptSubmit）
CLAUDE_WORKING_DIR 当前工作目录
NOTIFICATION_MESSAGE 通知内容（Notification，JSON）

更稳妥的写法：脚本里同时支持读取 stdin（JSON）与环境变量，避免某些环境差异导致取不到值。

5.3 退出码怎么控制“阻断/不阻断”？

常见约定（建议你按这个写，团队最好统一）：

exit 0   # 成功，继续
exit 2   # 阻断错误（blocking=true 时会拦下本次操作）
exit 1   # 非阻断错误（记录/提示，但不中断主流程）
bash

6. 提示型 Hooks

让 Claude 在“停下前”做质量门禁

提示型 Hooks 仅用于 Stop / SubagentStop：当 Claude 觉得“差不多可以结束了”，会先跑一次这个提示，让它自检并输出 JSON 决策。

6.1 基础语法

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查是否满足停止条件。返回 JSON: {\"decision\":\"stop\"|\"continue\",\"feedback\":\"说明\"}"
          }
        ]
      }
    ]
  }
}
json

5.2 响应格式（核心）

{
  "decision": "continue",
  "feedback": "请先运行测试并修复 lint。"
}
json

你可以用它来实现 “Claude 自己给自己验收” 的体验，不满足条件就继续把事情做完，满足才停。

7. 案例模板

下面的模板尽量遵循一个原则：高风险校验 blocking=true，耗时工作 blocking=false。

依赖提示：后面的脚本示例会用到 jq 来解析 JSON（macOS 可用 brew install jq）。

7.1 案例：SessionStart 做环境体检（不阻断）

session-init.sh：检查 Node/Python/Git 状态、依赖是否安装等（按你的项目改）。

.claude/settings.json配置如下：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/session-init.sh", "blocking": false }
        ]
      }
    ]
  }
}
json

session-init.sh 示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

echo "🚀 Claude Code SessionStart"
echo "cwd: ${CLAUDE_WORKING_DIR:-$(pwd)}"

if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
  echo "git branch: $(git branch --show-current)"
  changes="$(git status --porcelain | wc -l | tr -d ' ')"
  if [[ "${changes}" != "0" ]]; then
    echo "⚠️  uncommitted changes: ${changes}"
  fi
fi

if [[ -f package.json ]]; then
  command -v node >/dev/null 2>&1 && echo "node: $(node --version)"
  [[ -d node_modules ]] || echo "📦 tip: run npm install"
fi

if [[ -f requirements.txt ]]; then
  command -v python >/dev/null 2>&1 && echo "python: $(python --version 2>&1 | head -n 1)"
  [[ -n "${VIRTUAL_ENV:-}" ]] || echo "🐍 tip: activate venv"
fi
bash

7.2 案例：PreToolUse 拦截危险 Bash（阻断）

guard-bash.sh 思路：从 TOOL_INPUT（或 stdin JSON）里取出 command，匹配 rm -rf、git push --force 等高危模式，命中就 exit 2 并在 stderr 输出原因。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/guard-bash.sh", "blocking": true }
        ]
      }
    ]
  }
}
json

guard-bash.sh 示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

input_json="${TOOL_INPUT:-}"
if [[ -z "${input_json}" ]]; then
  input_json="$(cat || true)"
fi

cmd="$(echo "${input_json}" | jq -r '.command // empty' 2>/dev/null || true)"
if [[ -z "${cmd}" ]]; then
  exit 0
fi

if [[ "${cmd}" == *"[claude-allow-danger]"* ]]; then
  exit 0
fi

deny_patterns=(
  '(^|[[:space:]])rm[[:space:]]+-rf[[:space:]]+(/|~|\\$HOME)([[:space:]]|$)'
  '(^|[[:space:]])git[[:space:]]+push([[:space:]].*)?--force'
  '(^|[[:space:]])git[[:space:]]+reset([[:space:]].*)?--hard'
  '(^|[[:space:]])chmod[[:space:]]+-R[[:space:]]+777'
)

for pattern in "${deny_patterns[@]}"; do
  if echo "${cmd}" | grep -Eq "${pattern}"; then
    echo "❌ 已阻断高危命令（PreToolUse）：" >&2
    echo "    ${cmd}" >&2
    echo "如确认要执行，请在命令末尾加 [claude-allow-danger] 作为显式确认。" >&2
    exit 2
  fi
done

exit 0
bash

7.3 案例：PreToolUse 做敏感信息检测（阻断）

适用场景：Write/Edit 写入内容前，扫描是否疑似 Key/密码/Token，命中直接拦截。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/check-secrets.sh", "blocking": true }
        ]
      }
    ]
  }
}
json

check-secrets.sh示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

input_json="${TOOL_INPUT:-}"
if [[ -z "${input_json}" ]]; then
  input_json="$(cat || true)"
fi
content="$(echo "${input_json}" | jq -r '.new_string // .content // ""' 2>/dev/null || true)"

patterns=(
  'AKIA[0-9A-Z]{16}'                  # AWS Access Key
  'ghp_[a-zA-Z0-9]{36}'               # GitHub PAT
  'sk-[a-zA-Z0-9]{32,}'               # API Key（示例）
  '(?i)password\\s*[:=]\\s*["\x27][^"\x27]+["\x27]'
  '(?i)api[_-]?key\\s*[:=]\\s*["\x27][^"\x27]+["\x27]'
)

for pattern in "${patterns[@]}"; do
  if echo "${content}" | grep -Pq "${pattern}" 2>/dev/null; then
    echo "❌ 检测到潜在敏感信息，已阻断写入（PreToolUse）" >&2
    echo "pattern: ${pattern}" >&2
    echo "建议：改用环境变量/密钥管理服务，不要把 Key 写进仓库。" >&2
    exit 2
  fi
done

exit 0
bash

7.4 案例：PostToolUse 自动格式化 + 自动跑测试（不阻断）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/format.sh", "blocking": false },
          { "type": "command", "command": "./.claude/hooks/auto-test.sh", "blocking": false }
        ]
      }
    ]
  }
}
json

format.sh 示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

file="${TOOL_INPUT_FILE_PATH:-}"
[[ -n "${file}" && -f "${file}" ]] || exit 0

case "${file}" in
  *.ts|*.tsx|*.js|*.jsx|*.json)
    command -v prettier >/dev/null 2>&1 && prettier --write "${file}" >/dev/null 2>&1 || true
    command -v eslint >/dev/null 2>&1 && eslint --fix "${file}" >/dev/null 2>&1 || true
    ;;
  *.py)
    command -v black >/dev/null 2>&1 && black "${file}" >/dev/null 2>&1 || true
    command -v isort >/dev/null 2>&1 && isort "${file}" >/dev/null 2>&1 || true
    ;;
  *.go)
    command -v gofmt >/dev/null 2>&1 && gofmt -w "${file}" >/dev/null 2>&1 || true
    ;;
  *.rs)
    command -v rustfmt >/dev/null 2>&1 && rustfmt "${file}" >/dev/null 2>&1 || true
    ;;
esac

exit 0
bash

auto-test.sh 示例代码如下：

#!/usr/bin/env bash
set -euo pipefail

file="${TOOL_INPUT_FILE_PATH:-}"
[[ -n "${file}" && -f "${file}" ]] || exit 0

if echo "${file}" | grep -Eq '(\\.test\\.|\\.spec\\.|/tests?/|__tests__)'; then
  exit 0
fi

if [[ -f package.json ]] && command -v npm >/dev/null 2>&1; then
  if echo "${file}" | grep -Eq '\\.(ts|tsx|js|jsx)$'; then
    echo "🧪 running minimal js/ts tests (best effort)"
    npm test --silent 2>/dev/null || true
  fi
fi

if [[ -f pyproject.toml || -f requirements.txt ]] && command -v pytest >/dev/null 2>&1; then
  if echo "${file}" | grep -Eq '\\.py$'; then
    echo "🧪 running minimal python tests (best effort)"
    pytest -q 2>/dev/null || true
  fi
fi

exit 0
bash

建议：

  • 格式化脚本按后缀选择 prettier/black/gofmt/rustfmt
  • 测试脚本“只跑与当前文件相关的最小集合”，避免每次都全量测试拖慢体验

7.5 案例：Notification 做系统通知（不阻断）

notify.sh（macOS）可以用 osascript 或 terminal-notifier，从 NOTIFICATION_MESSAGE 里取 title/message 发系统通知。

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "./.claude/hooks/notify.sh", "blocking": false }
        ]
      }
    ]
  }
}
json

notify.sh 示例脚本如下：

#!/usr/bin/env bash
set -euo pipefail

msg_json="${NOTIFICATION_MESSAGE:-}"
if [[ -z "${msg_json}" ]]; then
  msg_json="$(cat || true)"
fi

title="$(echo "${msg_json}" | jq -r '.title // "Claude Code"' 2>/dev/null || echo "Claude Code")"
message="$(echo "${msg_json}" | jq -r '.message // empty' 2>/dev/null || true)"
[[ -n "${message}" ]] || exit 0

if command -v terminal-notifier >/dev/null 2>&1; then
  terminal-notifier -title "${title}" -message "${message}" -group "claude-code" >/dev/null 2>&1 || true
  exit 0
fi

osascript -e "display notification \"${message}\" with title \"${title}\"" >/dev/null 2>&1 || true
exit 0
bash

8. 常见问题

问题一：Hook 不执行

可以通过如下方式排查：

开调试：

claude --debug="hooks"
bash

检查脚本可执行权限：

chmod +x ./.claude/hooks/*.sh
bash

脚本自测（用 stdin 模拟 JSON）：

echo '{"sessionId":"test"}' | ./.claude/hooks/session-init.sh
bash

问题二：无故被阻断

blocking=true 的 Hook 一定要做到：

  • 只在命中明确条件时才 exit 2
  • stderr 输出清晰原因（让 Claude 能把“为什么被拦”解释给你）

问题 三：变慢很明显

  • 把耗时任务（全量测试、扫描整个仓库）改成 blocking=false 或改成“增量/抽样”
  • 在脚本里加超时/短路条件（比如只对特定目录、特定后缀执行）

9. 文末

通过阅读本文，相信大家已经系统理解了 Claude Code 中 Hooks 的整体设计与实战价值：它并不是零散的脚本技巧，而是一套事件驱动的自动化与质量门禁机制。通过在 Session、Tool 执行前后以及 Stop 阶段合理配置命令型与提示型 Hooks，可以将格式化、测试、危险命令拦截、敏感信息校验等“重复但关键”的操作交由系统自动完成，把人为自觉升级为流程约束。

 

Claude Code 完整指南（五）：Subagents（AI 角色工程化）

Claude 在 “单个对话里完成一切” 当然可以，但当任务变复杂时，你会遇到三个典型瓶颈：

  • 上下文污染：你让它又写业务、又跑测试、又审安全、又写文档，对话会越来越“杂”，质量波动大。
  • 角色混乱：同一个模型既当开发又当审查，很容易出现“自己给自己过”的情况。
  • 可复用性差：团队里每个人都在重复写“你是测试专家/你是安全审计专家”的提示词。

Subagents 的定位就是：把这些 “固定角色” 固化成可复用配置，让主对话负责编排，子代理负责专业产出。

2. Subagents 是什么？

Subagents（子代理）是预配置的 AI 人格，每个 Subagent 都有：

  • 独立的指令与风格：可以理解为一个长期雇佣的 “测试工程师/安全审计/文档工程师”
  • 相对隔离的上下文：减少对主对话的污染，让主对话保持 “编排者” 角色
  • 独立的工具权限：比如只允许 Read/Grep，禁止 Bash/Write）

可以把主 Claude 理解成 Tech Lead / Orchestrator：拆任务、分派子代理、汇总结果、把子代理当成 “专职工种”。

3. Subagents 配置

Subagents 本质上就是一组 Markdown 文件，按作用域放两种位置：

用户级（跨项目复用）：

  • 目录：~/.claude/agents/
  • 适合：你个人常用的通用角色（比如安全审计、代码审查、文档写作）

项目级（推荐团队共享）：

  • 目录：{project}/.claude/agents/
  • 适合：和项目强绑定的角色（比如“本项目测试工程师：约定 Jest + 特定目录结构”）

团队最佳实践：把项目级 Agents 版本化提交到 Git，让新同学克隆仓库即可拥有同一套“AI 工种”。

如果把 Subagents、Hooks、Commands 都落到项目里，结构通常长这样：

your-project/
├── .claude/
│   ├── settings.json
│   ├── agents/
│   │   ├── test-writer.md
│   │   ├── code-reviewer.md
│   │   └── security-auditor.md
│   ├── hooks/
│   │   ├── format.sh
│   │   ├── auto-test.sh
│   │   └── guard-bash.sh
│   └── commands/
│       ├── review.md
│       └── test.md
└── CLAUDE.md
bash

3.1 配置格式

Subagent 文件是 “带 YAML Frontmatter 的 Markdown”，结构非常固定，例如：

---
name: test-writer
description: 专门编写单元测试和集成测试的 AI 助手
tools: Read, Write, Bash, Grep
model: sonnet
permissionMode: inherit
skills: api-testing
---

# Test Writer Agent

你是一位测试专家，专注于编写高质量的测试代码。
...
markdown

可以把它理解为：

  • YAML 区：机器可读（名字、权限、模型、技能）
  • 正文：人类可读（角色定义、工作流程、输出格式、约束条件）

3.2 核心配置

下面是最常用也最影响效果的四组字段。

3.2.1 tools（让子代理“能做什么”）

tools 是最直观的安全边界与能力边界：

  • Read/Grep：读代码、搜代码（适合审查类）
  • Write/Edit：写代码、改代码（适合实现类）
  • Bash：跑命令（适合测试/构建/脚手架类）

建议：能不开放就不开放。比如“安全审计”大多数时候只需要 Read, Grep。

3.2.2 permissionMode（让子代理“默认怎么申请权限”）

常见模式：

  • inherit：继承主会话的权限策略（最常用、最稳）
  • allow-all / deny-all / ask-all：按字面意思理解

建议：团队场景以 inherit 为主；确实需要强约束时再用 deny-all（例如“纯审查只读”）。

3.2.3 model（让子代理“用哪个模型”）

如果你的团队对成本/速度/质量有分层策略，可以这样用：

  • 主对话用更强模型负责编排与关键决策
  • 子代理按角色选择模型：例如测试/文档用更快模型，安全审计用更强模型

具体模型名建议用你在 settings 里配置的别名（便于后续统一切换）。

3.2.4 skills（把可复用步骤注入到子代理）

Skills 更像“标准作业程序（SOP）模板”，Subagent 更像“岗位说明书”：

  • Skill：如何做（步骤/命令/输出结构）
  • Subagent：谁来做（角色、边界、口吻、工具权限）

把 Skill 挂到 Subagent 上，能让团队把重复流程 “标准化”：例如 api-testing、db-migration、release-checklist。

4. Subagents用法

交互式的用法如下，输入以下命令：

/agents
bash

通过这个命令，可以：

  • 创建新 Agent
  • 选择某个 Agent 执行任务
  • 查看正在运行/已完成的 Agent 状态

当然也可以通过CLI  直接指定：

claude --agents test-writer "为 src/api/user.js 编写测试"
bash

也可以用 JSON 临时定义一个轻量代理（适合临时任务）：

claude --agents '{"name":"reviewer","tools":["Read","Grep"]}' "审查 src/ 下的潜在安全问题"
bash

当多个 Agent 并行干活时，可以理解/agents 就是 “任务面板”，把 “后台任务” 变得可见，也可以通过如下方式判断是否适合使用Subagent：

  • 适合 Subagent：审查/测试/文档/重构这类“有固定输出结构、可重复执行”的工种
  • 适合 Subagent：你希望它有严格边界（只读/禁 Bash/固定输出格式）
  • 不适合 Subagent：你还在探索需求、频繁变更方向（主对话更灵活）
  • 不适合 Subagent：一次性小任务（新建文件改两行），直接主对话更快

6. 最佳实践

6.1 实践原则

让子代理“可控、可复用、可验收”

① 子代理的提示不要写成“百科全书”

  • Subagent 的正文更像岗位说明书：只放长期有效的原则、约束、输出格式；项目细节放到 CLAUDE.md 或 Skill 里。

② 给每个 Agent 定一个“硬输出格式”

没有格式，主对话就很难汇总；一旦输出结构固定，主对话就能做到：

  • 并行启动多个 Agent
  • 把结果汇总成统一报告
  • 快速定位“必须修”的条目

③ 用工具权限做“最小能力原则”

  • 审查类：尽量只读（Read/Grep）
  • 写代码类：再开放 Write/Edit
  • 跑命令类：再开放 Bash（并配合 Hooks 做危险命令拦截）

④ 让主对话负责编排，子代理负责产出

推荐的协作方式：

  1. 主对话拆解任务与验收标准
  2. 子代理按角色产出（测试/审查/文档）
  3. 主对话统一验收与合并决策

这样做的好处是：责任边界清晰，质量更稳定。

6.2 Subagents、Hooks、Skills 组合工作

Subagents 解决的是“角色复用与并行”，Hooks 解决的是“自动触发与门禁”，Skills 解决的是“步骤模板”。

一个团队常见的组合拳是：

  1. Subagent：test-writer 负责补齐测试
  2. Hook：PostToolUse 自动格式化/跑测试（不阻断）
  3. Hook：Stop 做最终质量门禁（测试是否通过、lint 是否干净、git status 是否干净）
  4. Subagent：code-reviewer 只读审查给出必须修清单

6.3 案例模板

6.3.1 security-auditor（只读安全审计）

---
name: security-auditor
description: 安全审计与合规检查（只读）
tools: Read, Grep
permissionMode: deny-all
---

# Security Auditor

目标：找出高风险漏洞与可利用路径，并给出可执行修复建议。

输出格式（必须遵守）：
1) Critical（必须立刻修）
2) High（优先修）
3) Medium（建议修）
每条包含：文件路径 + 风险说明 + 复现/攻击思路 + 修复建议
markdown

6.3.2 test-writer（写测试 + 跑测试）

---
name: test-writer
description: 为变更补齐单测/集成测试，并尽量跑一遍验证
tools: Read, Write, Edit, Grep, Bash
permissionMode: inherit
---

# Test Writer

规则：
- 只改测试相关文件，避免改业务逻辑（除非确实需要测试注入点）
- 测试命名清晰，覆盖主路径 + 关键异常路径

输出格式：
- 新增/修改了哪些测试文件
- 运行了哪些测试命令（若无法运行，说明原因与替代建议）
markdown

6.3.3 code-reviewer（代码审查官）

---
name: code-reviewer
description: 严格代码审查（只读），给出可执行的 review checklist
tools: Read, Grep
permissionMode: deny-all
---

# Code Reviewer

重点检查：
- 逻辑正确性（边界/异常/并发）
- 可维护性（命名/结构/重复）
- 性能（热路径/无谓 IO/复杂度）
- 安全（注入/鉴权/敏感信息）

输出格式：
1) 必须修复（带原因与建议）
2) 建议优化
3) 可选风格
markdown

6.3.4 refactor-engineer（重构工程师）

---
name: refactor-engineer
description: 面向可维护性的重构（小步、可验证）
tools: Read, Write, Edit, Grep
permissionMode: inherit
---

# Refactor Engineer

原则：
- 每次重构只解决一个主题（例如“拆分函数”“去重复”“收敛边界”）
- 先加测试/保持行为等价，再动结构

输出格式：
- 重构目标与范围
- 关键改动点（按文件列出）
- 风险点与回滚策略
markdown

6.3.5 doc-writer（文档工程师）

---
name: doc-writer
description: 为功能/模块补齐开发者文档（README/ADR/使用示例）
tools: Read, Write, Edit, Grep
permissionMode: inherit
---

# Doc Writer

要求：
- 用最短路径让新同学跑起来：安装 → 配置 → 运行 → 常见错误
- 每个关键命令给出示例

输出格式：
- 新增/修改了哪些文档文件
- 文档中新增了哪些“可复制命令”
markdown

7. 文末

通过阅读本文，相信大家已经系统理解了 Claude Code 中 Subagents 的设计理念与工程价值：它并不是“多开几个对话”的技巧，而是一套 角色固化、上下文隔离、权限可控的协作机制。通过将测试、审查、安全、文档等稳定工种抽象为 Subagent，并与主对话形成“编排者 + 专职角色”的协作模式，可以显著降低上下文污染与角色混乱，让复杂任务具备可并行、可复用、可验收的工程属性。

 

1. 引言

在这里插入图片描述
在前面的博客，博主已经讲解了 Claude Code 相关的概念，有兴趣的同学可以参考下：

很多人用 Claude Code 用着用着，会出现一个非常典型的“团队化痛点”：

  • 同一个需求，不同人问法不同，Claude 输出结构就不同
  • 今天它写出了测试证据，明天它只给一段“我觉得差不多”
  • 团队有规范（比如迁移必须可回滚、PR 必须写风险与回滚），但 AI 不一定每次都记得

Skills 的价值不在 “更聪明”，而在“更稳定”：把一类任务的标准步骤、检查清单、输出格式、工具边界写成 Skill，让它每次都按 SOP交付 （Standard Operating Procedure，翻译为标准操作流程）。

2. Skills 是什么?

Skills 是一个独立的任务模板，核心由三部分组成：

  1. 触发语义：description 描述 “什么时候用我”
  2. 执行流程：正文写 “怎么做（步骤/清单/约束）”
  3. 能力边界：allowed-tools 约束 “能用哪些工具”

它可以：

  • 手动调用（最可控）
  • 自动触发（依赖 description 匹配）
  • 被 Subagent 引用（把 SOP 固化到某个岗位上）

3. 如何理解 Skills、Subagents、Hooks

把这三个概念分清楚，你就知道 “该用 Skill 还是该用 Subagent”：

能力 它更像 解决的问题 适合什么场景
Skills SOP/作业指导书 让输出结构稳定、流程可复制 审查清单、迁移模板、文档生成、PR 总结
Subagents 岗位/专职工种 让角色边界清晰、上下文更干净 测试工程师、安全审计、文档工程师、重构工程师
Hooks 事件触发器/门禁 让流程自动发生、能阻断风险 代码格式化、危险命令拦截、Stop 质量门禁

总结：Skill 定“怎么做”，Subagent 定“谁来做”，Hook 定“什么时候做/能不能继续”。

如果结合5w1h图，可能就更容易理解了，Skills → HOW | Subagent → WHO | Hooks → WHEN。
在这里插入图片描述

4. Skills 配置

Skill 的基本结构是：一个文件夹 + SKILL.md。

用户级（跨项目复用）配置示例：

~/.claude/skills/
└── code-reviewer/
    └── SKILL.md
bash

适合：你个人通用的 SOP（安全审查、变更总结、周报整理）。

项目级（推荐团队共享）配置示例：

{project}/.claude/skills/
├── api-doc-generator/
│   └── SKILL.md
└── db-migration-helper/
    └── SKILL.md
bash

适合：强依赖项目结构与技术栈的 SOP（路由风格、目录规范、测试命令、迁移框架）。

团队最佳实践：项目级 Skills 提交到 Git；个人覆盖放 settings.local.json 或用户级 skills。

4.1 SKILL.md 结构

Skill 定义文件是 SKILL.md（Markdown + YAML frontmatter），示例：

---
name: Code Review Assistant
description: Perform comprehensive code reviews focusing on security, performance, and best practices
user-invocable: true
context: fork
model: opus
allowed-tools:
  - Read
  - Grep
  - Bash
---

# Code Review Instructions

你是一位资深工程师，目标是产出可执行的 Review 报告。

## Checklist
- Security
- Performance
- Best Practices

## Output Contract
1) Summary
2) Must Fix
3) Suggestions
4) Test Evidence
markdown

理解重点：

  • YAML 区决定“运行方式”（能否在菜单出现、是否隔离上下文、用哪个模型、允许哪些工具）
  • 正文决定“产出质量”（流程/清单/约束/输出契约）

4.2 关键字段解析

4.2.1 name、description

name：展示名（给人看）

description：触发语义（给 Claude 判断“何时用”），建议写法：

  • 写清楚 “Use when … / 当用户要 … 时使用”
  • 把关键词写进去（review/security/changelog/migration/docs/test）
  • 不要写成一句很空的口号（例如 “helps with coding”）

4.2.2 user-invocable

作用：是否显示在 /skills 列表

  • 默认：true
  • 建议：
    • 团队对外入口：true
    • 内部中间件 Skill（只给 Subagent 引用）：可以设为 false，减少干扰

4.2.3 context: fork

作用：让 Skill 在“隔离的 fork 上下文”运行（减少污染主对话）

建议：

  • 审查/总结/报告类默认 fork
  • 需要连续交互、多轮拿上下文才能完成的任务，谨慎使用（否则主对话看不到细节，只拿到结果）

4.2.4 model

作用：指定 Skill 的模型（建议用你配置过的别名）

团队建议：

  • 高频 SOP（文档/总结）用更快模型
  • 高风险（安全审计/迁移门禁）用更强模型或主对话复核

4.2.5 allowed-tools 

作用：白名单：Skill 只能使用这些工具

最小权限原则：

  • 只读审查：Read, Grep
  • 文档生成：Read, Grep, Write
  • 迁移生成：Read, Write（Bash 能不开就不开；确实需要再加）

5. Skills 用法

5.1 Skills 命令调用

可以通过如下命令手动调用 Skills：

/skills
bash

从列表里选择某个 Skill 执行即可（最可控、最可复现）。 很多情况下，列表里也会提供一个对应的“可直接输入的命令入口”（例如 /xxx），但团队落地时建议仍以 /skills 的可视化列表作为统一入口，避免命名变动造成学习成本。

当然，当输入的需求与某个 Skills 的 description 足够匹配，Claude 也会尝试自动触发它。

5.2 Subagent 引用 Skills

在 Subagent 的 YAML 里绑定 skills，例如：

---
name: api-tester
description: API 测试专家
skills: api-testing, change-summary
---
markdown

这类输出会更稳定，也更像团队工作流。

###= 5.3 Skills 定义规范

① 推荐命名规范（减少调用成本）：

  • Skill 目录名：kebab-case，语义明确（change-summary/、api-doc-generator/）
  • name：给人看的标题（可以更友好）
  • description：像搜索关键词一样写（可触发、可理解）

② 把“输出契约”写死（让结果可验收）：

  • Summary（3~5 行）
  • Deliverables（产物清单：文件/命令/链接）
  • Risks（风险与回滚）
  • Test Evidence（测试证据）
  • Next Actions（下一步）

③ 把 Skill 当作“流程资产”版本化：

  • 提交 Git（像提交脚本一样）
  • PR 审核 Skill 变更（因为它影响“团队的默认产出方式”）
  • 和 Hooks/Subagents 一起形成 .claude/ 目录的“开箱即用工程规范”

④ 工具边界：建议先收紧 allowed-tools，不够用再放开

⑤ Skill 编写 Checklist：

  • description` 可触发：明确 Use when / 当用户要…时使用（别写空话）
  • 输出契约固定：Summary/Deliverables/Risks/Test Evidence/Next Actions
  • 步骤可执行：每一步都能落到“读哪些文件/产出什么内容”
  • 工具最小化：只给完成任务所需的最小 allowed-tools
  • 能兜底：写清“信息不足时要反问什么/要我提供什么”

5.3 案例模板

5.3.1 change-summary（PR 描述/发布说明生成器 ）

---
name: Change Summary Generator
description: Generate PR description / release notes / changelog from code changes. Use when user asks for summary, changelog, release notes, or PR description.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
---

# Change Summary

目标：把变更整理成“可直接粘贴到 PR/发布说明”的结构化内容。

输出契约（必须遵守）：
1) Summary（3~5 行）
2) User Impact（谁会受影响）
3) Risk & Rollback（风险与回滚策略）
4) Test Evidence（跑了什么/没跑为什么）
5) Notes（兼容性/配置变更/迁移说明）
markdown

5.3.2 api-doc-generator（API 文档生成器）

---
name: API Documentation Generator
description: Generate API documentation from routes/types/comments. Use when user asks to create API docs or document endpoints.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
  - Write
---

# API Documentation

对每个 endpoint 输出（必须完整）：
- Method / Path / Description
- Auth（是否需要登录/权限）
- Request（Headers/Params/Body Schema）
- Response（Success Schema + Error Codes）
- curl Example（可复制）

额外要求：
- 如果找不到路由定义，说明你查了哪些文件/模式（便于我补上下文）
markdown

5.3.3 db-migration-helper（数据库迁移助手：必须可回滚）

---
name: Database Migration Helper
description: Help create safe and reversible database migrations with explicit up/down. Use when user needs to modify database schema.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Write
  - Bash
---

# Database Migration Helper

原则：
1) 必须可回滚（必须有 Down）
2) 高风险操作必须显式标注（drop/rename/backfill）
3) 考虑性能与锁表风险（索引/大表 DDL）

输出契约：
1) Migration Plan（步骤 + 风险点）
2) Up Migration（完整内容）
3) Down Migration（完整内容）
4) Rollout Notes（上线建议：分批/灰度/监控项）
5) Rollback Steps（回滚命令/验证点）
markdown

5.3.4 code-review-assistant（结构化代码审查：可执行清单）

---
name: Code Review Assistant
description: Perform comprehensive code reviews focusing on security, correctness, performance, and maintainability. Use when user asks to review code or audit changes.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
---

# Code Review Assistant

审查范围：
- Correctness（边界/异常/并发）
- Security（鉴权/注入/敏感信息）
- Performance（热路径/IO/复杂度）
- Maintainability（命名/结构/重复/可测试性）

输出契约（必须遵守）：
1) Summary（一段话）
2) Must Fix（每条：文件 + 问题 + 影响 + 修复建议）
3) Should Fix（同上）
4) Nice to Have（可选）
5) Test Suggestions（建议补哪些测试）
markdown

5.4 与 Hooks/Subagents 组合：把流程做成“装配线”

如果只做 Skills，会得到“更稳定的模板”；但如果把 Skills、Subagents、Hooks 组合起来，就能得到“自动化流水线”，一个最容易落地的团队组合拳：

  • Subagent：test-writer（岗位）绑定 Test Generator 类 Skill（SOP）
  • Hook：PostToolUse(Write|Edit) 自动格式化 + 最小测试（不阻断）
  • Hook：Stop 做最终门禁（测试/lint/git status）
  • Skill：change-summary 在最后生成 PR 描述（结构化输出）

这样基本能做到：每次交付都带 测试证据、风险与回滚、可直接粘贴的 PR 总结。

6. 文末

通过阅读本文，相信大家已经系统理解了 Claude Code 中 Skills、Subagents 与 Hooks 的设计理念与工程价值：它们并不是 “会用 AI 就行” 的技巧，而是一套 任务固化、角色分工、事件驱动 的团队化协作机制。通过将常用流程抽象为 Skills（可复用 SOP）、将岗位职责封装为 Subagents（角色隔离、权限可控）、并通过 Hooks 自动触发关键步骤，可以显著提升交付的稳定性、可复用性与可验收性，让复杂任务具备可并行、可自动化、可回滚的工程属性。

1. 引言

在这里插入图片描述
在前面的博客，博主已经讲解了 Claude Code 相关的概念，有兴趣的同学可以参考下：

前几篇我们解决的更多是 “Claude Code 如何在本地更好地工作”：

  • 用 Hooks 做门禁与自动化
  • 用 Subagents 做角色分工与并行
  • 用 Skills 把 SOP 固化成可复用模板

但这些能力的边界仍然主要在“本地文件/命令”。

MCP 的意义在于：让 Claude 能用标准协议连接到外部系统 —— GitHub、数据库、监控平台、内部 API、知识库……

从这一刻开始，Claude 才真正具备 “像工程师一样操作系统” 的能力：查数据、找异常、开工单、回写状态、联动流程。

2. MCP 是什么？

2.1 概念

MCP（Model Context Protocol） 是一个标准化协议，用于让 Claude 连接外部服务。你可以把它理解成：

  • 外部服务提供一个 MCP Server
  • MCP Server 暴露 Tools / Resources / Prompts
  • Claude Code 通过 MCP 把这些能力当成“可调用工具”使用

在 Claude Code 里，MCP 主要用于扩展两类能力：

  1. 读：把外部数据源作为上下文（比如查数据库、读 PR、读告警）
  2. 写：对外部系统执行动作（比如创建 Issue、发消息、更新工单）

2.2 Tools / Resources / Prompts

MCP 的核心概念通常按这三类理解：

概念 可以理解为 示例
Tools 可调用的 “动作” github.create_issue、db.query、sentry.list_errors
Resources 可读取的 “数据源” PR 列表、某条告警详情、某张表的数据
Prompts 预定义的 “提示模板” 固定的“事故复盘模板”“发布检查模板”

注意：MCP 并不是“自动帮你做事”，而是提供一个规范接口，让 Claude 能安全、可控地访问外部能力。

2.3 传输方式

Claude Code 里常见的 MCP 传输方式主要有两种：

2.3.1 HTTP（推荐）

  • 适合：GitHub、Sentry、Slack、内部平台（有服务端、可复用）
  • 优点：部署在统一环境、便于权限与审计、多人共享
  • 典型配置字段：transport: "http" + url

2.3.2 stdio（本地进程）

  • 适合：本地快速试验、数据库连接、本地脚本封装成 MCP
  • 优点：启动简单、无需单独部署服务
  • 风险：凭证/环境变量/本地网络访问更分散；团队复用成本更高
  • 典型配置字段：transport: "stdio" + command + args + env

选型建议（团队落地版）：

  • 团队要长期用、要审计、要统一权限：优先 HTTP
  • 个人本地工具、短期实验：用 stdio

3. MCP 配置

Claude Code 常见的 MCP 配置入口有种。

① 全局配置（用户级）：

  • 位置：~/.claude.json
  • 字段：mcpServers
  • 适合：你个人跨项目复用的 MCP（比如 GitHub、个人数据库等）

示例（节选）：

{
  "mcpServers": {
    "user": {
      "github": {
        "transport": "http",
        "url": "https://github-mcp.example.com"
      },
      "database": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres"]
      }
    },
    "local": {}
  }
}
json

② 项目配置（项目级）：

  • 位置：{project}/.mcp.json
  • 字段：mcpServers
  • 适合：团队共享、与项目强绑定的 MCP（内部 API、项目专用服务）

示例（节选）：

{
  "mcpServers": {
    "github": {
      "transport": "http",
      "url": "https://github-mcp.example.com"
    }
  }
}
json

团队最佳实践：项目级 .mcp.json 可提交 Git；个人密钥用环境变量，不要写死在配置里。

4. MCP 用法

4.1 安装/添加 MCP Server

# HTTP 服务器
claude mcp add --transport http github https://api.github.com/mcp

# stdio 服务器（本地进程）
claude mcp add --transport stdio weather -- npx @modelcontextprotocol/server-weather
bash

带环境变量示例（stdio）：

claude mcp add --transport stdio database \
  --env DB_HOST=localhost \
  --env DB_PORT=5432 \
  --env DB_USER=admin \
  -- node ./mcp-servers/database.js
bash

项目级安装示例：

claude mcp add --scope project slack-bot https://slack.company.com/mcp
bash

4.2 管理命令

claude mcp list
claude mcp get weather
claude mcp remove weather
bash

你可以在会话里查看 MCP 状态、并对需要认证的服务器完成 OAuth 流程（如果该 server 配置了 OAuth），命令如下：

/mcp
bash

4.3 案例模板

推荐的项目目录布局（MCP + Claude 配置）：

your-project/
├── .claude/
│   ├── settings.json
│   ├── settings.local.json        # 个人环境变量（不提交）
│   ├── agents/
│   ├── skills/
│   ├── hooks/
│   └── commands/
├── .mcp.json                      # MCP 服务器配置（可提交）
└── CLAUDE.md
bash

{project}/.mcp.json：

{
  "mcpServers": {
    "github": {
      "transport": "http",
      "url": "https://github-mcp.example.com",
      "auth": {
        "type": "oauth2",
        "clientId": "${GITHUB_CLIENT_ID}",
        "clientSecret": "${GITHUB_CLIENT_SECRET}"
      }
    },
    "database": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "transport": "http",
      "url": "https://sentry-mcp.example.com/api",
      "headers": {
        "Authorization": "Bearer ${SENTRY_TOKEN}"
      }
    }
  }
}
json

建议：

  • .mcp.json 里只写“连接方式”，凭证一律从环境变量注入
  • 如果你用 settings.local.json 管理环境变量，别把它提交到 Git

4.4 Hooks / Subagents / Skills 使用 MCP

MCP 单独用当然可以，如果结合Claude，可以实现“系统化编排”，下面讲解几个场景。

4.4.1 MCP + Subagent

这种方式可以理解为：专职工种操作外部系统

例子：你可以定义一个只负责“处理告警”的子代理（只开放必要工具 + MCP）。

  • 子代理负责：查 Sentry、定位错误、创建 Issue、回填链接
  • 主对话负责：确认策略、决定是否上线修复、做最终把关

4.4.2 MCP + Skills

这种方式可以理解为：把外部操作变成 SOP

例子：做一个 incident-triage Skill（事故分诊 SOP）：

输出契约固定为：

  1. Incident Summary（现象与影响面）
  2. Evidence（Sentry 错误、关键日志、相关 PR）
  3. Hypothesis（最可能原因）
  4. Actions（创建 Issue/PR/通知）
  5. Rollback & Mitigation（缓解与回滚）

有了 MCP 之后，Skill 不再只是“写文字”，而是能拉取证据、完成动作。

4.4.3 MCP + Hook

这种方式可以理解为：把通知与门禁接到团队系统

可以用 Notification Hook 做系统通知：

  • 让 Hook 把关键事件转发到 Slack（通过 Slack MCP server）
  • 在 Stop 门禁失败时自动发一条“测试没过/风险提示”到团队

注意：Hook 执行外部动作一定要谨慎，建议默认 blocking=false，并加入明确的白名单/开关。

4.5 安全性问题

MCP 的能力越强，越要把 “安全边界” 先立起来，建议如下：

① 凭证管理：只用环境变量，不写死：

.mcp.json / ~/.claude.json 里不要直接写 Token，推荐：

  • OAuth：走 /mcp 完成授权
  • Header/Token：用 ${ENV:...} 或 ${VAR} 形式引用（具体以你们配置规范为准）

② 最小权限原则：能只读就只读

  • 只做查询：尽量只开放读取型工具
  • 必须写入：让操作变成显式动作（最好让主对话确认）

③ 建议的权限落地顺序（先收住“写操作”）

如果第一次接 MCP，建议按“风险从低到高”开放：

  1. 只读型 MCP：读 PR、读告警、读数据库查询（先跑通证据链）
  2. 低风险写入：发通知、写评论（可逆、影响小）
  3. 高风险写入：合并 PR、改配置、删资源（必须人工确认 + 审计）

同时建议配合第四篇的 Hooks：

  • PreToolUse(Bash) 拦截危险命令
  • Stop 门禁失败时给出明确反馈（必要时通知团队）

④ 企业策略（Managed Settings）

企业场景里，常见做法是把 MCP server  的范围/白名单锁到托管配置里，例如：

  • 只允许连接批准的 MCP 域名
  • 强制开启审计日志
  • 锁定 mcpServers 不允许用户修改

4.6 主流 MCP 资源导航

如果想找“主流 MCP Server/SDK/生态工具”，建议优先从官方入口开始（最权威、更新也最快）：

建议：不同 MCP Server 的鉴权、能力范围、写操作风险差异很大，团队落地时建议先接只读能力，再逐步放开写入，并配合审计与门禁。

5. 文末

通过阅读本文，相信大家已经系统理解了 Claude Code 中 MCP（Model Context Protocol） 的设计理念与工程价值：它并不是“让 AI 自动替你操作系统 ”的黑盒能力，而是一套 以标准协议为边界、以权限与审计为前提的外部能力接入机制。

MCP 的核心意义在于：把真实世界的系统能力（代码仓库、数据库、监控平台、内部 API）安全、可控地引入到 Claude 的上下文与行动空间中。通过 MCP，Claude 不再只停留在 “分析与建议”，而是能够 读取真实数据、执行明确动作、回写处理结果，让 AI 参与到完整的工程闭环中。

1. 引言

参考官方文档： https://code.claude.com/docs/en/output-styles

在这里插入图片描述

在前面的博客，博主已经系统讲解了 Claude Code 的核心能力，有兴趣的同学可以先了解：

本文主要聊 Output Styles，它并不是字面上的 “输出风格，让回答更好看”，而是把 Claude Code 的 系统提示词 “换皮”，让 Claude 在保持本地能力（跑脚本、读写文件、TODO 追踪）的同时，变成你需要的任何类型 Agent（事故指挥官、产品经理、技术写作、数据分析助手、代码导师……）

2. Output Styles 是什么？

2.1 概念

在这里插入图片描述

一句话总结：Output Styles 通过“修改 Claude Code 的 system prompt”，把 Claude Code 变成不同类型的 Agent。

官方定义里强调了两点：

  • Claude Code 的核心能力依然保留，例如：运行本地脚本、读写文件、追踪 TODO。
  • 输出/交互方式会被“风格化”，不局限于 软件工程师助手，也就是说不只是仅开发人员可以使用，其它人也能使用。

为了更好理解，可以把 Output Styles 当作：

  • “长期生效的输出契约”：要求它每次都按某种固定结构输出（标题/表格/清单/风险提示/确认口径）。
  • “默认工作方式的开关”：比如要不要先问问题、要不要先出计划、要不要教育性讲解、要不要把关键步骤留给你做。
  • “身份 + SOP 的最小集合”：它不替代 Skills 的完整流程，但能把 “每次都必须遵守的交互规则”固化下来。

2.2 三种内置风格

Claude Code 自带 3 种风格的 Output Styles：

  • Default（默认）：偏执行、偏高效、偏落地（默认 system prompt）的工程师风格。
  • Explanatory（讲解型）：会在干活过程中插入教育性 “Insights”，适合看懂代码库、理解实现选择、快速熟悉模式。
  • Learning（共学型）：不仅解释，还会让你“参与写几行关键代码”，会在代码里插入 TODO(human) 让你完成，适合带新人、结对编程、训练自己在项目里的手感。

在这里插入图片描述

2.3 如何理解？

这里举一个例子来加深对 Output Styles 的理解。例如：用同一个请求做 A/B 测试最直观，这个时候会对 Claude 说：

“请帮我把一个 POST /orders 接口补上幂等（Idempotency-Key），并告诉我为什么这样设计。”

如果选择不同的Output Styles，会看到如下的差异：

  • Default：倾向直接落地改动（要改哪里、怎么做、怎么验证），解释更少。
  • Explanatory：会在关键选择点插入解释（幂等键存哪里、冲突怎么返回、重试语义）。
  • Learning：会把关键一两处留 TODO(human)（例如“你来补：幂等键表的唯一索引/冲突处理分支”），并引导完成。

如果你“看不出差异”，通常不是你没理解，而是：你给的任务太小/太确定（比如“把变量名改一下”），任何风格都差不多。用这种更“有选择空间”的任务测试最有效。

2.4 易混淆点（统一对照）

下表从作用位置、影响范围、适用场景三个核心维度，对 Output Styles、CLAUDE.md、--append-system-prompt、Subagents 与自定义 Slash Commands 进行统一对照：

能力/机制 作用到哪里 影响范围 典型用途
Output Styles System Prompt（主对话） 主 agent 的整体角色、语气、输出契约 从“工程师助手”切换到产品、运维、写作、法务等身份
CLAUDE.md User Message（system 之后） 项目级约束与背景信息 项目规范、目录结构、流程约定、注意事项
--append-system-prompt System Prompt 当前会话的行为强化 临时试验、一次性强化、对比测试
Subagents（Agents） 子 agent（被调用） 具体任务的模型、工具、权限边界 任务分工、能力隔离、自动化流程
自定义 Slash Commands 触发指令 单次流程或模板化操作 快捷执行固定步骤或提示词

一句话理解以上易混淆的概念点:

  • Output Styles 决定“你在和谁对话”
  • CLAUDE.md 决定“这个项目有哪些约束”
  • Subagents 决定“任务怎么分工、用什么能力做”
  • Slash Commands 决定“什么时候快速跑一套流程”
  • --append-system-prompt 只是临时改一下脑回路

3. Output Styles 的工作原理

官方文档里有几条结论，我们把它当成“规则”记住：

  1. Output styles 直接修改 system prompt ；
  2. 所有 output styles 都会去掉“高效输出”的那部分指令（例如“尽量简洁”） ；
  3. 自定义 output style 默认也会去掉“编码相关指令”（例如“跑测试验证”），除非设置 keep-coding-instructions: true
  4. 风格指令会被追加到 system prompt 末尾，并在对话过程中反复提醒 Claude 遵守

用人话说就是：

如果想要 “简洁 / 固定格式 / 先问再做 / 先列计划 / 必须给检查清单”，都要在 Output Styles 里明确写出来；否则你以为的“默认行为”，可能已经被关掉了。

很多人看完文档还是懵，核心原因是：你以为 Output Style 只改“措辞”，但它可能连“工程化习惯”也一起改掉。

可以这样去理解：

  • keep-coding-instructions: true：更像“换一种表达/协作方式，但仍按工程师方式做事”
    典型表现：会主动建议/运行测试、会按改动范围做验证、会更谨慎处理写入操作。
  • keep-coding-instructions: false（默认）：更像“把它从工程师助手切到别的身份”
    典型表现：可能更偏文档产出/决策建议/模板填写；当我们让它改代码时，它仍能改，但更容易忽略 “跑测试/验证/边界检查/逐步确认” 这类习惯。

一个容易踩坑的场景，例如让 Claude 写了一个 “PRD Writer” 风格（false），同时让它顺手改个接口，它可能就“直接给你一段代码/建议”，但不再默认把验证步骤当成必须项。

解决方式：把 keep-coding-instructions 改 true，或者在风格里明确写：“涉及代码/配置变更时必须给验证清单、必须先确认风险点”。

4. Output Styles 用法

4.1 命令行使用

官方提供了两种方式使用Output Styles。

4.1.1 命令

运行/output-style 打开菜单选择或者直接 /output-style explanatory（举例）：
在这里插入图片描述

另外 /config 菜单里也能进到同一个入口。
在这里插入图片描述

4.1.2 配置文件

切换 会保存到项目级别的 .claude/settings.local.json，也可以在不同层级 settings  文件里手动改 outputStyle 字段（比如想给整个项目默认一个风格）。

示例（节选）：

{
  "outputStyle": "explanatory"
}
json

4.2 自定义 Style

自定义 Output Style 本质是一个 Markdown 文件：

  • frontmatter（可选元数据）
  • 正文（会被追加到 system prompt）

存放位置两种（官方推荐）：

  • 用户级：~/.claude/output-styles
  • 项目级：.claude/output-styles（更适合团队共享，能进 Git）

4.2.1 官方推荐模板

---
name: My Custom Style
description:
  A brief description of what this style does, to be displayed to the user
keep-coding-instructions: false
---

# Custom Style Instructions

[你的风格指令写在这里]

## Specific Behaviors

[具体行为约束写在这里]
markdown

frontmatter 字段要点（官方表格）：

  • name：显示名（不写就继承文件名）
  • description：仅用于 /output-style UI 展示
  • keep-coding-instructions：是否保留“编码相关 system prompt 指令”（默认 false）

4.2.2 如何写 Style

写 Output Style 时，建议按下面 5 件事组织（缺了就容易“感觉没变化”或“容易跑偏”）：

  1. 目标：一句话说明它要把对话变成什么（例如“可发群的纪要”“可执行的事故处置清单”）。
  2. 输入澄清规则：先问几个问题？不足时必须先问而不是瞎编？
  3. 输出结构（最关键）：固定小节标题/表格字段/清单项（最好“严格包含”，没有就写“暂无”）。
  4. 行动边界：什么情况必须先征求确认？什么情况禁止执行？要不要提供回滚/风险？
  5. 简洁度/语气：要短句、要表格、要不讲科普、还是要教学式解释？

可以把它理解为：把“你每次都要反复提醒 Claude 的话”，搬进 Output Style 里，让它自动记住。

4.3 案例模板

下面举例三个Output Style案例，这些案例可以放到 .claude/output-styles/。

4.3.1 事故分诊风格

建议配合 MCP使用，incident-triage.md 模板如下：

---
name: Incident Triage
description: 用于线上事故分诊与处置建议（先证据后结论）
keep-coding-instructions: true
---

# Custom Style Instructions

你是“线上事故分诊官”。目标：快速收敛问题、降低影响面、推动可执行动作。
默认保持回答简洁，避免长篇科普。

## Specific Behaviors

- 永远先问清楚：时间范围、影响面、是否可回滚、当前缓解措施。
- 永远先给出“你还缺哪些关键证据”，并给出最小可行的获取方式。
- 输出必须严格包含以下小节（没有也要写“暂无”）：
  1) Incident Summary（现象 & 影响）
  2) Evidence（证据）
  3) Hypotheses（按可能性排序）
  4) Actions（可执行动作清单，标注风险/可逆性）
  5) Rollback & Mitigation（回滚/缓解方案）
  6) Next Check（下一步验证点）
- 涉及写入/破坏性操作时，必须先征求确认，并给出回滚预案。
markdown

这里建议 keep-coding-instructions: true，因为事故处理中往往仍需要 Claude 保持“工程化习惯”（验证、检查、谨慎执行）。

4.3.2 PRD 写作风格

prd-writer.md模板如下：

---
name: PRD Writer
description: 用于需求分析与 PRD 产出（结构化、可评审）
keep-coding-instructions: false
---

# Custom Style Instructions

你是资深产品经理 + 技术合作者，负责把需求写成“可评审、可落地”的 PRD。

## Specific Behaviors

- 先问 3~7 个澄清问题（不足就不要直接写 PRD）。
- PRD 必须包含：背景、目标、非目标、用户故事、范围、交互/流程、埋点、验收标准、风险与灰度方案、里程碑。
- 每个验收标准必须可测试、可观察，避免空话。
- 输出尽量短句，表格优先。
markdown

4.3.3 会议纪要风格

meeting-notes.md 模板风格如下：

---
name: Meeting Notes
description: 会议纪要与行动项提炼（可直接发群）
keep-coding-instructions: false
---

# Custom Style Instructions

你是会议记录员。目标：把讨论变成对齐材料与行动项。

## Specific Behaviors

- 输出必须包含：
  - 结论（Decisions）
  - 待办（Action Items：Owner / Due / 内容）
  - 风险与未决（Risks & Open Questions）
- 不要复述过程；只保留对齐需要的信息。
- 行动项不超过 10 条，超过就合并/聚类。
markdown

5. 文末

通过阅读本文，相信大家已经系统理解了 Claude Code 中 Output Styles 的设计初衷与工程意义：它并不是简单的“回答风格切换”，也不是为了让输出更好看，而是通过 修改 system prompt，在不影响 Claude Code 本地能力的前提下，重新定义 Claude 的角色身份、默认行为与交互契约。

Output Styles 的核心价值在于：把“你希望 AI 如何工作”这件事，从一次次临时提示，固化为长期生效的系统级规则。通过合理设计 Output Style，Claude 可以稳定地扮演事故分诊官、产品经理、技术写作助手或协作型代码导师，在不同场景下遵循固定结构、明确边界，并保持一致的工程习惯。

1. 引言

参考官方文档（建议收藏）：

在这里插入图片描述
在前面的博客，博主已经系统讲解了 Claude Code 的核心能力，有兴趣的同学可以先了解：

这一篇我们聊 Plugins，它不是一个新的概念，而是把在 .claude/ 里写的 slash commands / agents / hooks / Skills / MCP 这些能力，打包成一个 可安装、可版本化、可给其它人复用 的“能力包”。

2. Plugins 是什么？

一句话总结：Plugin = 一个目录 + 一个清单文件 .claude-plugin/plugin.json + 一堆你要分发的能力（commands / agents / hooks / Skills / MCP / LSP）。

大白话就是：你把 Claude Code 当成一台“可扩展的工作台”，.claude/ 适合你自己在当前项目里折腾，而Plugin 更像一个“可安装的扩展包”，可以跨项目复用，还能发给团队/社区。

2.1 Plugin 命名空间

Plugin 的 slash command 一律 带命名空间，如果文件叫 commands/hello.md，插件名（plugin.json 里的 name）叫 my-first-plugin，那么最终命令就是：/my-first-plugin:hello

为什么要 namespace命名空间？ 因为装了多个插件后，都叫 /review、/hello 的概率太高了，使用命名空间就能防止冲突。

2.2 Plugin 什么时候使用？

什么时候用 Plugin，什么时候继续用 .claude/？官方给的对比非常直白：

你现在的需求 更适合
我就自己用、在单个项目里调试、想快 .claude/（Standalone）
要给同事用、要跨项目复用、要版本管理 Plugin
我很在意命令短：/review、/hello .claude/
我能接受命令带前缀：/team-tools:review Plugin

一个很实际的路径是：先在 .claude/ 里把东西跑通 → 再打包成 Plugin 分享，这比一上来就写插件舒服很多。

2.3 Plugin 包含什么？

插件不是只能装“命令”，它更像一个能力集合 ，把它理解成“一个团队最佳实践包”，包含如下内容。

2.3.1 Commands（自定义 slash commands）

详情参考：《Claude Code 完整指南（二）：终端命令全解析（收藏级）》

  • 放在 commands/ 下，每个文件一个命令
  • 写法是 Markdown + frontmatter（--- description: ... ---）
  • 适合：把常用提示词/流程固化成一条命令，比如 /team:review、/team:release-notes

2.3.2 Hooks（事件触发器）

详情参考：《Claude Code 完整指南（四）：Hooks（自动化事件触发）》

  • 放在 hooks/hooks.json（也可以写到 plugin.json 里）
  • 适合：让 Claude Code 在某些事件后自动跑动作（比如“写文件后自动跑格式化/测试”）

2.3.3 Agents（子代理 / 子角色）

详情参考：《Claude Code 完整指南（五）：Subagents（AI 角色工程化）》

  • 放在 agents/ 下
  • 适合：把“专精角色”做成可复用资源，比如“安全审计 agent”“SQL 优化 agent”

2.3.4 Skills（可复用 SOP）

详情参考：《Claude Code 完整指南（六）：Skills（可复用的标准操作流程）》

  • 放在 skills/ 下（每个 Skill 一个目录，里面有 SKILL.md）
  • 适合：把可重复的标准流程沉淀下来，让模型自动触发（例如：事故分诊、PR 检查、日志分析）

2.3.5 MCP servers （外部系统连接器）

详情参考：《Claude Code 完整指南（七）：MCP（让 AI 连接外部真实系统）》

  • 适合：把“连接 GitHub / Jira / Notion / Figma / 数据库”等能力，打包给团队一键安装

2.3.6 LSP servers（代码智能）

2.3.6.1 LSP 是什么?

前面没有提过 LSP 这个概念，我们可以把 LSP（Language Server Protocol）理解成一套“统一接口”，让编辑器 / 工具去问一个 语言服务进程，比如：

  • “这个符号定义在哪？”
  • “这个函数有几个引用？”
  • “我这段代码现在有哪些类型错误/诊断？”

VS Code 之所以能做“跳转定义、找引用、实时报错”，背后就是 LSP 这一套。Claude Code 里的 LSP 插件，本质上是在告诉 Claude Code：

  • “这门语言用哪个 language server（可执行程序）”
  • “怎么启动它、怎么跟它通信”

这样 Claude 在 改代码/读代码 的时候，就能拿到语义级信息（比纯文本搜索强很多），例如它能更可靠地定位定义、理解类型、发现编辑后引入的错误。

2.3.6.2 LSP 安装

LSP的安装步骤一般如下：

  1. 先去 /plugin 的 Discover 里找对应语言的 *-lsp 插件（官方 marketplace 里有很多常见语言）
  2. 安装后，打开 /plugin 的 Errors 看它要求的 binary 是什么
  3. 把这个 binary 装到系统（例如系统包管理器、语言自己的包管理器），保证终端里能直接运行它（也就是在 $PATH 里）

以下是几个典型 binary 名字：

  • Python：pyright-langserver
  • TypeScript：typescript-language-server
  • Rust：rust-analyzer
  • Go：gopls

3. Plugin 使用

3.1 Plugin 命令

在这里插入图片描述

在 Claude Code 里输入 /plugin，会打开插件管理器（一个带 Tab 的界面），常用的几个 Tab：

  • Discover：逛插件“应用商店”
  • Installed：你装了哪些、启用/禁用/卸载
  • Marketplaces：你添加了哪些“商店”
  • Errors：插件没生效时先看这里

如果没有 /plugin 命令，通常是版本太老，插件功能要求 Claude Code >= 1.0.33（跑一下 claude --version）。

3.2 Marketplace 是什么？

Marketplace 就是“插件目录/插件清单”。流程两步走：

  1. 先添加 marketplace（只是把商店加进来，还没安装任何插件）
  2. 再从这个 marketplace 安装某个插件

官方 marketplace（claude-plugins-official）默认可用，安装插件类似这样：

/plugin install plugin-name@claude-plugins-official
bash

3.3 添加官方 demo marketplace

Anthropic 在 anthropics/claude-code 仓库里维护了一个 demo marketplace（名字叫 claude-code-plugins），你可以手动加一下：

/plugin marketplace add anthropics/claude-code
bash

在这里插入图片描述

然后你就能在 Discover 里看到 demo 插件，点安装即可；也可以用命令行直接装，例如：

/plugin install commit-commands@anthropics-claude-code
bash

3.4 安装范围

插件安装有 scope（和 Claude Code 其它配置的 scope 是一套体系）：

  • user：装在 ~/.claude/settings.json，自己所有项目都能用（默认）
  • project：装在 .claude/settings.json，团队随仓库一起共享
  • local：装在 .claude/settings.local.json，只在本机生效，且一般会被 gitignore

你可以用 CLI 装，并指定 scope：

# 默认 user
claude plugin install formatter@my-marketplace

# 团队共享（project）
claude plugin install formatter@my-marketplace --scope project

# 仅本机（local）
claude plugin install formatter@my-marketplace --scope local
bash

4. 自定义 Plugin

4.1 目录结构

首先需要知道插件目录的结构，.claude-plugin/ 里只能放 plugin.json，其它目录都在插件根目录，标准结构如下：

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json
└── commands/
    └── hello.md
text

4.2 编写 Plugin

了解清楚后，可以写plugin.json，例如：my-first-plugin/.claude-plugin/plugin.json （官方 quickstart）：

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}
json

其中 name 很关键：它既是插件 ID，也是 slash command 的命名空间前缀。

接着 写一个命令 ，my-first-plugin/commands/hello.md 示例（官方 quickstart）：

---
description: Greet the user with a friendly message
---

# Hello Command

Greet the user warmly and ask how you can help them today.
markdown

开发/调试时，不需要把插件丢进 marketplace，可以直接用 --plugin-dir 加载本地目录：

claude --plugin-dir ./my-first-plugin
bash

然后在会话里运行：

/my-first-plugin:hello
bash

也可以同时加载多个本地插件（多写几次 --plugin-dir）。如果插件不加载、命令不出现，先做两件事：

  1. 打开 /plugin → 看 Errors tab
  2. 跑校验：claude plugin validate 或 /plugin validate

4.3 打包

如果你已经在 .claude/ 里有一套东西，迁移的目标其实很简单：搬家 + 加一个清单文件，迁移后最明显的变化（官方对照表）：

Standalone（.claude/） Plugin
只能在一个项目里用 可以通过 marketplace 共享
.claude/commands/ plugin-name/commands/
hooks 在 settings.json hooks 在 hooks/hooks.json
分享靠手动复制 用 /plugin install 安装

注意：如果 “原来的 .claude/ 文件还在”，又“插件也加载了”，可能会出现重复/覆盖，官方建议是迁移稳定后，把原来的 .claude/ 相关文件删掉，避免重复。

5. 文末

通过阅读本文，相信大家已经系统理解了 Claude Code 中 Plugins 的设计理念与工程价值：它并不是一组“零散功能的简单集合”，而是一种 将 commands / agents / hooks / Skills / MCP / LSP 等能力进行标准化封装与分发的工程机制。

1. 引言

在前面的博客，博主已经系统讲解了 Claude Code 的核心能力，有兴趣的同学可以先了解：

在这里插入图片描述

本文采用 5W1H（What / Why / Who / When / Where / How）来总结 Claude Code，方便大家从“是什么” 一步步走到 “怎么落地”，循序渐进建立整套心智模型。

2. 【WHAT】：Claude Code 是什么?

Claude Code 不是“聊天机器人”，更像一个 能在你电脑和代码仓库里做事的工程师，它的核心能力可以拆成 4 层：

一、核心执行层（能读、能改、能跑）

  • 读仓库：读文件、搜代码、理解目录结构与依赖。
  • 改仓库：跨文件写/改代码与配置（不是只给建议）。
  • 跑命令：跑测试/构建/脚本，拿到报错再继续修。

这三件事决定了它能做“真实交付”，而不是“纸上谈兵”。

二、会话与上下文层（让它“持续把一件事做完”）

  • 在 Claude Code 的一段持续对话可以理解为一个会话（Session）。
  • 会话会累积上下文（Context）：包括文件内容、你输入的信息、以及必要的运行结果。
  • 上下文太多会变贵、变慢、变容易跑偏，所以会话管理（恢复/回滚/压缩）很重要。

三、工程化编排层（把能力变成“流程”）

这一层是 Claude Code 和普通“代码补全/聊天 AI”最大的差异：

  • Hooks：把关键动作自动化，甚至做“门禁”（能阻断危险/低质量操作）。
  • Subagents：把工作拆给不同“岗位”，减少上下文污染与角色混乱。
  • Skills：把 SOP 固化成模板，让输出结构稳定、验收可重复。

四、 扩展与分发层（连接外部系统 + 让团队复用）

  • MCP：连接外部真实系统（GitHub、数据库、监控、知识库……）。
  • Plugins：把 commands/hooks/agents/skills/mcp/lsp 打包分发给团队/多个项目。

3. 【WHY】：为什么要用 Claude Code

一、 它解决的不是“会不会写代码”，而是“交付效率”

现实里最耗时的往往不是写某一行代码，而是：

  • 找到需要修改的真正位置（跨文件定位）
  • 改完之后跑测试、修报错、再跑、再修（闭环）
  • 做 Review、补文档、写变更说明、做风险/回滚说明（交付材料）

Claude Code 的优势是：它能在同一个工作台里把闭环跑完 。

二、 它能把“经验”变成默认流程（这是团队价值）

个人用 Claude Code 的收益是 “快”；团队用的收益是 “稳”：

  • Hooks 把“必须做的检查”固化（格式化/测试/危险拦截）。
  • Skills 把“必须交付的结构”固化（风险/验证/回滚/证据）。
  • Subagents 把“必须分工的角色”固化（测试官/审计官/文档工程师）。

三、为什么要理解数据流动与安全边界

因为它会读文件、会写文件、会跑命令，还会在本地落盘记录，在真实团队环境里，需要考虑：

  • 它会在本地留下些什么？会不会暴露项目路径/历史操作？
  • 哪些文件默认可读？敏感信息如何阻止被读入上下文？
  • 哪些操作必须先确认（写文件/跑命令/外部系统写入）？

4. 【WHO】：谁适合用、怎么分工

一、谁适合用？

  • 个人开发者：写代码 + 跑测试 + 快速复盘（效率提升明显）。
  • 团队技术负责人/Tech Lead：把流程固化，减少交付不一致。
  • 测试/运维/安全：通过角色化（Subagents）与模板化（Skills）参与研发闭环。
  • 非纯研发角色：通过 Output Styles 把主对话变成“产品/写作/排障”等身份。

二、团队里怎么分工（Subagents 的视角）

你可以把主对话当成“编排者/Tech Lead”，把子代理当成“岗位工种”：

  • security-auditor（安全审计官）：只读（Read/Grep），输出风险清单与修复建议。
  • test-writer（测试工程师）：Write + Bash，补测试并给出跑测证据。
  • code-reviewer（代码审查官）：只读为主，输出结构化 Review（必须修/建议/风险/验证点）。
  • doc-writer（文档工程师）：只写文档目录，产出说明与教程。

这种分工的好处是：

  • 避免“同一会话什么都干”导致的上下文污染
  • 避免“自己写自己审”的自我通过
  • 让每个岗位的工具权限更可控（审计类通常不应有 Write/Bash）

三、Skills 在分工里扮演什么角色

如果 Subagent 解决“谁来做”，Skill 解决“怎么做”：
把团队 SOP（发布检查、迁移可回滚、PR 必须有证据）固化成 Skill，挂在对应 Subagent 上，就能让交付稳定。

5. 【WHEN】：什么时候用哪些能力？

把能力按“时间点”组织，读者会更容易形成直觉：什么时候该用 Hook，什么时候该用 Skill，什么时候该用 Subagent。

一、会话开始（SessionStart）：先把“环境与规则”亮出来

适合做：

  • 环境体检（Node/Python 版本、依赖是否安装）
  • 打印项目约束/团队规范提示
  • 确认权限策略是否符合预期

二、做任何危险事之前（PreToolUse）：门禁点

适合做：

  • 拦截危险 Bash（rm -rf、git push --force 等）
  • 敏感信息检测（避免把密钥读进上下文/写进仓库）
  • 参数校验与审计记录

三、写/改文件之后（PostToolUse）：自动化点

适合做：

  • 自动格式化（失败不阻断但要提示）
  • 自动跑最小测试（尽量给证据）
  • 自动生成变更摘要（方便写 PR）

四、准备停止之前（Stop/SubagentStop）：收尾验收点

适合做：

  • “停下前质量门禁”：有没有跑测试？有没有未解决报错？有没有未提交改动？
  • 对子任务做验收：例如子代理说“测试写完了”，那就要求给测试命令与结果

一句话总结 WHEN： Hooks 管“什么时候发生”，Skills 管“怎么做才算完成”，Subagents 管“谁来负责”。

6. 【WHERE】：它在本地/项目里“放在哪、存在哪、接在哪”

这一部分解决“它到底在哪些地方动了我的东西”的问题（也是最容易让新人困惑的点）。

一、存在哪：用户级目录 ~/.claude/

你可以把这里理解成“跨项目的个人工作台数据”，常见包含：

  • 项目会话记录（按项目分目录）
  • 全局命令索引 history.jsonl（可能包含项目路径信息）
  • todos（任务列表 JSON）
  • debug/shell-snapshots/ide 等辅助目录

结论：这就是为什么共享账号/共享环境要谨慎。

二、放在哪：项目级目录 {project}/.claude/

这是团队最该沉淀规范的地方（因为它能跟仓库一起走）：

  • settings.json：团队共享配置（建议提交 Git）
  • settings.local.json：个人覆盖（不要提交）
  • CLAUDE.md：项目背景/规范/常用命令（强烈建议有）
  • commands/：自定义斜杠命令（把流程做成入口）
  • .mcp.json：项目 MCP 配置（团队共享外部连接器）

三、接在哪：入口与集成（Where you use）

Claude Code 的使用入口并不只有 CLI：

  • IDE（VS Code / JetBrains）
  • 桌面版/Web
  • CI/CD（GitHub Actions/GitLab CI）
  • IM（Slack 等）

但无论入口是什么，底层都绕不开：权限、配置、上下文、工具调用。

7. 【HOW】：怎么从 0 到工程化落地

这一章按“循序渐进”的方式给出落地路线：先能用，再好用，再团队化，再平台化。

Step1：先把“边界”画出来（权限最小化）

  • 读仓库默认允许（否则它没法理解）
  • 敏感文件明确 deny（.env、secrets/、证书、私钥等）
  • 写文件/跑命令默认 ask（尤其是前期）

Step2：让它“看懂你的项目”（CLAUDE.md）

目标：减少你重复解释、减少上下文浪费、减少误改，建议写进 CLAUDE.md 的最小集合：

  • 项目是什么（业务一句话）
  • 目录结构（核心模块在哪）
  • 如何运行/测试/构建（命令）
  • 代码规范与约束（比如必须跑哪些测试、提交规范）

Step3：把日常需求变成可控闭环（CLI + 会话管理）

目标：把“说一句话”变成“交付闭环”：

  • 让 Claude 做改动（限定范围与目标）
  • 让 Claude 跑测试/构建拿证据
  • 根据报错继续修
  • 导出摘要/变更说明（用于 PR）

关键习惯：

  • 会话变长要压缩（避免越聊越飘）
  • 走错路要回滚（不要硬聊到崩）

Step4：把“必须做的事”自动化（Hooks）

目标：把返工成本最高的环节系统化：

  • PreToolUse：危险拦截（阻断）
  • PostToolUse：自动格式化 + 最小测试（不阻断但要提示）
  • Stop：停下前质量门禁（强提醒或阻断）

Step5：把“角色”工程化（Subagents）

目标：让一个 Claude 像一个团队一样工作：

  • 业务实现（主对话编排）
  • 测试由 test-writer 负责（给证据）
  • 安全由 security-auditor 负责（只读）
  • 文档由 doc-writer 负责（写文档目录）

Step6：把“流程”标准化（Skills）

目标：让输出稳定、可验收、可复制，推荐你优先沉淀的 4 类 Skill：

  • PR/变更总结（风险/验证/回滚/影响面）
  • 结构化 Code Review（必须修/建议/风险/验证点）
  • 数据库迁移（强制可回滚）
  • 文档生成（API/运行手册/排障手册）

Step7：连接外部系统（MCP）

目标：从“改本地仓库”扩展到“操作真实系统”：

  • 查外部数据作为上下文（Resources）
  • 执行动作（Tools）
  • 固化模板（Prompts）

建议：优先 HTTP 形态（便于统一权限与审计）。

Step8：把能力变成团队资产（Plugins）

目标：跨项目复用、版本化管理、统一升级，把你在 .claude/ 里跑通的这些东西打包

  • commands + hooks + agents + skills + mcp + lsp

8. 官方文档导航

前面九章的内容基本把 Claude Code 核心的内容覆盖了，可能会有缺漏的知识点，这里整理官方的文档，按以下三层来整理：

  1. 怎么用起来：安装/快速上手/各种入口（IDE/桌面/Web/CI/IM）
  2. 怎么工程化：CLI 参考、常用工作流、Hooks/Subagents/Skills、Output styles
  3. 怎么在团队与企业里安全运行：安全/数据使用/合规、网络与 IAM、成本与监控、插件生态与外部系统（MCP）

入门与安装：

使用入口（IDE/桌面/Web）：

CLI 与日常工作流（查命令/查用法/查最佳实践）：

自动化（Hooks）：

角色与 SOP（Subagents / Skills）：

连接外部系统（MCP）：

插件生态（Plugins）：

集成（CI/IM/第三方）：

安全、合规与网络（团队/企业最常查）：

成本、用量与分析（想控预算/看趋势）：

企业/云平台接入（Bedrock / Vertex / Foundry）：

运行形态与容器（自动化/远程/容器化）：

排障：

9. 总结

通过阅读本文，相信大家已经从 5W1H（What / Why / Who / When / Where / How） 的完整视角，系统建立了对 Claude Code 的认知框架：它并不是一个“更强的聊天式写代码工具”，也不是单点能力的堆叠，而是一套 将 AI 纳入真实工程流程的执行型系统。

  • Hooks 负责“什么时候必须发生”；
  • Skills 定义“做到什么才算完成”；
  • Subagents 明确“谁对结果负责”；
  • MCP 与 Plugins 则让能力走出本地，成为团队级、平台级资产。

 

posted @ 2026-04-23 20:20  CharyGao  阅读(33)  评论(0)    收藏  举报