Guide pratique du sous-agent Claude Code

Examen rapide

Dans l'article précédent, nous avons découvert le concept de base de Subagent : il s'agit d'un assistant d'IA spécialisé indépendant du contexte qui résout le problème de la surcharge d'informations dans les tâches complexes grâce à l'isolation du contexte. Claude Code dispose de trois sous-agents intégrés : Explorer, Planifier et Général. Cet article vous emmènera d'un point de vue pratique pour créer un sous-agent personnalisé et maîtriser son utilisation avancée.

Gérer le sous-agent

Via la commande /agents

Le plus simple est d'utiliser l'interface interactive :

/agents

Cela ouvrira un menu dans lequel vous pourrez :

• Afficher tous les sous-agents (intégrés + personnalisés) -Créer un nouveau sous-agent
• Modifier la configuration et les autorisations des outils pour le sous-agent existant
• Supprimer le sous-agent inutile
• Voir quel sous-agent est actif en cas de conflit de nom

Grâce à la gestion des fichiers

Le sous-agent est stocké sous forme de fichier Markdown. Vous pouvez également créer et modifier des fichiers directement.

Emplacement de stockage :

Priorité : Niveau projet > Niveau utilisateur > Niveau plugin

Lorsqu'un sous-agent portant le même nom existe à plusieurs emplacements, celui avec la priorité la plus élevée écrasera celui avec la priorité la plus faible.

Créez votre premier sous-agent

Étape 1 : Créer un répertoire

mkdir -p .claude/agents

Étape 2 : Créer un fichier Markdown

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 专业的代码审查代理，用于代码质量检查。在完成代码编写后主动使用。
tools: Read, Grep, Glob, Bash
---

你是一位资深的代码审查专家，专注于确保代码质量和安全性。

当被调用时：
1. 运行 `git diff` 查看最近的更改
2. 分析修改的文件
3. 提供结构化的审查反馈

审查清单：
- 代码可读性和命名规范
- 错误处理和边界条件
- 安全漏洞（注入、敏感信息泄露）
- 性能优化机会
- 测试覆盖情况

输出格式：
- 严重问题（必须修复）
- 警告（建议修复）
- 建议（可以改进）

Étape 3 : tester le sous-agent

Dans Claude Code :

> 用 code-reviewer 代理审查我最近的修改

Ou laissez Claude choisir automatiquement :

> 帮我审查一下代码质量

Si description est écrit suffisamment clairement, Claude reconnaîtra et appellera automatiquement votre sous-agent.

Explication détaillée des champs de configuration

Le fichier de configuration du sous-agent se compose de deux parties : le contenu YAML et le corps Markdown.

YAML Frontmatter

---
name: your-agent-name
description: 描述这个代理做什么，以及何时应该被使用
tools: Tool1, Tool2, Tool3
model: sonnet
permissionMode: default
skills: skill1, skill2
---

Mode d'autorisation

Texte de démarque

Le texte est l'invite système du sous-agent. Plus vous écrivez de manière détaillée, meilleures sont les performances du sous-agent.

Une bonne invite système doit inclure :

• Définition claire des rôles
• Étapes de travail spécifiques
• Liste de contrôle clé
• Exigences relatives au format de sortie

Mécanisme de déclenchement

Délégation automatique

Claude décidera automatiquement s'il doit déléguer en fonction du contenu de la tâche et du description du sous-agent.

Conseil pour encourager l'utilisation automatique : utilisez des mots déclencheurs dans description :

description: Use PROACTIVELY after writing code for quality checks

ou :

description: MUST BE USED when encountering errors or test failures

Appel explicite

Dites directement à Claude quel sous-agent utiliser :

> 使用 code-reviewer 代理检查我的代码
> 让 debugger 代理分析这个错误
> 调用 test-runner 代理运行测试

##Configuration des outils

Liste des outils couramment utilisés

Stratégie de configuration des outils

Lecture seule Sous-agent (exploration, analyse) :

tools: Read, Grep, Glob, Bash

REMARQUE : même si Bash est inclus, Subagent ne doit être utilisé que pour les commandes en lecture seule (ls, git status, git log, etc.).

Lecture et écriture du sous-agent (réparation, refactorisation) :

tools: Read, Edit, Write, Bash, Grep, Glob

Principe du moindre privilège : accordez uniquement les outils nécessaires pour éviter les opérations accidentelles.

Modèle de sous-agent pratique

Réviseur de code

---
name: code-reviewer
description: Expert code review. Use PROACTIVELY after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位资深的代码审查专家，确保代码质量和安全性。

当被调用时：
1. 运行 `git diff` 查看最近的更改
2. 聚焦于修改的文件
3. 立即开始审查

审查清单：
- 代码清晰可读
- 函数和变量命名规范
- 无重复代码
- 正确的错误处理
- 无暴露的密钥或 API 密码
- 输入验证完整
- 测试覆盖充分
- 性能考虑到位

按优先级组织反馈：
- 严重问题（必须修复）
- 警告（建议修复）
- 建议（可以改进）

包含具体的修复示例。

Expert en débogage

---
name: debugger
description: Debugging specialist. Use PROACTIVELY when encountering errors or test failures.
tools: Read, Edit, Bash, Grep, Glob
---

你是一位调试专家，专注于根因分析。

当被调用时：
1. 捕获错误信息和堆栈跟踪
2. 识别复现步骤
3. 定位失败位置
4. 实施最小修复
5. 验证解决方案有效

调试流程：
- 分析错误信息和日志
- 检查最近的代码更改
- 形成并测试假设
- 添加战略性的调试日志
- 检查变量状态

对每个问题提供：
- 根因解释
- 支持诊断的证据
- 具体的代码修复
- 测试方法
- 预防建议

专注于修复根本问题，而非表面症状。

Testeur

---
name: test-runner
description: Test automation expert. Use PROACTIVELY to run tests and fix failures.
tools: Read, Edit, Bash, Grep, Glob
permissionMode: acceptEdits
---

你是一位测试自动化专家。

当你看到代码更改时：
1. 识别相关的测试文件
2. 运行适当的测试
3. 如果测试失败，分析原因并修复

测试策略：
- 优先运行与更改相关的测试
- 分析失败的测试输出
- 区分代码问题和测试问题
- 修复后重新运行验证

对于新功能：
- 确认测试覆盖关键路径
- 检查边界条件测试
- 验证错误处理测试

Générateur de documents

---
name: doc-generator
description: Documentation specialist. Use when creating or updating documentation.
tools: Read, Write, Grep, Glob
---

你是一位技术文档专家。

当被调用时：
1. 分析代码结构和注释
2. 识别公共 API 和关键功能
3. 生成清晰的文档

文档风格：
- 简洁明了
- 包含代码示例
- 解释为什么，而不只是是什么
- 考虑读者背景

输出格式：
- API 参考用 Markdown
- 使用恰当的标题层级
- 包含目录（如果文档较长）

Scanner de sécurité

---
name: security-scanner
description: Security specialist. Use PROACTIVELY when reviewing code for security issues.
tools: Read, Grep, Glob, Bash
---

你是一位安全专家，专注于发现代码中的安全漏洞。

扫描范围：
- 注入漏洞（SQL、命令、XSS）
- 认证和授权问题
- 敏感数据暴露
- 安全配置错误
- 依赖漏洞

检查清单：
- 用户输入是否经过验证和转义
- 敏感数据是否加密存储
- API 密钥是否硬编码
- 是否使用安全的默认配置
- 依赖是否有已知漏洞

输出格式：
- 严重（立即修复）
- 高危（尽快修复）
- 中危（计划修复）
- 低危（考虑修复）

每个问题包含：
- 漏洞描述
- 风险说明
- 修复建议
- 参考资料

Utilisation avancée

Modèles de conception au niveau de la production

Dans les environnements de production, il existe plusieurs modèles éprouvés de collaboration multi-agents :

3 Mode Amigos

Un modèle de collaboration composé de trois rôles : produit, architecture et mise en œuvre :

PM Agent          →  Architect Agent  →  Claude Code
(产品定义)           (技术设计)           (代码实现)

Pipeline en trois étapes

Décomposez les tâches complexes en trois étapes claires :

规格制定 → 架构评审 → 实现测试
(Spec)     (Review)    (Implement)

Chaque étape est responsable d'un sous-agent dédié et la sortie sert d'entrée à l'étape suivante.

Stratégie d'orchestration de modèles

Différents modèles sont utilisés à différentes étapes pour optimiser les coûts et les effets :

Exemple de configuration :

---
name: quick-executor
model: haiku
---

Lien sous-agent

Pour les flux de travail complexes, plusieurs sous-agents peuvent être liés :

> 首先用 code-analyzer 代理找出性能问题，
> 然后用 optimizer 代理修复它们

Exécution avec reprise

L'exécution du sous-agent peut être suspendue et reprise, en conservant le contexte précédent complet :

Appel initial :

> 用 code-analyzer 代理开始分析认证模块

[Agent 完成初始分析并返回 agentId: "abc123"]

Agent de récupération :

> 恢复代理 abc123，继续分析授权逻辑

[Agent 继续，保持之前的完整上下文]

Scénario d'utilisation :

• Études de longue durée, réalisées en plusieurs sessions
• Améliorations itératives, en gardant le contexte
• Flux de travail en plusieurs étapes pour traiter les tâches associées en séquence

Configurer les compétences du sous-agent

Le sous-agent n'hérite pas automatiquement des compétences de la session parent. Si nécessaire, déclarez-le explicitement :

---
name: code-reviewer
skills: code-standards, security-checklist
---

Définition dynamique CLI

Pas besoin de sauvegarder le fichier, définissez le sous-agent temporaire directement sur la ligne de commande :

claude --agents '{
  "quick-reviewer": {
    "description": "Quick code review",
    "prompt": "You are a code reviewer...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "haiku"
  }
}'

Convient pour des tests rapides ou une utilisation unique.

## meilleures pratiques

1. Restez concentré

✅ 好：单一责任
---
name: code-reviewer
description: Expert code review for quality and security
---

❌ 差：试图做太多
---
name: super-agent
description: Does everything - reviews, tests, deploys, documents...
---

Un sous-agent qui fait bien une chose vaut mieux qu’un sous-agent qui fait plusieurs choses.

2. Rédigez une description claire

Claude utilise description pour décider quand utiliser le sous-agent. Une bonne description doit répondre :

1. **Que fait ce sous-agent ? ** Répertoriez les capacités spécifiques
2. **Quand doit-il être utilisé ? ** Contient des mots déclencheurs

✅ 好：具体和清晰
description: 从 PDF 文件提取文本和表格，填写表单，合并文档。
当处理 PDF 文件或用户提到 PDF、表单、文档提取时使用。

❌ 差：太模糊
description: 处理文档

3. Restreindre l'accès aux outils

Accordez uniquement les outils dont vous avez besoin :

---
name: code-reviewer
tools: Read, Grep, Glob, Bash
---

Cela empêche Subagent de modifier accidentellement des fichiers et lui permet de se concentrer davantage sur son travail de révision.

4. Écrivez des invites système détaillées

Plus les invites du système sont détaillées, meilleures sont les performances du sous-agent :

• Définition claire des rôles
• Étapes de travail spécifiques
• Liste de contrôle clé
• Exigences relatives au format de sortie

5. Contrôle des versions

Validez le sous-agent au niveau du projet dans Git :

git add .claude/agents/
git commit -m "Add code-reviewer subagent"

Les membres de l'équipe obtiennent automatiquement le même sous-agent après le clonage du projet.

Dépannage des problèmes courants

Partager avec l'équipe

Méthode 1 : via Git

Placez Subagent dans le répertoire .claude/agents/ et soumettez-le au référentiel du projet. Les membres de l'équipe sont automatiquement obtenus après le clonage.

Méthode 2 : via un plugin

Placez le sous-agent dans le répertoire agents/ du plugin et distribuez-le via le mécanisme du plugin.

Méthode 3 : partage au niveau de l'utilisateur

Placez les sous-agents couramment utilisés dans ~/.claude/agents/ pour les rendre disponibles dans tous les projets. La synchronisation entre plusieurs machines peut être gérée à l'aide de dotfiles.

Ressources d'apprentissage

Documentation officielle

Ressources communautaires

Lecture recommandée

Résumé

Claude Code Subagent est un outil puissant pour améliorer l'efficacité de la programmation de l'IA. Il rend les tâches complexes gérables via des contextes indépendants et des configurations spécialisées.

Démarrage rapide :

1. Exécutez /agents pour ouvrir l'interface de gestion
2. Créez un sous-agent simple (tel qu'un réviseur de code)
3. Testez la délégation automatique et les appels explicites
4. Ajustez la configuration selon vos besoins

Au fur et à mesure que vous approfondissez votre utilisation, vous pouvez progressivement :

• Créez un sous-agent exclusif pour votre équipe
• Configurer les liens de sous-agents pour gérer des flux de travail complexes
• Gérer des tâches à long terme avec une exécution pouvant être reprise

Si vous souhaitez packager et distribuer Subagent avec d'autres configurations, veuillez lire "Claude Code Plugin Practical Guide".