总览
- sub-agent：配置在
.claude/.agent下 - Skills 的 渐进式披露架构
- command：显式、可复用、可审计、通过斜杠命令固定触发的操作指令集，是相对固化的标准流程。
- Hooks 适合 自动化检查 ——格式化、安全检查、日志记录等。
Claude 命令：
| 命令 | 说明 | 备注 |
|---|---|---|
| claude | 启动交互式对话模式（REPL） | 进入持续会话，支持多轮上下文 |
| claude “任务描述” | 执行单次任务并退出 | 适合脚本调用或快速生成，如 claude “为 README.md 生成简洁的使用说明” |
| claude -p “问题” | 快速提问 → 获取答案 → 自动退出 | -p = prompt-only，无历史上下文，轻量查询（类似 curl 式用法） |
| claude -c | 继续最近一次未完成的对话 | 依赖本地会话缓存（通常保存在 ~/.claude/session/ 或 .claude/.agent 中） |
| help | 显示内置帮助文档 | 在交互模式下输入即可 |
| Ctrl+C 或 exit | 退出当前交互会话 | 安全退出，不中断后台 agent |
Plugins：打包容器
my-team-plugin/
├── commands/ # 斜杠命令
│ └── review.md
├── skills/ # 技能
│ └── security-check/
│ └── SKILL.md
├── agents/ # 子代理
│ └── test-runner.md
├── hooks/ # 钩子
│ └── pre-edit.sh
└── plugin.json # 插件配置
使用场景和对应方案
| 场景 | 推荐方案 | 原因 |
|---|---|---|
| 团队统一 commit 格式 | Commands | 标准化操作，手动触发 |
| 代码安全审查 | Skills | 自动识别，专业能力 |
| 跑 500 行测试输出 | SubAgents | 隔离噪声，只返结论 |
| 每次保存自动格式化 | Hooks | 事件驱动，自动执行 |
| 连接内部 API | MCP | 外部工具连接 |
| PR 自动审查 | Headless + SubAgents | CI/CD 集成 |
| 构建复杂审批流程 | Agent SDK | 完全编程控制 |
memory
五层记忆架构
| 层级 | 名称 | 路径位置 | 作用范围 | 说明 |
|---|---|---|---|---|
| 0 | 企业策略 | /etc/claude-code/CLAUDE.md | 全组织全局 | 最高优先级策略，强制生效（如合规要求、安全基线） |
| 1 | 用户级 | ~/.claude/CLAUDE.md | 当前用户所有项目 | 用户个性化配置（如默认模型、偏好语言、常用命令别名） |
| 2 | 项目级 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 当前 Git 仓库 | 项目通用上下文（技术栈、架构约定、团队协作规范） |
| 3 | 项目规则 | .claude/rules/*.md | 项目内子目录 | 按模块/功能/环境细分的细粒度规则（如 rules/backend/, rules/api/） |
| 4 | 本地级 | ./CLAUDE.local.md | 当前工作目录（不提交） | 临时、敏感、本地调试用配置（如 API 密钥占位符、本地路径、未提交实验逻辑） |
注：rules 支持条件作用域
---
paths:
- "src/**/*.test.ts"
- "tests/**/*.ts"
---编写原则
- 保持精简
- 具体优于泛泛
- 关键三问题 WHY / WHAT / HOW：为什么，做什么，怎么做
- 渐进式披露：不要把一切都塞进 CLAUDE.md，采用文件路径引用方式按需加载
使用场景
- 创建新项目时，依次创建项目级、项目规则和本地级
- 优化一个 CLAUDE.md 文件时，技术栈、项目目录和编码规范保留，API文档、数据库表结构和部署流程拆分独立文件按路径引用，前端、后端、测试等详细规范可以使用 rules 的条件规则
- 管理命令
/memory
/memory edit # 编辑项目级 CLAUDE.md
/memory edit user # 编辑用户级记忆
/memory edit local # 编辑本地级记忆
sub-agents
根本原因：创造一个上下文独立的窗口，避免污染。解决的并不是“模型更聪明”，而是工程系统如何避免上下文被执行细节淹没。
核心价值：
- 隔离，解决的是上下文污染问题
- 约束，解决的是行为不可控问题
- 复用，解决的是经验无法沉淀的问题
内置子代理
- Explore 子代理：找文件，使用Read, Grep, Glob
- Plan 子代理：收集上下文、梳理依赖、生成实施路径
- General-purpose 子代理：能探索、能修改、能推进
适用子代理的情景
- 高噪声输出的任务
- 角色边界必须非常明确的任务
- 可以并行展开的研究型任务
- 可以拆成清晰阶段的流水线式任务
关键约束：子代理不能生成子代理
子代理配置文件
使用 Markdown + YAML frontmatter 格式：
---
name: code-reviewer
description: Review code for security issues and best practices. Use after code changes.
tools: Read, Grep, Glob
model: sonnet
skills:
- chain-knowledge # 链路拓扑和 SLA 约束
- recent-incidents # 近期事故记录
---
你是一个代码审查专家。
当被调用时：
1. 首先理解代码变更的范围
2. 检查安全问题
3. 检查代码规范
4. 提供改进建议
输出格式：
## 审查结果
- 安全问题：[列表]
- 规范问题：[列表]
- 建议：[列表]frontmatter 字段详解
| 字段 | 必填 | 说明 | 示例 |
|---|---|---|---|
| name | 是 | 唯一标识符，使用小写字母和连字符 | code–reviewer |
| description | 是 | 最重要的字段！ Claude 据此决定何时自动委派任务 | Review code for security issues. Use proactively after code changes. |
| tools | 否 | 工具白名单（逗号分隔）。省略则继承主对话的全部工具 | Read, Grep, Glob |
| disallowedTools | 否 | 工具黑名单，从继承列表中排除指定工具 | Write, Edit |
| model | 否 | 模型选择。省略则默认为 inherit | haiku / sonnet / opus / inherit |
| permissionMode | 否 | 权限模式，控制子代理如何处理权限弹窗 | default /plan/bypassPermissions 等 |
| skills | 否 | 启动时预加载的 Skill 列表，注入为上下文 | [api-conventions, error-handling] |
| hooks | 否 | 子代理专属的生命周期 Hook | 见后续 Hook 章节 |
子代理层级
| 位置 | 作用域 | 优先级 | 适用场景 |
|---|---|---|---|
| —agents CLI 参数 | 仅当次会话 | 1（最高） | 临时测试、CI/CD 自动化 |
| .claude/agents/ | 当前项目 | 2 | 项目特有的子代理，提交到 git 团队共享 |
| ~/.claude/agents/ | 所有项目 | 3 | 个人通用子代理 |
| Plugin 的 agents/ 目录 | 启用了该 Plugin 的项目 | 4（最低） | 通过插件分发的子代理 |
multi-agents
何时使用 multi-agents：
- 上下文窗口满载
- 多 agent 独立维护
几种设计模型：
- Sub-Agents（子代理委派 / 集中式编排），独立的上下文窗口
- Skills（技能 / 渐进式能力加载），一个skill看作一个agent，串行运行
- Handoffs（交接 / 状态驱动的 Agent 切换）通过 Prompt + 状态约束 + 工程结构模拟出来的
- Router（路由器 / 并行分发与合成）
真实工程中往往从单agent开始
skills
得益于其渐进式加载的能力，使得可以作为一个能力包，在预定的提示词 description 触发器命中时，被加载到上下文中。
为了丰富它的功能，可以有description、content、templates、allowed-tools、hooks
在Claude发布的 Agent Skills 公用仓库中，集成了大量可复用的能力。Coze也推出了技能商店，为Coze智能体生态提供即插即用的能力组件。
触发机制有两个：命令式触发和语义触发
设有 disable-model-invocation: true 的 Skill，其 description 不会加载到上下文 ——Claude 完全看不到它，只有用户 /name 才能触发。
skill 设计规范
SKILL.md ← 导航页：概述 + 引用（< 500 行）
├── reference.md ← 详情页：详细 API 文档
├── examples.md ← 详情页：使用示例
└── scripts/validate.sh ← 工具：可执行脚本