Claude Code自定义命令与Subagent开发完全实战

graph TD
    A[.claude 目录体系] --> B[commands/ 自定义命令]
    A --> C[agents/ 自定义Subagent]
    A --> D[rules/ 模块化规则]
    A --> E[skills/ 技能包]

    B --> B1[用户主动输入 /command-name]
    B --> B2[Markdown纯文本]
    B --> B3[无独立上下文窗口]

    C --> C1[Claude自动委托或 @提及]
    C --> C2[YAML frontmatter + Markdown]
    C --> C3[独立上下文窗口]

    D --> D1[自动加载到系统提示词]
    D --> D2[拆分大CLAUDE.md为小模块]

    E --> E1[条件触发式工作流]
    E --> E2[含SKILL.md的目录结构]

    style B fill:#4A90D9,color:white
    style C fill:#E67E22,color:white
    style D fill:#27AE60,color:white
    style E fill:#8E44AD,color:white

your-project/
├── CLAUDE.md                      # 团队指令（提交到Git）
├── CLAUDE.local.md                # 个人覆盖（gitignore）
└── .claude/
    ├── settings.json              # 权限+配置（提交到Git）
    ├── settings.local.json        # 个人权限覆盖（gitignore）
    ├── .mcp.json                  # MCP服务器配置
    ├── rules/                     # 模块化规则文件
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── commands/                  # 自定义Slash命令
    │   ├── review.md              # → /project:review
    │   ├── deploy.md              # → /project:deploy
    │   └── gsd/                   # 子目录组织
    │       ├── plan.md            # → /project:gsd:plan
    │       └── execute.md         # → /project:gsd:execute
    ├── skills/                    # 自动触发式技能
    │   └── deploy/
    │       └── SKILL.md
    ├── agents/                    # 自定义Subagent定义
    │   ├── code-reviewer.md
    │   ├── security-auditor.md
    │   └── research/
    │       └── docs-explorer.md
    └── hooks/                     # 事件驱动自动化脚本
        └── validate-bash.sh

~/.claude/                          # 全局个人配置（不提交）
├── CLAUDE.md                      # 全局指令
├── settings.json                  # 全局权限
├── commands/                      # 个人命令 → /user:xxx
│   ├── reflect.md
│   └── status.md
├── skills/                        # 个人技能
├── agents/                        # 个人Subagent
└── projects/                      # 会话历史+自动记忆
    └── <project-hash>/
        └── memory/
            └── MEMORY.md

# .gitignore
CLAUDE.local.md
.claude/settings.local.json
.claude/agent-memory-local/

# 全局个人命令（所有项目可用）
mkdir -p ~/.claude/commands

# 项目级命令（仅当前项目可用）
mkdir -p .claude/commands

# 反思最近的工作

审查本会话中的近期工作，提取可操作的教训。

## 步骤
1. 运行 `git log -5 --oneline --stat` 查看最近的提交
2. 如有需要，运行 `git diff HEAD~1` 查看最新变更
3. 识别：错误假设、过度工程、遗漏的边界情况、
   失败的方法、有用的模式
4. 用 `save_observation` 保存每条发现，标题加"LESSON:"前缀
5. 用2-3句话总结捕获的内容

/reflect

# 安全审计

对项目代码进行安全审查，检查OWASP Top 10相关漏洞。

## 检查清单
- [ ] SQL注入：搜索所有数据库查询，检查参数化使用
- [ ] XSS：搜索所有用户输入渲染点，检查转义处理
- [ ] 命令注入：搜索所有exec/spawn调用，检查输入验证
- [ ] 敏感数据泄露：搜索硬编码的密钥、token、密码
- [ ] 不安全的依赖：运行 `npm audit` 或 `pip audit`
- [ ] CORS配置：检查跨域策略是否过于宽松
- [ ] 认证缺陷：检查JWT实现、session管理

## 执行步骤
1. 使用 Grep 工具搜索 `eval(`、`innerHTML`、`exec(`、`password`、
   `secret`、`api_key` 等关键词
2. 检查 .env 文件是否在 .gitignore 中
3. 运行依赖审计命令
4. 检查认证中间件实现
5. 按严重程度分类输出报告

## 输出格式
按以下结构输出：
- 🔴 严重：可直接被利用的漏洞
- 🟡 警告：潜在风险，需要评估
- 🟢 建议：安全最佳实践建议

# 初始化新项目

深度收集上下文后初始化项目，而非简单地创建目录结构。

## 步骤
1. 研究现有代码库，映射依赖关系
2. 识别集成点和技术约束
3. 在开始实现前，向用户提出澄清问题
4. 创建 PROJECT.md 作为项目唯一真相来源
5. 包含：架构决策、技术栈、模块划分、里程碑

## 关键原则
- 不做假设，先问再做
- 理解现有系统再规划新功能
- 记录每一个架构决策的理由

# 系统化调试

用科学方法替代随机试错。

## 调试流程
1. **观察**：精确描述异常行为，收集错误日志
2. **假设**：基于证据提出1-3个可能原因
3. **测试**：设计最小实验验证每个假设
4. **结论**：记录哪些假设被证实/推翻
5. **修复**：基于验证结果实施最小化修复

## 输出要求
- 每次只测试一个变量
- 记录每个实验的输入、预期、实际结果
- 如果3轮假设未解决，暂停并重新审视问题定义

graph LR
    subgraph 主会话
        A[用户指令] --> B[Claude主线程]
    end

    B -->|委托| C[Subagent A<br/>代码审查]
    B -->|委托| D[Subagent B<br/>文档研究]
    B -->|委托| E[Subagent C<br/>测试运行]

    C -->|返回摘要| B
    D -->|返回摘要| B
    E -->|返回摘要| B

    style C fill:#E67E22,color:white
    style D fill:#3498DB,color:white
    style E fill:#2ECC71,color:white

/agents

一个代码改进Agent，扫描文件并建议可读性、
性能和最佳实践方面的改进。它应该解释每个
问题，展示当前代码，并提供改进版本。

用code-improver Agent来建议改进这个项目

---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use after code changes or before commits.
tools: [Read, Glob, Grep, Bash]
disallowedTools: [Edit, Write]
model: sonnet
permissionMode: plan
memory: project
color: "#E67E22"
---

你是一位高级代码审查专家。分析代码时遵循以下原则：

## 审查维度

### 代码质量
- 命名是否清晰表达意图
- 函数是否保持单一职责（<30行）
- 嵌套层级是否超过3层
- 是否存在重复代码可以抽取

### 安全性
- 输入验证是否充分
- 是否存在注入风险
- 敏感数据处理是否安全
- 认证授权是否正确实现

### 可维护性
- 错误处理是否完善
- 日志是否足够但不冗余
- 类型定义是否精确
- 依赖关系是否合理

## 输出格式

对每个发现的问题：
1. **位置**：文件路径:行号
2. **类别**：质量/安全/性能/可维护性
3. **严重程度**：🔴严重 🟡警告 🟢建议
4. **当前代码**：问题代码片段
5. **改进建议**：修改后的代码和理由

最后给出总体评分（1-10）和最重要的3个改进建议。

graph TD
    A[任务类型判断] --> B{需要深度推理？}
    B -->|是| C[opus]
    B -->|否| D{需要代码修改？}
    D -->|是| E[sonnet]
    D -->|否| F{响应速度关键？}
    F -->|是| G[haiku]
    F -->|否| E

    H[示例场景] --> I[代码审查 → sonnet]
    H --> J[快速搜索 → haiku]
    H --> K[架构设计 → opus]
    H --> L[文档研究 → haiku]
    H --> M[安全审计 → sonnet]

my-project/
├── CLAUDE.md
├── .claude/
│   ├── commands/
│   │   ├── review.md           # 代码审查命令
│   │   ├── security-check.md   # 安全检查命令
│   │   ├── test-coverage.md    # 测试覆盖率命令
│   │   └── deploy/
│   │       ├── staging.md      # 部署到staging
│   │       └── production.md   # 部署到production
│   ├── agents/
│   │   ├── code-reviewer.md    # 代码审查Agent
│   │   ├── security-auditor.md # 安全审计Agent
│   │   └── test-runner.md      # 测试运行Agent
│   └── rules/
│       ├── code-style.md       # 代码风格规则
│       └── testing.md          # 测试规则

# My Project

## 常用命令
- `npm run dev` — 启动开发服务器 (端口3000)
- `npm test` — 运行测试套件 (Vitest)
- `npm run lint` — 代码检查 (ESLint + Prettier)
- `npm run build` — TypeScript编译

## 架构
- Next.js 15 App Router + TypeScript
- 数据层：Prisma ORM + PostgreSQL
- API路由在 `src/app/api/`
- 组件在 `src/components/`
- 测试镜像 `src/` 结构在 `tests/`

## 约定
- 所有API响应格式：`{ data, error, meta }`
- 组件使用函数式 + hooks
- 禁止使用 `any` 类型
- 提交前必须通过lint和测试

# 代码审查

对当前Git暂存区的变更进行完整审查。

## 步骤
1. 运行 `git diff --cached` 查看暂存变更
2. 运行 `git diff` 查看未暂存变更
3. 运行 `npm run lint` 检查代码规范
4. 运行 `npm test` 执行相关测试
5. 基于以下维度评估变更：
   - 代码质量和可读性
   - 潜在Bug和边界情况
   - 安全漏洞
   - 性能影响
   - 测试覆盖是否充分

## 输出格式
- 🟢 可以合并
- 🟡 需要小幅修改（列出具体建议）
- 🔴 需要重大修改（列出阻塞问题）

如果需要深度审查，建议使用 @code-reviewer Agent。

---
name: security-auditor
description: Scans code for security vulnerabilities following OWASP Top 10. Use proactively before releases and after auth-related changes.
tools: [Read, Glob, Grep, Bash]
disallowedTools: [Edit, Write]
model: sonnet
permissionMode: plan
memory: project
color: "#E74C3C"
---

你是一位应用安全专家。对代码进行系统化安全审计。

## 扫描范围

### 注入攻击
- 搜索所有数据库查询，检查参数化使用
- 搜索 `eval(`、`exec(`、`spawn(`、`child_process`
- 检查用户输入是否直接拼接到命令中

### 身份认证
- JWT实现是否正确（算法、密钥管理、过期处理）
- Session管理是否安全
- 密码存储是否使用bcrypt/argon2

### 敏感数据
- 搜索硬编码的密钥：`password`、`secret`、`api_key`、`token`
- 检查 `.env` 文件是否在 `.gitignore` 中
- 验证HTTPS在传输层的强制使用

### CORS与CSRF
- 跨域策略是否限制来源
- CSRF Token是否正确实现

### 依赖安全
- 运行 `npm audit`（Node.js）或 `pip audit`（Python）
- 检查是否使用了已知有漏洞的版本

## 输出格式

---
name: test-runner
description: Runs tests, analyzes failures, and suggests fixes. Use when tests fail or before committing changes.
tools: [Read, Glob, Grep, Bash]
disallowedTools: [Edit, Write]
model: haiku
maxTurns: 15
color: "#2ECC71"
---

你是一位测试工程师。专注于运行测试和分析失败原因。

## 工作流程
1. 识别最近的代码变更（git diff）
2. 确定需要运行的测试范围
3. 执行相关测试套件
4. 如果测试通过，报告成功
5. 如果测试失败：
   a. 读取失败的测试文件
   b. 读取被测试的源文件
   c. 分析失败原因（断言错误、异常、超时）
   d. 建议具体的修复方案

## 输出格式
- 测试结果摘要：通过/失败/跳过数量
- 失败测试的根因分析
- 建议的修复步骤（按优先级排列）

sequenceDiagram
    participant U as 开发者
    participant CC as Claude Code
    participant CR as code-reviewer
    participant SA as security-auditor
    participant TR as test-runner

    U->>CC: /review
    CC->>CC: 读取 .claude/commands/review.md
    CC->>TR: 委托运行测试
    TR-->>CC: 测试通过，覆盖率92%
    CC->>CR: 委托代码审查
    CR-->>CC: 发现2个警告，3个建议
    CC->>SA: 委托安全审计
    SA-->>CC: 无严重问题，1个建议
    CC-->>U: 综合报告：🟡 需要小幅修改

    Note over U,CC: 开发者也可以直接@指定Agent
    U->>CC: @security-auditor 检查新的认证模块
    CC->>SA: 直接委托
    SA-->>CC: 审计结果
    CC-->>U: 安全审计报告

# 代码风格规则

## TypeScript
- 严格模式：always
- 优先使用 `interface` 而非 `type` 定义对象
- 使用 `unknown` 而非 `any` 处理未知类型
- 枚举使用 `const enum` 或字符串联合类型

## React
- 函数式组件，禁止class组件
- Props使用interface定义
- 使用 `useCallback` 包装事件处理器
- 自定义Hook以 `use` 开头

## 命名约定
- 文件：kebab-case（`user-profile.tsx`）
- 组件：PascalCase（`UserProfile`）
- 函数/变量：camelCase
- 常量：UPPER_SNAKE_CASE
- CSS类：使用CSS Modules或Tailwind

# 测试规则

## Vitest配置
- 测试文件与源文件同目录，命名为 `*.test.ts`
- 使用 `describe`/`it` 组织测试
- Mock外部依赖，不Mock内部模块

## 覆盖率要求
- 核心业务逻辑：≥90%
- API路由：≥80%
- UI组件：≥60%（侧重交互逻辑）

## 测试结构
遵循 AAA 模式：
1. Arrange：设置测试数据和前置条件
2. Act：执行被测试的操作
3. Assert：验证结果符合预期

<!-- .claude/commands/full-review.md -->
# 全面审查

执行完整的代码审查流程。

## 步骤
1. 运行 `npm run lint` 检查代码规范
2. 如果lint通过，使用 @test-runner 运行测试
3. 如果测试通过，使用 @code-reviewer 审查代码质量
4. 使用 @security-auditor 进行安全扫描
5. 汇总所有Agent的报告，给出综合评分

## 注意
- 如果任何步骤失败，报告失败原因并建议修复
- 不要在主线程中做大量文件搜索，委托给Agent

---
name: parallel-research
description: Research multiple topics in parallel using background agents.
background: true
model: haiku
tools: [Read, Glob, Grep, Bash]
---

研究以下主题并返回摘要：
- 项目使用的框架版本和已知问题
- 类似项目中的常见模式
- 性能优化的最佳实践

---
name: refactor-worker
description: Performs code refactoring in an isolated worktree to avoid conflicts.
isolation: worktree
model: sonnet
tools: [Read, Edit, Write, Glob, Grep, Bash]
permissionMode: auto
---

# ❌ 弱描述——Claude不知道何时使用
description: A code review agent.

# ✅ 强描述——触发条件明确
description: Reviews code for quality, security, and best practices. Use proactively after code changes or before commits.

tools: [Read, Glob, Grep]        # 只允许这三个
disallowedTools: [Edit, Write, Bash]  # 明确禁止写入

# 提交到Git的文件（团队共享）
git add .claude/commands/
git add .claude/agents/
git add .claude/rules/
git add .claude/settings.json
git add CLAUDE.md

# 不提交的文件（个人配置）
echo "CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore
echo ".claude/agent-memory-local/" >> .gitignore

## Claude Code配置

本项目包含以下自定义配置：

### 命令
- `/review` — 审查暂存区变更
- `/deploy:staging` — 部署到staging环境

### Subagents
- `code-reviewer` — 代码质量和最佳实践审查
- `security-auditor` — OWASP安全审计
- `test-runner` — 测试执行和失败分析

### 使用建议
提交前运行 `/review` 获取完整审查报告。

graph TD
    A[任务到达] --> B{需要修改代码？}
    B -->|否，只读| C{复杂分析？}
    B -->|是| D{高难度重构？}
    C -->|否| E[haiku 成本$0.25/M token]
    C -->|是| F[sonnet 成本$3/M token]
    D -->|否| F
    D -->|是| G[opus 成本$15/M token]

    style E fill:#2ECC71,color:white
    style F fill:#F39C12,color:white
    style G fill:#E74C3C,color:white