CLAUDE.md, subagentes, hooks, skills, worktrees y los cinco servidores MCP que realmente valen la pena.

Para la mayoría de los ingenieros que usan Claude Code en este momento, la respuesta de la herramienta suele ser un frío “command not found” o un único archivo con una instrucción vaga para escribir código limpio. Lo entiendo, está bien. Pero también significa que estamos dejando aproximadamente el 80% del producto sin aprovechar.

Así es como se ve el mismo comando en un repositorio configurado por un usuario avanzado.

Plaintext

.claude/
├── CLAUDE.md
├── rules/
│   ├── langgraph.md
│   ├── retrieval.md
│   ├── tests.md
│   └── python-types.md
├── agents/
│   ├── retrieval-reviewer.md
│   ├── prompt-auditor.md
│   └── eval-runner.md
├── skills/
│   ├── new-rag-eval/
│   │   └── SKILL.md
│   └── claude-pr-checklist/
│       └── SKILL.md
├── settings.json
└── .mcp.json

Ninguno de estos archivos es largo. El archivo principal de memoria tiene menos de 500 tokens a propósito. Cada archivo de reglas es un comportamiento breve asociado a una ruta específica. Cada subagente tiene unas treinta líneas. La configuración de hooks en el archivo de settings consiste en una compuerta previa al uso de herramientas y un formateador posterior. La configuración de servidores tiene cinco servidores en lugar de quince.

Imagina a dos ingenieros realizando exactamente la misma tarea. Necesitan añadir generación de respuestas respaldadas por citas a un servicio de recuperación existente. También deben escribir las evaluaciones y abrir un PR contra la rama principal.

Un ingeniero tiene la carpeta vacía. El otro tiene la estructura anterior y un modo headless completamente configurado. El primero pasa toda una tarde implementando una funcionalidad que termina desplegando por la noche. El segundo abre un pull request en treinta minutos. La diferencia no está en los prompts que escriben. La diferencia está en una pila de configuración que nadie se tomó el tiempo de construir.

Comienza por el archivo de memoria, porque todas las demás capas son más económicas cuando esta es breve.

Capa 1: La jerarquía de memoria

Claude Code utiliza una jerarquía de memoria de cinco niveles. Tienes preferencias personales en tu directorio home, un archivo en la raíz del proyecto, reglas asociadas a rutas específicas, sobrescrituras locales no confirmadas y las escrituras automáticas de memoria que realiza la herramienta en cada sesión.

El archivo de la raíz del proyecto se carga al inicio de cada sesión. Consume tokens de forma permanente. Muchos equipos vuelcan toda su wiki de ingeniería dentro de este archivo, tratándolo como si fuera una base de datos vectorial en lugar de una caché caliente.

Las tasas de acierto de caché disminuyen notablemente más allá de los ~500 tokens en mis propias cargas de trabajo. El nuevo tokenizador de Opus 4.7 convierte los prompts existentes en aproximadamente entre 1,0 y 1,35 veces más tokens, lo que significa que exactamente la misma carga ahora es más costosa si no controlas estrictamente tu contexto ambiental.

Mantenga el archivo por debajo de 200 líneas. Escríbelo de forma imperativa. No utilice sugerencias descriptivas como “escribir código limpio”. Escribe reglas literales como “todas las funciones deben tener anotaciones de tipos en TypeScript”. Cada línea debe cambiar realmente el comportamiento.

Aquí está el archivo mínimo para nuestro servicio RAG.

Reducción

# citation-rag
Servicio de recuperación + generación de respuestas. Pipeline basado en
LangGraph, recuperación PostgreSQL+pgvector, generación de respuestas con Gemini,
arnés de evaluación en `evals/`.

## Estructura
- `services/retrieval/`  — fragmentación, embeddings, reranker, empaquetado de citas
- `services/answer/`     — plantillas de prompts, nodo generador, guardrails
- `shared/`              — esquemas, trazabilidad, configuración
- `evals/`               — conjuntos dorados, runners, puntuación

## Compilación y pruebas
- Instalar:           `uv sync`
- Pruebas unitarias:  `uv run pytest -q`
- Arnés de evaluación:`uv run python -m evals.run --suite citations`
- Lint + tipos:       `uv run ruff format . && uv run mypy .`

## Convenciones canónicas
- El prompt canónico de respuestas vive en
  `services/answer/prompts/v4.md`.
  No edites `v3.md` porque está congelado para evaluaciones de regresión.
- Todas las salidas del LLM se validan con los modelos pydantic de
  `shared/schemas/answers.py`. No se permiten retornos de diccionarios sin tipar.
- Retrieval siempre devuelve objetos `Chunk` con un `citation_id`.
  El nodo de respuestas debe emitir citas usando exactamente esos IDs.

## Guardrails (Claude: sigue estas reglas literalmente)
- Nunca actualices la versión del modelo sin actualizar
  `evals/snapshots/<version>.json` en el mismo commit.
- Nunca introduzcas llamadas de red dentro de `tests/unit/`.
  Utiliza fixtures en `tests/fixtures/` and fakes en `tests/fakes/`.
- Prefiere editar módulos existentes antes que crear nuevos paquetes raíz.
- Si un cambio afecta `services/retrieval/`, lee primero
  `.claude/rules/retrieval.md`.
- Mantén las funciones por debajo de ~40 líneas.
  Divide por responsabilidad, no por longitud.

## Antes de abrir un PR
- Ejecuta el arnés de evaluación y adjunta la salida del diff al PR.
- Actualiza `CHANGELOG.md` bajo `## Unreleased`.
- Utiliza la skill `claude-pr-checklist`.

Esto le indica al agente exactamente qué hace cada directorio. Defina el contrato estricto de citas entre el nodo de recuperación y el nodo de respuestas. Establece barandillas rígidas para las pruebas que evitan que el modelo alucine mocks de red.

Capa 2: Reglas asociadas a rutas

Una vez que disciplinas tu memoria raíz, todavía necesitas instrucciones específicas para determinados archivos. Para eso están las reglas asociadas a rutas.

El patrón utiliza frontmatter YAML. Define un conjunto de rutas con globos. La herramienta carga el archivo de reglas únicamente cuando toca un archivo coincidente. El resto del tiempo cuesta cero tokens. Si el agente está editando scripts de migración de bases de datos, no necesita leer convenciones de estilos frontend.

Nota: Aunque paths:es la clave documentada, las versiones actuales a veces la ignoran debido a un error conocido. En la práctica, usar globs:un formato CSV suele ser más confiable si notas que tus reglas se están ignorando silenciosamente.

Aquí tienes el archivo de reglas para nuestro servicio de recuperación.

YAML

---
name: retrieval-rules
description: Convenciones para services/retrieval/**.
  Solo se carga cuando Claude edita o planifica cambios
  dentro del servicio de recuperación.
globs:
  - "services/retrieval/**"
  - "tests/retrieval/**"
---
# Reglas del servicio de recuperación

## Fragmentación (Chunking)
- Utiliza `shared/chunking.semantic_chunker` para toda ingesta documental.
  No introduzcas un segundo chunker sin actualizar la instantánea de evaluación.
- Tamaño objetivo: 512 tokens, 64 de solapamiento.
  Los cambios requieren un ADR.

## Reranker
- La interfaz es `services/retrieval/reranker.Reranker`.
  Los nuevos backends deben implementarla, no duplicarla.
- Nunca rerankees más de los 50 primeros resultados.
  La latencia del reranker es el principal riesgo para el SLO del servicio.

## Citas
- Cada `Chunk` devuelto debe incluir un `citation_id` estable.
- Los IDs son generados por `shared.citations.make_citation_id`.
  No generes IDs manualmente.
- El nodo de respuestas asume que `citation_id` es seguro para URL.
  No cambies esto sin actualizar
  `services/answer/citation_packer.py` en el mismo diff.

## Pruebas
- Las pruebas unitarias nunca deben llamar a la API de embeddings.
  Usa el embedder falso en `tests/fakes/embeddings.py`.
- Las pruebas de integración viven en
  `tests/retrieval/integration/` y se ejecutan con
  `pytest -m integration`.

Tres o cuatro archivos de reglas pequeños son mejores que un único archivo enorme en la raíz. El ahorro de tokens se acumula en cada interacción.

Capa 3: Modo Plan

La mayoría de las personas nunca utilizan Plan Mode en producción. Escriben un aviso y observan cómo los archivos cambian inmediatamente.

Plan Mode separa el pensamiento de la ejecución. Mantiene la exploración fuera del contexto principal y genera un documento explícito que puedes revisar y modificar antes de que ocurra cualquier acción destructiva.

Claude Code ofrece tres niveles de planificación:

  • Plan Simple: tareas cortas en un único archivo.
  • Plan Visual: cambios en Múltiples archivos donde la estructura importa.
  • Deep Plan: cambios entre servicios y refactorizaciones con riesgo.

Deep Plan utiliza subagentes para evaluación de riesgos y revisión arquitectónica. El subagente planificador es de solo lectura por diseño. No tiene permisos de escritura ni edición. No puede modificar accidentalmente su código mientras analiza las dependencias.

En nuestro ejemplo del servicio RAG, utilizamos Deep Plan para rastrear el flujo actual de generación de respuestas. El subagente de exploración reúne los archivos relevantes en un contexto reducido. El planificador genera una lista específica de cambios, enumera las evaluaciones necesarias y redacta la descripción del pull request. Tú revisas el plan y lo apruebas. Los cambios reales solo ocurren después de salir de Plan Mode.

Capa 4: Subagentes personalizados

Los subagentes son probablemente la funcionalidad más infrautilizada de toda la herramienta.

Claude Code incluye subagentes integrados. El agente de exploración realiza búsquedas de solo lectura. El agente generalista maneja tareas complejas con un contexto limpio. Existen también revisores de código y arquitectos.

Crea un subagente personalizado cuando:

  • Repite una tarea frecuentemente.
  • Necesita restricciones específicas de herramientas.
  • El aviso del sistema entra en conflicto con su configuración principal.

Nuestro ingeniero RAG utiliza tres agentes personalizados: prompt-auditor, eval-runnery retrieval-reviewer. Aquí está el revisor de recuperación.

YAML

---
name: retrieval-reviewer
description: Revisa cambios bajo services/retrieval/ para detectar
  regresiones de fragmentación, reranking y contratos de citas.
  Solo lectura. Invócalo antes de abrir un PR.
tools: Read, Grep, Glob, Bash(git diff:*), Bash(uv run pytest:*)
model: sonnet
---
Eres un revisor del servicio de recuperación para el repositorio citation-rag.

Alcance:
- Solo revisa archivos dentro de `services/retrieval/**`
  y sus pruebas.
- No comentes archivos no relacionados.

Checklist:
1. Chunking: ¿respeta el objetivo 512/64 y sigue usando
   `shared.chunking.semantic_chunker`?
2. Reranker: si cambió la interfaz,
   ¿todas las implementaciones fueron actualizadas?
   ¿el límite top-k sigue siendo ≤ 50?
3. Citas: cada `Chunk` debe usar
   `shared.citations.make_citation_id`.
4. Pruebas: sin llamadas de red en unit tests.
5. Impacto en evaluaciones:
   ¿se regeneraron los snapshots correspondientes?

Formato de salida:
- Veredicto (pass / needs-changes / blocker).
- Lista de hallazgos con archivo y solución.
- No sugierst refactorizaciones no relacionadas.

Observa el frontmatter. La línea toolslimita estrictamente las capacidades del agente. La línea modelreduce el coste utilizando Sonnet. El modelo principal conserva las tareas de razonamiento complejo mientras el subagente trabaja de forma económica en el segundo plano.

Capa 5: Habilidades

Las skills empaquetan flujos de trabajo para que puedas invocarlos por nombre.

Una habilidad es una carpeta que contiene un archivo Markdown con frontmatter YAML. Puede incluir scripts Python, comandos Bash y accesorios de pruebas.

La arquitectura se basa en la divulgación progresiva. Los metadatos se cargan al inicio de la sesión. Las instrucciones solo se cargan cuando invocas la habilidad. Los recursos adicionales se cargarán únicamente cuando sean necesarios. Esto mantiene bajo el consumo de tokens incluso si instalas cincuenta habilidades.

Creamos una skill llamadanew-rag-eval .

YAML

---
name: new-rag-eval
description: Crear un nuevo caso de evaluación RAG a partir de un ejemplo,
  integrarlo en el arnés de evaluación, ejecutarlo y generar un resumen.
allowed-tools: Read, Write, Edit, Bash(uv run:*), Bash(git add:*)
---

Esta habilidad permite:

  • Leer una plantilla de evaluación.
  • Solicitar datos al usuario.
  • Crear un nuevo caso.
  • Ejecutar el arnés.
  • Analizar resultados.
  • Registrar notas si falla.
  • Añadir el archivo al escenario.

Y explícitamente:

  • No modifique la plantilla base.
  • No toca otras suites.
  • No abre solicitudes de extracción.

Capa 6: Hooks y determinismo

Los ganchos hacen que el agente sea más seguro y requiera menos supervisión humana.

Los eventos disponibles incluyen:

  • Inicio de sesión.
  • Envío de prompts.
  • Uso de herramientas.
  • Rechazos de seguridad.

La funcionalidad más importante añadida en abril de 2026 fue Permisos Diferidos. Un gancho previo a una herramienta puede devolver una decisión de tipo defer, pausando al agente durante una ejecución sin cabeza. Un humano revisa la acción y posteriormente la aprueba.

Configuramos dos hooks:

  • Formatear código automáticamente después de escribir archivos.
  • Bloquear cualquier git push dirigido a main.

JSON

{
  "hooks": {
    "pre-tool": {
      "command": "python3 .claude/hooks/pre_tool_guard.py"
    },
    "post-write": {
      "command": "uv run ruff format"
    }
  }
}

El script complementario intercepta cualquier empuje a la rama principal y devuelve:

JSON

{
  "permissionDecision": "defer",
  "reason": "Push to main requires human approval."
}

El gancho de formato es deliberadamente simple. Son probablemente los ganchos con mejor retorno sobre inversión que existen.

Capa 7: La pila de servidores

El Model Context Protocol conecta el agente con herramientas externas.

Muchos desarrolladores instalan servidores Quince y luego se preguntan por qué el agente se confunde. Cada servidor aporta esquemas de herramientas. Esos esquemas consumen tokens en cada interacción. Según la documentación de Anthropic, sin carga diferida, 50 herramientas pueden consumir entre 10.000 y 20.000 tokens por turno.

Necesita exactamente cinco servidores para una configuración seria:

  1. Gráfico de código con memoria persistente.
  2. GitHub.
  3. Sistema de archivos.
  4. Búsqueda web.
  5. Contexto documental versionado.

Ejemplo:

JSON

{
  "mcpServers": {
    "postgres-memory": {
      "command": "docker",
      "args": ["run", "-i", "mcp/postgres-memory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Si trabajas directamente contra producción, quizás añadas un sexto servidor para la base de datos. Mantén la lista pequeña.

Capa 8: Worktrees paralelos y automatización headless

Los worktrees son la forma de dejar de esperar a que el agente termine de escribir. Ejecutas un comando y obtienes: Rama, Worktree y una Sesión aislada.

Cada árbol de trabajo mantiene: Estado del editor, Procesos y Contexto.

Nuestro ingeniero paraleliza la tarea de citas:

  • Árbol de trabajo 1: lógica principal.
  • Worktree 2: evaluaciones.
  • Worktree 3: trazabilidad.
  • Worktree 4: PR.

Cada uno funciona de forma independiente.

La última pieza es el modo headless. Puedes ejecutar Claude Code dentro de un pipeline CI/CD y permitirle: Ejecutar evaluaciones, Corregir regresiones y Abrir PRs automáticamente. El artículo muestra un flujo de trabajo completo de GitHub Actions capaz de ejecutar evaluaciones nocturnas, corregir errores mínimos y abrir un borrador de PR.

La repetición

Ya tenemos la pila. Ahora veamos cómo se desarrolla una entrega de 90 minutos.

La sesión comienza. El ingeniero abre el proyecto y crea un worktree para la funcionalidad. La memoria y las reglas se cargan automáticamente. Los cinco servidores se conectan. El ingeniero entra en modo Deep Plan. El planificador genera:

Reducción

## Plan de implementación: Generación respaldada por citas
1. Modificar services/retrieval/search.py
2. Actualizar services/answer/generator.py
3. Crear una evaluación específica

La implementación comienza. El subagente retrieval-reviewerdetecta dos problemas:

Texto plano

Veredicto: blocker

- services/retrieval/search.py:
  Se generó manualmente un UUID.
- tests/retrieval/test_search.py:
  Falta @pytest.mark.integration.

El agente corrige ambos problemas. El segundo árbol de trabajo ejecuta la habilidad new-rag-eval. La ejecución final produce:

JSON

{
  "suite": "citations",
  "cases_run": 45,
  "grounded_citation_rate": {
    "previous": 0.82,
    "current": 0.98,
    "delta": "+0.16"
  },
  "unsupported_claims": {
    "previous": 12,
    "current": 0,
    "delta": "-12"
  },
  "status": "PASS"
}

La aprobación diferida detiene el push. El ingeniero revisa, aprueba y el PR se abre automáticamente.

Suelo y techo

Puedes arruinar esta configuración muy fácilmente.

No escribas un archivo de memoria enorme. No instale servidores quince. Los esquemas de herramientas no son gratuitos. No utilice la sesión principal para tareas que deban ejecutarse en subagentes. La exploración y la revisión pertenecen a contextos aislados.

Si no vas a implementar todo esto, al menos haz lo mínimo:

  • Crea un archivo de memoria corto e imperativo.
  • Escribe dos archivos de reglas asociados a rutas.
  • Añade un hook de formato.
  • Instale tres servidores: repositorio, sistema de archivos y documentación.

Oblígate a utilizar Plan Mode cuando exista riesgo de equivocarte. Agregue subagentes cuando una tarea se repita. Agregue habilidades cuando un flujo sea estable. Agrega worktrees cuando te descubras cambiando de rama varias veces por hora. Agrega el modo headless cuando quieras que el agente siga escribiendo el código mientras duermes.

Nuestro agente ahora navega perfectamente por el código. Sin embargo, todavía tiene dificultades con tareas de larga duración donde la ventana de contexto se llena lentamente de observaciones obsoletas.

En el próximo artículo veremos el nivel avanzado: Context Rot, Compaction y Tool-Result Clearing , técnicas para evitar que los agentes de larga ejecución terminen ahogándose en su propia memoria.

Gracias por leer Código en Casa.
Si esto te a ayudado y te sumo algo Dale un 👏 , compártelo con tu red o dejame un comentario para saber tu opinión.