代理设计最佳实践

设计与多媒体 社区

技能解读

当前原文的自动摘译,尚未人工审校。

概述

此技能定义了设计 Claude Code 代理文件 (.claude/agents/*.md) 的最佳实践。代理文件定义可重用的角色,可以作为子代理或队友生成。核心原则是代理文件定义功能,而不是生命周期——团队领导的生成提示控制代理运行的时间和方式。

1. 定义功能,而不是生命周期

代理文件描述代理可以做什么。来自团队负责人的生成提示控制“何时”运行以及“关注什么”。错误的版本与一个工作流程耦合(“计划创建代理团队”、“给出研究简介”、“通过 SendMessage 发送”)。正确的版本适用于任何环境——计划、审查、临时分析——因为团队领导的生成提示提供了具体的说明。

2. 每个域一个代理,而不是每个阶段

优先选择覆盖某个域的单个代理,而不是按工作流程阶段划分的多个代理。团队负责人通过生成提示专门指定每个阶段的代理。错误 · 正确 security-planner + security-reviewer · security-specialist test-strategist + test-coverage-agent · test-specialist architecture-planner + architecture-reviewer · architecture-specialist

3. 设计重点领域

每个代理都应该在一个特定领域表现出色。该领域应该足够广泛,以避免工作流耦合,但又足够狭窄,以提供真正的专业知识。

4. 撰写详细描述

Claude 使用 YAML frontmatter 中的 description 字段来决定何时委派任务。具体说明代理的作用以及何时增加价值。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
设计与多媒体
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Agent Design Best Practices

## Overview

This skill defines best practices for designing Claude Code agent files (`.claude/agents/*.md`). Agent files define reusable roles that can be spawned as subagents or teammates. The core principle is that **agent files define capabilities, not lifecycle** -- the team lead's spawn prompt controls when and how the agent runs.

## Principles

### 1. Define Capabilities, Not Lifecycle

Agent files describe *what* an agent can do. The spawn prompt from the team lead controls *when* it runs and *what to focus on*.

```markdown
<!-- Wrong: Hardcodes workflow phase and interaction pattern -->
# Security Planner Agent

You are a security specialist in a plan-create Agent Team.
Given a Research Brief from the team lead, identify security
considerations for the planned changes.

## Output Format

Send your sub-plan to the team lead via `SendMessage` with this structure:
...
```

```markdown
<!-- Correct: Defines domain expertise, team lead controls usage -->
# Security Specialist Agent

You are a security specialist who identifies vulnerabilities,
evaluates threats, and recommends mitigations for code changes.

## Analysis Process
1. Read affected files
2. STRIDE analysis
3. Check input validation
...
```

The wrong version is coupled to one workflow ("plan-create Agent Team", "Given a Research Brief", "Send via SendMessage"). The correct version works in any context -- planning, review, ad-hoc analysis -- because the team lead's spawn prompt provides the specific instructions.

### 2. One Agent Per Domain, Not Per Phase

Prefer a single agent that covers a domain over multiple agents split by workflow phase. The team lead specializes the agent per phase via the spawn prompt.

| Wrong | Right |
|-------|-------|
| `security-planner` + `security-reviewer` | `security-specialist` |
| `test-strategist` + `test-coverage-agent` | `test-specialist` |
| `architecture-planner` + `architecture-reviewer` | `architecture-specialist` |

The same agent type can be spawned multiple times with different prompts for different phases. A `security-specialist` spawned during planning gets "evaluate this plan for security risks" while the same type spawned during review gets "review these code changes for vulnerabilities."

### 3. Design Focused Domains

Each agent should excel at one specific domain. The domain should be broad enough to avoid workflow coupling but narrow enough to provide real expertise.

```yaml
# Too narrow (coupled to one workflow step)
description: Performs STRIDE analysis on Research Briefs during plan-create Phase 2

# Too broad (no clear expertise)
description: General-purpose agent that can do anything

# Just right (focused domain, reusable across workflows)
description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling.
```

### 4. Write Detailed Descriptions

Claude uses the `description` field in YAML frontmatter to decide when to delegate tasks. Be specific about what the agent does and when it adds value.

```yaml
# Bad: Vague, Claude can't decide when to use it
description: Reviews code

# Good: Specific domain, clear trigger conditions
description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling, and recommends mitigations.
```

### 5. Limit Tool Access

Grant only the tools necessary for the agent's domain. This enforces focus and prevents agents from exceeding their intended scope.

| Agent Type | Appropriate Tools | Rationale |
|-----------|-------------------|-----------|
| Researcher / Reviewer | `Read, Grep, Glob, Bash` | Read-only analysis, no file modifications |
| Implementer | `Read, Write, Edit, Bash, Grep, Glob` | Needs to modify code |
| Planner | `Read, Grep, Glob` | Research only, no execution |

Read-only agents cannot implement code. Do not assign implementation tasks to agents without `Write` and `Edit` tools.

### 6. No Hardcoded Interaction Patterns

Do not prescribe how the agent communicates or what input format it expects. The team lead's spawn prompt handles interaction patterns.

```markdown
<!-- Wrong: Hardcodes communication protocol -->
## Input
You receive a **Research Brief** from the team lead containing...

## Output Format
Send your sub-plan to the team lead via `SendMessage` with this structure:
```

```markdown
<!-- Correct: Defines output structure without prescribing delivery mechanism -->
## Output Format
Structure your findings as:

### Threat Model (STRIDE)
| Threat | Applies? | Description | Mitigation |
...
```

The output format itself is fine to define -- it provides structure. But how the agent receives input and delivers output should be left to the team lead.

### 7. Context Window Isolation

Each teammate has its own context window. Teammates do not share context and cannot see what other teammates have done. Account for this in agent design:

- Do not assume the agent has seen previous analysis from other agents
- Include enough domain knowledge in the agent file for independent operation
- The team lead bridges context between agents via spawn prompts and messages

### 8. File Ownership in Teams

When agents work in teams, each teammate should own distinct files or directories. Two teammates editing the same file leads to conflicts and lost work.

Design agent domains so their file ownership naturally separates:

| Agent | Owns |
|-------|------|
| `implementer` | Source files (`src/`) |
| `test-specialist` | Test files (`tests/`) |
| `quality-specialist` | No files (read-only) |

## Agent File Structure

### Required Frontmatter

```yaml
---
name: agent-name           # lowercase with hyphens
description: When and why to use this agent. Be specific.
tools: Read, Grep, Glob     # comma-separated, minimal set
---
```

### Optional Frontmatter

```yaml
model: sonnet              # sonnet, opus, haiku, or inherit (default)
permissionMode: default     # default, acceptEdits, plan, bypassPermissions, etc.
maxTurns: 50               # limit agentic turns
skills:                     # skills to preload
  - skill-name
memory: user                # persistent memory: user, project, or local
```

### Body Structure

The markdown body becomes the agent's system prompt. Structure it as:

1. **Role statement** -- one sentence describing what the agent is
2. **Analysis/workflow process** -- numbered steps for the agent's approach
3. **Output format** -- structure for findings (without prescribing delivery mechanism)
4. **Rules/constraints** -- guardrails for the agent's behavior

## Anti-Patterns

### Don't Create Phase-Specific Agents

```markdown
<!-- Wrong: Two agents for the same domain, split by phase -->
# Pre-Implementation Security Planner
...
# Post-Implementation Security Reviewer
...

<!-- Correct: One agent, team lead controls timing -->
# Security Specialist
...
```

### Don't Hardcode Workflow Dependencies

```markdown
<!-- Wrong: Agent assumes specific workflow context -->
You are part of the plan-create Phase 2 team.
Wait for the Research Brief from Phase 1.
After your analysis, the Consistency Checker will validate your output.

<!-- Correct: Agent is self-contained -->
You are a security specialist who identifies vulnerabilities
and recommends mitigations for code changes.
```

### Don't Over-Specify the Model

Only set `model` when there's a clear reason. Most agents work well with `inherit` (the default), which uses the same model as the parent session. Use `haiku` for fast, simple tasks (exploration, search). Use `sonnet` or `opus` only when the domain requires stronger reasoning.

## Verification Checklist

Before committing an agent file, verify:

1. **Description is specific** -- Claude can determine when to delegate from the description alone
2. **Tools are minimal** -- only the tools the agent actually needs
3. **No workflow coupling** -- no references to specific team structures, phases, or input formats
4. **No hardcoded communication** -- no "send via SendMessage" or "given a Research Brief"
5. **Domain is reusable** -- the agent works in planning, review, and ad-hoc contexts
6. **Role statement is clear** -- first line of body explains what the agent is
7. **Output format is defined** -- structured output without prescribing delivery

---
> Source: [CodySwannGT/lisa](https://github.com/CodySwannGT/lisa) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。