agents-subagents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Agents

Claude 编码代理

Create and maintain Claude Code agents/subagents with predictable behavior, least-privilege tools, and explicit delegation contracts.

创建并维护行为可预测、采用最小权限工具且具备明确委托契约的Claude编码代理/子代理。

Quick Start

快速开始

Create an agent file at
```
.claude/agents/<agent-name>.md
```
(kebab-case filename).

Add YAML frontmatter (required:

name

description

; optional:

tools

model

permissionMode

skills

hooks

Write the agent prompt: responsibilities, workflow, and an output contract.
Minimize tools: start read-only, then add only what the agent truly needs.
Test on a real task and iterate.

Minimal template:

markdown

---
name: sql-optimizer
description: Optimize SQL queries, explain tradeoffs, and propose safe indexes
tools: Read, Grep, Glob
model: sonnet
---

在
```
.claude/agents/<agent-name>.md
```
路径下创建代理文件（使用kebab-case文件名）。
添加YAML前置元数据（必填项：
```
name
```
、
```
description
```
；可选项：
```
tools
```
、
```
model
```
、
```
permissionMode
```
、
```
skills
```
、
```
hooks
```
）。
编写代理提示词：职责、工作流和输出契约。
最小化工具使用：从只读权限开始，仅添加代理真正需要的工具。
在真实任务上测试并迭代。

最简模板：

markdown

---
name: sql-optimizer
description: Optimize SQL queries, explain tradeoffs, and propose safe indexes
tools: Read, Grep, Glob
model: sonnet
---

SQL Optimizer

Responsibilities

Diagnose bottlenecks using query shape and plans when available
Propose optimizations with risks and expected impact

Diagnose bottlenecks using query shape and plans when available
Propose optimizations with risks and expected impact

Workflow

Identify the slow path and data volume assumptions
Propose changes (query rewrite, indexes, stats) with rationale
Provide a verification plan

Identify the slow path and data volume assumptions
Propose changes (query rewrite, indexes, stats) with rationale
Provide a verification plan

Output Contract

Summary (1–3 bullets)
Recommendations (ordered)
Verification (commands/tests to run)

undefined

Summary (1–3 bullets)
Recommendations (ordered)
Verification (commands/tests to run)

undefined

Workflow (2026)

2026年工作流

Define the agent’s scope and success criteria.
Choose a model based on risk, latency, and cost (default to
```
sonnet
```
for most work).
Choose tools via least privilege; avoid granting
```
Edit
```
/
```
Write
```
unless required.
If delegating with
```
Task
```
, define a handoff contract (inputs, constraints, output format).
Add safety rails for destructive actions and secrets.
Add a verification step (checklist, tests, or a dedicated verifier agent).

定义代理的范围和成功标准。
根据风险、延迟和成本选择模型（大多数工作默认使用
```
sonnet
```
）。
通过最小权限原则选择工具；除非必要，否则避免授予
```
Edit
```
/
```
Write
```
权限。
如果使用
```
Task
```
进行委托，定义交接契约（输入、约束、输出格式）。
为破坏性操作和敏感信息添加安全防护。
添加验证步骤（检查清单、测试或专用验证代理）。

Frontmatter Fields (Summary)

前置元数据字段（摘要）

```
name
```
(REQUIRED): kebab-case; match filename (without
```
.md
```
).
```
description
```
(REQUIRED): state when to invoke + what it does; include keywords users will say.
```
tools
```
(OPTIONAL): explicit allow-list; prefer small, purpose-built sets.
```
model
```
(OPTIONAL):
```
haiku
```
for fast checks,
```
sonnet
```
for most tasks,
```
opus
```
for high-stakes reasoning,
```
inherit
```
to match parent.
```
permissionMode
```
(OPTIONAL): prefer defaults; change only with a clear reason and understand the tradeoffs.
```
skills
```
(OPTIONAL): preload skill packs for domain expertise; keep the list minimal.
```
hooks
```
(OPTIONAL): automate guardrails; prefer using the hooks skill for patterns and safety.

For full tool semantics and permission patterns, use

references/agent-tools.md

. For orchestration and anti-patterns, use

references/agent-patterns.md

```
name
```
（必填）：采用kebab-case格式；与文件名（不含
```
.md
```
）匹配。
```
description
```
（必填）：说明调用时机和功能；包含用户会使用的关键词。
```
tools
```
（可选）：明确的允许列表；优先选择小型、专用的工具集。
```
model
```
（可选）：
```
haiku
```
用于快速检查，
```
sonnet
```
用于大多数任务，
```
opus
```
用于高风险推理，
```
inherit
```
用于继承父代理模型。
```
permissionMode
```
（可选）：优先使用默认值；仅在有明确理由且了解权衡利弊时才修改。
```
skills
```
（可选）：预加载技能包以获取领域专业知识；保持列表精简。
```
hooks
```
（可选）：自动添加防护措施；优先使用hooks技能来实现模式和安全相关功能。

如需了解完整的工具语义和权限模式，请查看

references/agent-tools.md

。如需了解编排和反模式，请查看

references/agent-patterns.md

。

2026 Best Practices (Domain Expertise)

领域专业知识最佳实践

Use small, specialized agents; avoid “god agents”.
Keep agent prompts short; put repo conventions in
```
CLAUDE.md
```
/project memory and domain knowledge in skills.
Budget context: pass file paths, minimal snippets, and constraints; avoid dumping long logs/code.
Use explicit handoffs for subagents: “Goal / Constraints / Inputs / Output Contract”.
Add a verifier step for risky changes (security, migrations, infra, auth).
Treat CLI fields/features as moving; verify against official docs in
```
data/sources.json
```
.

使用小型、专用代理；避免“全能代理”。
保持代理提示词简短；将仓库约定放在
```
CLAUDE.md
```
/项目记忆中，领域知识放在技能里。
预算上下文：传递文件路径、最小化代码片段和约束；避免粘贴冗长的日志/代码。
为子代理使用明确的交接：“目标 / 约束 / 输入 / 输出契约”。
为高风险变更（安全、迁移、基础设施、认证）添加验证步骤。
将CLI字段/功能视为动态变化的；对照
```
data/sources.json
```
中的官方文档进行验证。

Validation Checklist

验证检查清单

Frontmatter:
```
name
```
matches filename;
```
description
```
is single-line and trigger-oriented; tools are minimal; model fits risk.
Prompt: responsibilities are concrete; workflow is actionable; output contract is explicit.
Delegation: subagent briefs are specific and bounded; orchestrator verifies integration.
Safety: confirm destructive ops; avoid secrets/PII; follow repository policies.

前置元数据：
```
name
```
与文件名匹配；
```
description
```
为单行且面向触发场景；工具集精简；模型符合风险等级。
提示词：职责具体明确；工作流可执行；输出契约清晰。
委托：子代理的任务简报具体且边界明确；编排器验证集成情况。
安全：确认破坏性操作；避免敏感信息/个人身份信息；遵循仓库政策。

Navigation

Operational Guardrails: Subagent Orchestration

操作防护措施：子代理编排

Use these defaults unless the user explicitly asks for wider fan-out.

除非用户明确要求更广泛的扩展，否则请使用以下默认设置。

Hard Limits

硬性限制

Keep active subagents <= 3.
Keep each subagent scope to one responsibility and a bounded file set.
Do not let multiple subagents edit the same file in parallel.

活跃子代理数量 ≤ 3。
每个子代理的范围限定为单一职责和一组边界明确的文件。
不允许多个子代理并行编辑同一文件。

Handoff Template (Required)

交接模板（必填）

text

Goal:
Constraints:
Owned files:
Do-not-touch files:
Output format:
Definition of done:

text

Goal:
Constraints:
Owned files:
Do-not-touch files:
Output format:
Definition of done:

Merge Discipline

合并规范

Wait for subagent outputs.
Review for overlap/conflicts.
Integrate one subagent result at a time.
Run verification gates before final synthesis.

等待子代理输出结果。
检查是否存在重叠/冲突。
逐个集成子代理的结果。
在最终合成前运行验证关卡。

Stop Conditions

停止条件

Stop and re-plan when:

two subagents propose conflicting edits to same module,
repeated retries happen without new evidence,
context window starts dropping prior decisions.

出现以下情况时，停止当前操作并重新规划：

两个子代理对同一模块提出冲突的编辑建议，
重复重试但未产生新的有效信息，
上下文窗口开始丢弃之前的决策。

agents-subagents

Original

Translation

Claude Code Agents

Claude 编码代理

Quick Start

快速开始

SQL Optimizer

SQL Optimizer

Responsibilities

Responsibilities

Workflow

Workflow

Output Contract

Output Contract

Workflow (2026)

2026年工作流

Frontmatter Fields (Summary)

前置元数据字段（摘要）

2026 Best Practices (Domain Expertise)

领域专业知识最佳实践

Validation Checklist

验证检查清单

Navigation

导航

Operational Guardrails: Subagent Orchestration

操作防护措施：子代理编排

Hard Limits

硬性限制

Handoff Template (Required)

交接模板（必填）

Merge Discipline

合并规范

Stop Conditions

停止条件