Llevo meses trabajando en Archivo Final, una plataforma de evaluación de manuscritos con IA construida sobre Django y Vertex AI (Gemini). Es un proyecto con backend complejo, pipeline de IA, deploy en Cloud Run y un solo desarrollador: yo.
En algún momento dejé de usar Claude Code como un “asistente que autocompleta” y empecé a tratarlo como un equipo. No es una metáfora bonita — es una arquitectura real con agentes especializados, aislamiento por feature, herramientas conectadas via MCP y un flujo que pasa por GitHub de punta a punta.
Y en esas cosas que tiene el emprendedurismo apareció Joan, un colega con el que habia trabajado y que se acercó por voluntad propia a colaborar con el proyecto. Me mostró su workflow, contrastamos con el mio(yo estaba usando openspec) y concluimos un monton de cosas hasta que dimos con el que funciona de maravilla.
Este artículo documenta exactamente cómo funciona ese workflow hoy. Sin filtros. Con configuración real, código y las lecciones que he aprendido usándolo en producción.
El problema: un proyecto complejo, un solo desarrollador
Archivo Final no es un CRUD sencillo. Es un sistema Django con:
- Pipeline asíncrono de evaluación con Gemini (Vertex AI)
- Clasificación de géneros literarios con THEMA v1.6
- Procesamiento de manuscritos PDF de hasta 300 páginas
- Cloud Tasks para jobs asíncronos
- Deploy automatizado con Cloud Build → Cloud Run
- Base de datos PostgreSQL en Cloud SQL
Cada feature nueva toca backend, IA, infraestructura, tests y UI. Sin un equipo, el riesgo de perder contexto entre tareas es alto. La pregunta era: ¿cómo puedo mantener la calidad de un equipo multidisciplinar trabajando solo?
La respuesta: un sistema de agentes especializados coordinados por Claude Code.
La arquitectura: 9 agentes especializados
En .claude/agents/ tengo definidos 9 agentes, cada uno con un rol concreto. No son “prompts bonitos” — son archivos markdown con instrucciones detalladas, modelo asignado y output esperado.
Agentes de planificación (solo generan documentación)
| Agente | Rol | Output |
|---|---|---|
backend-developer |
Diseña features Django | .claude/doc/{feature}/backend.md |
vertex-ai-architect |
Diseña integración Gemini | .claude/doc/{feature}/vertex-ai-plan.md |
mlops-engineer |
Diseña pipelines Docker/Cloud Build | .claude/doc/{feature}/mlops-engineer-plan.md |
ui-ux-analyzer |
Analiza templates y UX | .claude/doc/{feature}/ui_analysis.md |
sentry-pipeline-engineer |
Configura error tracking | .claude/doc/{feature}/sentry-plan.md |
Agentes de implementación
| Agente | Rol |
|---|---|
backend-test-engineer |
Escribe tests pytest (TDD) |
Agentes de coordinación y validación
| Agente | Rol |
|---|---|
project-coordinator |
Analiza issues, selecciona agentes, coordina |
qa-criteria-validator |
Valida con Playwright, comenta en PRs |
django-config-migrations |
Experto en migraciones (modelo Opus) |
La separación es clave: los agentes de planificación nunca tocan código. Generan planes en markdown. La implementación es un paso separado y consciente. Esto evita que un agente “creativo” rompa cosas en producción.
Ejemplo: definición de un agente
Cada agente se define en un archivo .md dentro de .claude/agents/. Esto es un fragmento del backend-developer.md:
Role: Senior Django backend developer for Archivo Final
Model: Sonnet
Output: .claude/doc/{feature_name}/backend.md
You are a planning-only agent. You NEVER write code directly.
You analyze the codebase, understand the current architecture,
and produce a detailed implementation plan that another agent
or the developer can execute.
Lo importante: el agente tiene contexto del proyecto (arquitectura, patrones, convenciones), un modelo asignado (Sonnet para la mayoría, Opus para migraciones críticas) y un output definido.
Worktrees: aislamiento real por feature
Cada feature se desarrolla en un git worktree independiente. No es un branch — es un directorio separado con su propia copia del repo.
# Estructura
.trees/
├── feature-issue-42/ # Worktree para issue #42
├── feature-issue-55/ # Worktree para issue #55
└── feature-issue-61/ # Worktree para issue #61
Por qué worktrees y no branches
Con branches, cada git checkout cambia los archivos del directorio de trabajo. Si tienes un agente trabajando en una feature y necesitas revisar otra, pierdes contexto. Con worktrees:
- Cada feature tiene su directorio independiente
- Puedo trabajar en múltiples features en paralelo
- No hay riesgo de contaminar cambios entre features
- El worktree se limpia al terminar, sin residuos
El guard hook: protección contra ediciones cruzadas
Tengo un hook PreToolUse que bloquea cualquier edición en el repo principal cuando hay worktrees activos:
# .claude/scripts/worktree-guard.sh
# Checks .claude/.worktrees_active/ for sentinel files
# Blocks edits in main working tree when worktrees are active
# Always allows edits in .claude/ directory
Cada worktree activo registra un archivo sentinel en .claude/.worktrees_active/. El guard verifica que las ediciones se hagan dentro del worktree correcto. Si intento editar un archivo del repo principal mientras tengo un worktree abierto, Claude Code se detiene y me avisa.
10 MCP servers: el arsenal de herramientas
Los Model Context Protocol (MCP) servers son lo que convierte a Claude Code en algo más que un chatbot. En mi .mcp.json tengo configurados 10:
| MCP Server | Para qué lo uso |
|---|---|
| context7 | Consultar docs actualizados de Django, Python, librerías |
| sequentialthinking | Descomponer problemas complejos paso a paso |
| playwright | Tests E2E, validación visual, screenshots |
| concurrent-browser | Hasta 20 instancias de browser en paralelo |
| memory | Grafo de conocimiento persistente entre sesiones |
| github | Issues, PRs, code search, reviews — todo via API |
| opik | Evaluación y tracing de prompts LLM |
| sentry | Monitorización de errores en producción |
| logfire | Logs estructurados y trazas |
| drawio | Generación de diagramas de arquitectura |
Los más transformadores para este workflow:
context7 es obligatorio. Antes de que cualquier agente proponga un plan, debe verificar versiones y APIs actualizadas via context7. Esto evita que genere código para versiones antiguas de Django o Sentry SDK.
github cambia todo el flujo de trabajo. Los agentes pueden leer issues, crear PRs, comentar reviews y verificar checks de CI — sin que yo tenga que copiar y pegar información. El @project-coordinator lee un issue de GitHub y genera un plan de trabajo automáticamente.
memory permite persistir contexto entre sesiones. Decisiones de arquitectura, patrones del proyecto, reglas que vamos descubriendo — todo queda en un grafo de conocimiento accesible para cualquier agente.
Comandos custom: automatización del flujo
En .claude/commands/ tengo 14 comandos personalizados. Los más importantes:
/worktree {issue_number}
El comando principal. Dado un número de issue de GitHub:
- Crea un git worktree en
.trees/feature-issue-{N}/ - Registra el sentinel en
.claude/.worktrees_active/ - Lanza
@project-coordinatorpara analizar el issue - El coordinador selecciona qué agentes necesita
- Los agentes se ejecutan en paralelo (si no hay conflictos de archivos) o secuencialmente
- Cada agente genera su plan/output en
.claude/doc/{feature}/
/start-working-on-issue-new
El flujo completo de extremo a extremo:
– Worktree → análisis → implementación → tests → PR
– Ejecuta tests constantemente para feedback rápido
– Se mantiene en el loop del PR hasta que el deploy en Cloud Build sea exitoso
– Si un check de CI falla, analiza el error y corrige
/implement-feedback
Cuando un PR recibe comentarios de review:
– Lee los comentarios del PR via GitHub MCP
– Aplica los cambios con enfoque TDD
– Ejecuta tests hasta que todo esté verde
– Pushea la corrección
Sesiones compartidas: la comunicación entre agentes
Cada feature tiene un único archivo de sesión en .claude/sessions/. Es el canal de comunicación entre agentes:
.claude/sessions/context_session_{feature_name}.md
El flujo funciona así:
- Cada agente lee TODO el documento antes de empezar (contexto completo)
- Cada agente rellena SU sección al terminar
- Avanza el campo de Estado (backlog → analysis → implementation → review → done)
- Los deliverables detallados van a
.claude/doc/{feature}/
La sesión es el resumen ejecutivo — lo mínimo para que el siguiente agente arranque con contexto. Incluye: descripción del problema, diagnóstico, archivos analizados, plan de implementación, métricas de éxito y riesgos.
GitHub como centro de operaciones
GitHub no es solo donde vive el código — es el hub que conecta todo el workflow:
Issues como punto de entrada
Todo empieza con un issue de GitHub. El comando /worktree o /start-working-on-issue-new toma el número de issue y arranca todo el flujo. El @project-coordinator usa el MCP de GitHub para leer el issue, entender los requisitos y planificar.
PRs como punto de control
Cuando la implementación está lista, se crea un PR automáticamente via gh pr create. El PR incluye:
– Descripción generada a partir de los cambios reales (no genérica)
– Referencia al issue original
– Los checks de CI de Cloud Build se ejecutan automáticamente
Reviews y feedback
El @qa-criteria-validator puede comentar directamente en el PR con los resultados de validación. Cuando recibo feedback humano en un PR, el comando /implement-feedback lee los comentarios via GitHub MCP y aplica las correcciones.
El loop de CI
Después de crear un PR, el agente se queda en un loop:
1. Verifica el estado de los checks con gh pr checks
2. Si algo falla, analiza los logs de Cloud Build
3. Corrige y pushea
4. Repite hasta que todos los checks estén verdes
Hooks y safety: el cinturón de seguridad
Con agentes que pueden ejecutar comandos, la seguridad no es opcional. Mi configuración incluye varias capas:
Permisos explícitos en settings.json
{
"deny": [
"rm -rf",
"git push --force",
"git rebase",
"git reset",
"cat .env"
]
}
Hookify: reglas de seguridad declarativas
6 reglas que bloquean operaciones destructivas:
– block-destructive-git — No force push, no reset hard, no clean
– block-dangerous-rm — No rm -rf
– block-drop-database — No DROP TABLE/DATABASE
– block-migration-delete — No borrar archivos de migración
– block-push-main — No push directo a main
– warn-sensitive-files — Aviso al editar archivos sensibles
El worktree guard
El hook que mencioné antes: bloquea ediciones fuera del worktree activo. Es la pieza más crítica porque previene que un agente modifique archivos en el directorio equivocado.
Lo que he aprendido
Después de meses usando este workflow, estas son las lecciones más importantes:
Funciona mejor de lo que esperaba. La separación entre agentes de planificación e implementación es la decisión más acertada. Tener un plan revisable antes de tocar código reduce errores drásticamente.
Los worktrees son imprescindibles. Antes de implementarlos, los conflictos de contexto entre features eran mi mayor fuente de frustración. Los worktrees + el guard hook eliminaron el problema por completo.
Los MCPs transforman el workflow. Sin el MCP de GitHub, tendría que copiar y pegar información constantemente entre el navegador y el terminal. Con él, el flujo es continuo.
La documentación automática tiene valor real. Al principio pensé que generaría documentos que nadie leería. Pero cuando vuelvo a una feature semanas después, tener el plan, el diagnóstico y la auditoría de seguridad documentados es invaluable.
No todo es perfecto. Los agentes a veces generan planes demasiado ambiciosos que hay que recortar. El memory MCP pierde contexto si no se mantiene activamente. Y los hooks de seguridad, aunque necesarios, a veces bloquean operaciones legítimas que requieren un bypass manual.
El coste de configuración es alto, pero se amortiza rápido. Montar todo esto llevó tiempo. Pero ahora, cada nueva feature arranca con un workflow probado que me ahorra horas de trabajo manual.
Conclusión
Este workflow no es teoría — es el sistema que uso cada día para construir un producto real en producción. No es perfecto, pero ha cambiado fundamentalmente cómo trabajo como desarrollador individual.
La clave no está en tener muchos agentes ni muchos MCPs. Está en la coordinación: que cada pieza sepa cuándo actuar, qué información necesita y dónde dejar su output. Es orquestación, no automatización ciega.
Si estás pensando en escalar tu workflow con Claude Code, empieza por lo básico: un buen CLAUDE.md, un par de agentes bien definidos y un MCP de GitHub. El resto lo puedes ir añadiendo según lo necesites.
Todo el código de configuración que ves aquí está en repositorios privados de Archivo Final, pero los patrones son replicables. Si quieres que profundice en alguna parte concreta, escríbeme.
