E3 · Explorador de solo lectura
10 minCrea .claude/agents/explorador.md en el proyecto de entrenamiento y ejecuta el verificador.
Listo cuando: el verificador imprime explorador · tools: Read, Grep, Glob · model: inherit · escreve: não.
Clase 2 · 18 min
Subagentes: contexto limpio, retorno corto
Un subagente hace la parte ruidosa en una ventana de contexto propia y devuelve solo el resumen. Vale por lo que no vuelve: logs, búsquedas y archivos que la conversación principal nunca va a volver a leer. En esta clase escribes un subagente de solo lectura con retorno de hasta 12 líneas y verificas, de verdad, el tamaño de lo que volvió.
Empezar la clase
En esta clase vas a
- 1Qué recibe el subagente y qué devuelve
- 2El archivo .claude/agents/[nome].md y los campos que importan
- 3Herramientas restringidas: lo que la lista bloquea y lo que solo la instrucción pide
- 4Retorno con formato fijo y línea de confianza
Objetivo: crear un subagente de solo lectura con retorno de hasta 12 líneas y comprobar que su respuesta cabe en la conversación principal.
01Ida y vuelta de un subagente
Comportamiento de Claude Code 2.1.303, según la doc oficial leída el 19/10/2026. Haz clic en cada etapa.
Haz clic en cada bloque del diagrama para ver qué hace.
Fork es otra cosa: hereda la conversación entera (/subtask) y pierde el aislamiento de entrada. Sirve para una tarea lateral que necesita lo que ya se dijo.
02Los campos que deciden
Del frontmatter soportado, cuatro cambian el comportamiento en el día a día.
1. description
Claude delega cuando la tarea coincide con la descripción. Escribe cuándo usar y cuándo no usar, en una frase.
Un archivo nuevo en .claude/agents/ entra sin reiniciar, excepto cuando la carpeta agents/ no existía al inicio de la sesión.
2. tools
Lista de lo que puede usar. Sin el campo, hereda las de la conversación. Sin Write, Edit y Bash, no graba nada, por más que el modelo quiera.
disallowedTools con especificador, como Bash(git push *), quita la herramienta completa; para bloquear solo el comando, usa permissions.deny.
3. model
Acepta apodo o inherit. Elige por el nivel del rol (clase 7), no por el nombre del día: los nombres cambian.
El kit del runtime usa opus, sonnet y haiku en los tres roles; tómalo como ejemplo de niveles distintos.
4. Cuerpo
El cuerpo del archivo se convierte en el prompt de sistema. Pon en él el formato de la respuesta: número máximo de líneas, caminho:linha como prueba y una línea final de confianza.
Es el formato que deja al orquestador leer 10 resúmenes sin llenar su propia ventana.
03Un explorador de solo lectura
Crea el archivo, revisa los campos sin gastar cuota y luego haz una llamada real.
.claude/agents/explorador.md · en ~/treino-multi
--- name: explorador description: Busca en el proyecto y devuelve solo el resumen. Úsalo para recorrer muchos archivos sin llenar la conversación principal. tools: Read, Grep, Glob model: inherit --- Eres el explorador. No modifiques nada. Devuelve como máximo 12 líneas: 1. La respuesta en una frase. 2. Hasta 8 líneas en el formato ruta:línea — qué hay ahí. 3. Última línea: CONFIANÇA alta|média|baixa y lo que no verificaste.
Terminal · ensayo sin cuota: revisar los subagentes del proyecto
cd ~/treino-multi
python3 - .claude/agents/*.md <<'PY'
import sys, re
for f in sys.argv[1:]:
m = re.match(r"---\n(.*?)\n---", open(f, encoding="utf-8").read(), re.S)
if not m:
print(f, "→ SEM frontmatter"); continue
d = {k.strip(): v.strip() for k, v in (l.split(":", 1) for l in m.group(1).splitlines() if ":" in l)}
tools = d.get("tools", "(herda todas)")
escreve = "tools" not in d or any(x in tools for x in ("Write", "Edit", "Bash"))
print(f"{d.get('name', '?')} · tools: {tools} · model: {d.get('model', '(herda)')} · escreve: {'sim' if escreve else 'não'}")
PYTerminal · llamada real (gasta un poco de la cuota)
cd ~/treino-multi claude -p "Use o subagente explorador para descobrir onde este projeto define a própria versão e quais arquivos citam essa versão. Repita apenas o resumo que ele devolver, sem comentar." < /dev/null > resposta.md grep -c "^CONFIANÇA" resposta.md; wc -l < resposta.md
Ejemplo del repositorio
## conferidor (sem cota) executor · tools: Read, Write, Edit, Bash, Grep, Glob · model: sonnet · escreve: sim explorador · tools: Read, Grep, Glob · model: inherit · escreve: não planejador · tools: Read, Grep, Glob · model: opus · escreve: não revisor · tools: Read, Bash, Grep, Glob · model: haiku · escreve: sim ## resposta.md (chamada real, 29 s) A versão é 0.3.0 e a fonte da verdade é o arquivo VERSION na raiz. Não existe package.json nem pyproject, e nenhuma constante no código define a versão. Ela também aparece em mais 6 arquivos, num total de 9 ocorrências: - `VERSION:1`: `0.3.0` (definição) - `CHANGELOG.md:3`: `## 0.3.0 — 2026-10-05` - `runtime/mods/runtime-guarda/.claude-plugin/plugin.json:3`: `"version": "0.3.0"` - `runtime/mods/runtime-painel/.claude-plugin/plugin.json:3`: `"version": "0.3.0"` - `guia/index.html:329` e `:335`: rótulo "Fase 3 · 0.3.0" e rodapé "INEMA Agent Runtime 0.3.0" (… guia/en e guia/es, as mesmas duas citações …) CONFIANÇA alta. Não conferi o que o .gitignore exclui nem os outros números de versão (0.1.0, 0.2.0), e não verifiquei se algum script lê o VERSION.
Los títulos con ## separan las dos rondas. Cortes declarados: dos líneas de la guía traducida y una línea final que el CLAUDE.md global de la máquina de la captura añade. En tu máquina, wc -l debe quedar entre 10 y 15.
El verificador marcó revisor · … · escreve: sim. El archivo del kit dice "Não altere arquivos", pero la lista de herramientas incluye Bash, y Bash graba. La instrucción es un pedido al modelo; la lista de herramientas es el seguro.
revisor · tools: Read, Bash, Grep, Glob · model: haiku · escreve: sim
El revisor necesita Bash para ejecutar los criterios. Para que no grabe de verdad, la salida es sandbox (clase 5) o una regla de permiso; la protección contra borrar y escribir es tema del curso 4. Y la llamada real sin < /dev/null espera 3 s por el stdin y avisa: Warning: no stdin data received in 3s.
04Práctica
El ensayo revisa el archivo; la llamada real revisa el retorno.
E4 · Retorno que cabe
10 minHaz la llamada real. Después cambia la pregunta por una de tu proyecto de verdad, con el mismo subagente.
Listo cuando: grep -c "^CONFIANÇA" resposta.md → 1 y wc -l < resposta.md → como máximo 15, en las dos preguntas.
05Prueba de la clase
Pregunta 1 de 4
¿Qué vuelve del subagente a la conversación principal?competencia
Correcto
Solo vuelve la respuesta final. Por eso el formato del retorno, escrito en el cuerpo del archivo, es la parte más importante.No es esa
Solo vuelve la respuesta final. Por eso el formato del retorno, escrito en el cuerpo del archivo, es la parte más importante.Repasar: Ida y vuelta de un subagentePregunta 2 de 4
¿El subagente recibe el historial de la conversación principal?competencia
Correcto
El subagente común empieza limpio. El fork hereda toda la conversación y, con eso, pierde el aislamiento de entrada.No es esa
El subagente común empieza limpio. El fork hereda toda la conversación y, con eso, pierde el aislamiento de entrada.Repasar: Ida y vuelta de un subagentePregunta 3 de 4
Un revisor tiene tools: Read, Bash, Grep, Glob y la instrucción "não altere arquivos". ¿Puede grabar?
Correcto
Con Bash puede escribir con echo, sed o rm. Para bloquearlo de verdad: sandbox (lección 5) o regla de permiso (curso 4).No es esa
Con Bash puede escribir con echo, sed o rm. Para bloquearlo de verdad: sandbox (lección 5) o regla de permiso (curso 4).Repasar: Un explorador de solo lecturaPregunta 4 de 4
¿Cuándo NO conviene delegar a un subagente?
Correcto
El ida y vuelta y el contexto compartido se quedan en la conversación principal; el subagente empieza de cero y tendría que releer todo.No es esa
El ida y vuelta y el contexto compartido se quedan en la conversación principal; el subagente empieza de cero y tendría que releer todo.Repasar: Ida y vuelta de un subagentePrueba completada
Acertaste {a} de {n}. Si aciertas todas, la clase se marca como completada.Elige una alternativa. La explicación aparece después de tu intento.
06En tres frases
Vale por lo que no vuelveLos logs, las búsquedas y los archivos se quedan en la ventana del subagente; solo vuelve el resumen.
La herramienta es el candadoRead, Grep, Glob no escribe; Bash escribe, diga lo que diga la instrucción.
Formato fijoMáximo de líneas, ruta:línea como prueba y línea de confianza, escritos en el cuerpo del archivo.