Verificando acesso...

MÓDULO 3.1

đŸ€– Criando subagentes nos dois

Anatomia, criação no Claude (markdown) e Codex (TOML), auto-invocação vs spawn, max_threads e max_depth, receita pra subagent narrow.

1

🧬 Anatomia de um subagent

Sub-agente Ă© uma sessĂŁo filha com context prĂłprio. Recebe prompt do pai, faz o trabalho, retorna SÓ a resposta final. O context da varredura nĂŁo polui o pai.

As 4 propriedades fundamentais

  • Fresh context: começa zerado, nĂŁo herda histĂłrico do pai
  • One-way: pai → filho via prompt; filho → pai via resposta final
  • Output synthesis: filho sintetiza, pai sĂł vĂȘ o resumo
  • Tool surface: pode ter tools restritas (read-only, p.ex.)

Use case principal: auditar 50 arquivos sem inchar o context principal. Subagent lĂȘ tudo, devolve punch list de 20 linhas.

2

📝 Criando no Claude Code (markdown)

Arquivo .claude/agents/nome.md. Comando /agents abre wizard interativo.

---
name: dead-code-audit
description: Use quando o usuårio pedir auditoria de código morto, imports não usados, ou funçÔes órfãs
tools: [Read, Grep, Bash]
---

VocĂȘ Ă© um auditor de cĂłdigo morto.

Quando invocado, faça:
1. Liste todos os arquivos .ts/.tsx em src/
2. Para cada um, identifique imports não usados e funçÔes sem caller
3. Retorne markdown com tabela: arquivo | tipo | item | severidade
4. MĂĄximo 30 linhas total. Priorize por severidade.

A description com "Use quando..." Ă© o que faz o Claude saber DISPARAR esse agent automaticamente. Especificidade aqui paga.

3

⚙ Criando no Codex (TOML)

Arquivo .codex/agents/nome.toml (projeto) ou ~/.codex/agents/ (pessoal). Mais campos opcionais.

name = "dead-code-audit"
description = "Audita cĂłdigo morto em src/"
model = "gpt-5"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
nickname_candidates = ["audit", "cleanup", "dead"]

developer_instructions = """
VocĂȘ Ă© um auditor de cĂłdigo morto.

Quando invocado:
1. Liste arquivos .ts/.tsx em src/
2. Identifique imports não usados, funçÔes sem caller
3. Retorne tabela: arquivo | tipo | item | severidade
4. MĂĄximo 30 linhas. Priorize por severidade.
"""

Campos opcionais Ășteis

  • model — usa modelo diferente do default (gpt-5 vs gpt-5-pro)
  • model_reasoning_effort — "low" | "medium" | "high"
  • sandbox_mode — "read-only" | "workspace-write" | "danger-full-access"
  • nickname_candidates — apelidos pra invocar mais rĂĄpido
  • mcp_servers — MCPs especĂ­ficos pra esse agent
4

🎯 Auto-invocação (Claude) vs spawn (Codex)

Diferença fundamental que muda como vocĂȘ escreve a description.

Claude — automático

Agente principal decide invocar baseado em description.

"Audita o cĂłdigo morto em src/"
→ Claude vĂȘ o trigger, invoca dead-code-audit automaticamente

⚠ Se description nĂŁo trigger → agente principal faz inline (e poluĂ­ context).

Codex — explícito

Subagent sĂł roda com comando spawn.

"spawn dead-code-audit"
"spawn audit no src/" (via nickname)

⚠ Esqueceu o spawn? Codex faz inline e poluĂ­ context.

5

🔱 max_threads e max_depth (Codex)

Codex impĂ”e limites duros que forçam vocĂȘ a planejar fan-out:

# .codex/config.toml

[agents]
max_threads = 6   # paralelos mĂĄximos (default)
max_depth = 1     # subagent NÃO pode criar subsubagent (default)

✓ PadrĂ”es que funcionam

  • Fan-out 6 subagents auditando 6 ĂĄreas em paralelo
  • Pai sintetiza 6 outputs
  • Trabalho horizontal e independente

✗ PadrĂ”es que quebram

  • Subagent criando subsubagent (recursĂŁo)
  • Mais de 6 paralelos (vai fila)
  • DependĂȘncias entre subagents

Claude nĂŁo documenta limites equivalentes — entĂŁo Codex Ă© mais previsĂ­vel pra workflows com fan-out. Lado bom de ser explĂ­cito.

6

📐 Receita: subagent narrow

Os melhores subagents seguem a receita:

1

1 trabalho claro

"Audita dead code" — claro. "Helper" — não claro.

2

Tool surface que combina

Auditor sĂł precisa Read + Grep. NĂŁo dĂȘ Bash/Write se nĂŁo for usar.

3

Output schema previsĂ­vel

"Retorne tabela markdown de atĂ© 30 linhas" — o pai sabe o que vai receber.

4

Anti-drift explĂ­cito

"NÃO refatore, apenas reporte" — limita o escopo. Senão o subagent começa a corrigir o que viu.

📚 Resumo

✓
Subagent = sessĂŁo filha com fresh context
✓
Claude: markdown + YAML; Codex: TOML
✓
Auto-invocação (Claude) vs spawn (Codex)
✓
max_threads=6, max_depth=1 no Codex
✓
Receita: 1 job, tools mĂ­nimos, output schema, anti-drift

PrĂłximo:

3.2 — Forças e limitaçÔes: qual usar pra cada task

← Voltar para TrilhaPrĂłximo: Forças e LimitaçÔes →