Notas prácticas: Claude Code Agent Teams: Una guía práctica para crear un equipo
Guía paso a paso práctica: Claude Code Agent Teams: Una guía práctica para crear equipos: contratos, verificaciones y espacios para código adicional para equipos que implementan este patrón.
Esta guía reconstruye el proceso desde las materias primas hasta un sistema funcional para: Claude Code Agent Teams: Una guía práctica para crear un equipo de desarrolladores de IA. Se centra en pasos operativos, verificaciones explícitas y código que se puede incorporar directamente a un repositorio sin tener que adivinar su propósito. En la etapa de visión general, se deben definir las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema.
¿Qué son Claude Code Agent Teams?
Al trabajar en la etapa de “¿Qué es Claude Code?”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Haga un punto de control después de los pasos costosos. Resume no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
Team Lead
Backend
Frontend
Database
QA
Reviewer
Los equipos de agentes son diferentes de los subagentes
Cuando se trabaja con equipos de agentes en diferentes etapas, primero escribe el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiere unidades pequeñas y probables a scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad en lugar de a un proceso complicado. Haz una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Main Agent
↓
Subagent
↓
Result
Team Lead
│
┌──────────┼──────────┐
↓ ↓ ↓
Agent A ←→ Agent B ←→ Agent C
│ │ │
└──── Shared Tasks ───┘
Paso 1: Habilitar equipos de agentes
Al trabajar en la etapa Paso 1: Habilitar agente, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta etapa como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite completaciones parciales silenciosas. Haga puntos de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior. Al trabajar en la etapa Paso 1: Habilitar agente, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
cd my-project
claude
Paso 2: Comience con el proyecto, no con los agentes
La etapa del Paso 2 de comenzar desde cero funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Los intentos repetidos, los controles humanos y el manejo de correos no entregados forman parte del producto, no son mejoras posteriores. Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación después de las interrupciones.
Build complete authentication for this application.
Requirements:- PostgreSQL user model
- FastAPI authentication API
- React login and registration
- JWT authentication
- refresh tokens
- automated testsUse an Agent Team.Act as the Team Lead.
Inspect the repository, determine the workstreams,
identify dependencies and create the teammates required.
Paso 3: Deje que el líder del equipo desglose el proyecto
La Etapa 3 “Dejar que la etapa funcione” funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando una etapa falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
Authentication Design
Database Schema
API Implementation
Frontend UI
Integration
Testing
Security Review
Etapa 4: Identificar qué puede ejecutarse realmente en paralelo
En el Paso 4, identifique qué etapa funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso. En el Paso 4, identifique qué etapa funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.
Schema
↓
API
↓
Integration
Backend
Frontend
Test Planning
Documentation
Security Review
Paso 5: Crear compañeros de equipo especializados
En la etapa 5 de Crear fase especializada, defina las entradas, el responsable de la etapa y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la etapa desde un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
Team Lead
├── Backend Engineer
├── Frontend Engineer
├── Database Engineer
├── QA Engineer
└── Reviewer
Etapa 6: Asignar una responsabilidad clara a cada agente
En el Paso 6, para cada etapa se deben definir las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Es preferible utilizar unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Se debe incluir la aprobación humana en aquellas tareas que implican gastos o modificaciones en datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
Help with backend.
Backend Agent owns:
/api
/services
/auth
/pages
/components
/hooks
/schema
/migrations
/tests
Paso 7: Utilizar la lista de tareas compartida
En la etapa “Usar para el Paso 7”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas. Incluya la aprobación humana en aquellos procesos que generen gastos o modifiquen datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial. En la etapa “Usar para el Paso 7”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema.
[ ] Database schema
[ ] Registration API
[ ] Login API
[ ] Login UI
[ ] Registration UI
[ ] Integration tests
[ ] Security review
[x] Database schema
[x] Registration API
[x] Login API
[ ] Login UI
[ ] Registration UI
[ ] Integration tests
[ ] Security review
Paso 8: Permitir que los compañeros de equipo se comuniquen
Al trabajar en el Paso 8, primero escribe el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documenta tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Haz una verificación después de los pasos costosos. Resume no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
Frontend → Backend
What does POST /auth/login return?
{
"access_token": "...",
"refresh_token": "...",
"user": {
"id": 10,
"email": "user@example.com"
}
}
Paso 9: Mantener al líder del equipo enfocado en la coordinación
Al trabajar en el Paso 9 “Mantener la etapa”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a que los cambios posteriores en el código sean transparentes. Prefiera unidades pequeñas y verificables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Act primarily as the Team Lead.
Your responsibilities are:- understand the project
- decompose the work
- create tasks
- assign tasks
- identify dependencies
- monitor blockers
- coordinate teammates
- review completed work
- manage integration
- verify the final solutionDelegate implementation whenever appropriate.
Paso 10: Permitir que los agentes asuman nuevos trabajos
Al trabajar en el Paso 10 “Permitir que los agentes se preparen”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite completaciones parciales silenciosas. Haga puntos de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior. Al trabajar en el Paso 10 “Permitir que los agentes se preparen”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.
Claim Task
↓
Work
↓
Complete
↓
Check Backlog
↓
Claim Next Task
Create an initial task backlog.
Agents should claim available tasks that match their role.When a teammate finishes its current task,
it should check the shared task list and claim
the next appropriate unblocked task.
Paso 11: Hacer explícitas las dependencias
La fase del Paso 11 de hacer explícitas las dependencias funciona mejor cuando se trata como una superficie medible. Capture una transcripción de éxito, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo e interrumpen la continuación después de las interrupciones.
API Contract
Backend
Frontend
Integration Tests
API Contract
/ \
Backend Frontend
\ /
Integration
Identify task dependencies before work begins.
Do not allow agents to start blocked tasks.When a dependency is completed,
unblock the appropriate downstream task.
Paso 12: Agregar un revisor independiente
El paso 12, “Añadir una etapa”, funciona mejor cuando se trata como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
Developers
↓
Reviewer
↓
Fixes
Create a Senior Code Reviewer teammate.
Do not use this teammate for feature development initially.Its responsibility is to review completed work for:- correctness
- architecture
- security
- duplicated logic
- error handling
- maintainability
- performanceWhen problems are identified,
create follow-up tasks for the appropriate developer.
Paso 13: Añadir control de calidad independiente
La etapa 13 “Agregar fase independiente” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso. La etapa 13 “Agregar fase independiente” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación; los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.
Developer
↓
Build
↓
QA
↓
Failure
↓
Fix
↓
Retest
Paso 14: No cree demasiados agentes
En el Paso 14, no se debe planificar nada; primero se deben definir las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
Team Lead
Backend
Frontend
QA
Reviewer
Paso 15: Definir qué significa “terminado”
En el Paso 15, Definir qué etapa corresponde, se deben especificar los insumos, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Es preferible utilizar unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Se debe incluir la aprobación humana en aquellas tareas que implican gastos o modificaciones en los datos de producción. La configuración en tiempo de compilación no equivale a una solución completa desde el punto de vista empresarial.
Implementation complete
Tests passing
Build passing
Lint passing
Type checking passing
Integration working
Reviewer findings resolved
Documentation updated
Write code
Deliver working software
Paso 16: Permitir que el líder del equipo realice la integración final
En el Paso 16, antes de modificar el código, se debe definir la etapa, los datos de entrada, el responsable del paso y los criterios de finalización. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace cualquier completación parcial silenciosa. Incluya la aprobación humana en aquellas operaciones que involucren gastos o cambios en datos de producción. La conexión durante la compilación no equivale a una implementación completa desde el punto de vista empresarial. En el Paso 16, antes de modificar el código, se debe definir la etapa, los datos de entrada, el responsable del paso y los criterios de finalización. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema.
Review changes
↓
Run tests
↓
Build
↓
Check integration
↓
Find failures
↓
Delegate fixes
↓
Retest
↓
Ship
When teammates finish:
1. Inspect all changes.
2. Review the final diff.
3. Resolve inconsistencies between workstreams.
4. Run the full test suite.
5. Run linting.
6. Run type checking.
7. Verify the frontend builds.
8. Verify the backend starts.
9. Check remaining tasks.
10. Assign fixes when failures are discovered.
11. Re-run verification.
12. Only then declare the project complete.
Un prompt reutilizable para Agent Teams
Al trabajar en la etapa de Agent Teams reutilizable, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Almacene en caché las instrucciones estables del sistema y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de agotamiento.
Use Claude Code Agent Teams for this task.
You are the Team Lead.First inspect the repository and understand the existing architecture.Then:1. Break the objective into a task graph.
2. Identify dependencies between tasks.
3. Identify which tasks can run in parallel.
4. Create only the teammates that are genuinely useful.
5. Give every teammate a specialized role.
6. Give every teammate clear ownership.
7. Avoid multiple agents modifying the same files unless necessary.
8. Use the shared task list to coordinate work.
9. Allow teammates to communicate when information is required
from another workstream.
10. Let teammates claim appropriate unblocked work after finishing
their current tasks.
11. Add independent QA and review tasks.
12. Create follow-up tasks when problems are discovered.
13. Continue until all required tasks are complete.
14. Run tests, builds, linting and type checks.
15. Review the final diff yourself.
16. Do not declare completion while known issues remain.Act primarily as Team Lead.Delegate implementation whenever appropriate instead of
performing all work yourself.
Cuándo tiene sentido usar Agent Teams
Cuando se trabaja en la fase de creación de equipos de agentes, primero escribe el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiere unidades pequeñas y probables a scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haz una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Fix this validation bug.
El cambio más importante
Al trabajar en la etapa de “The bigger shift”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta etapa como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina las comprobaciones de éxito y evite completaciones parciales silenciosas. Haga puntos de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior. Al trabajar en la etapa de “The bigger shift”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.
AI Coding Assistant
AI Developer
AI Agents
AI Development Team
Qué aprender a continuación
La etapa de “Qué aprender a continuación” funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Claude Code
↓
Subagents
↓
Agent Teams
↓
Shared Tasks
↓
Agent Communication
↓
Parallel Development
↓
QA + Reviewer Agents
↓
Autonomous Development Teams
Lista de verificación operativa
La etapa de la lista de verificación operativa funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance.
Registra los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Ver la información sobre costos desde el principio evita facturas inesperadas cuando el camino pasa de entornos de demostración a entornos compartidos.
Mantén el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y dificultan la reanudación después de interrupciones.
Añade una prueba de funcionamiento básica que ejecute la ruta crítica en CI con configuraciones fijas, y no con APIs pagadas en tiempo real, siempre que lo permitan los presupuestos.
Mantén la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un único lugar que los operadores puedan auditar sin tener que leer todo el grafo.
Mantén el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y dificultan la reanudación después de interrupciones.
Antes de promocionar el stack, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos de reversión. Los entornos compartidos necesitan límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sólida a demostraciones ingeniosas pero puntuales.
Nota por lotes para b860522250c5: mantenga las claves del proveedor fuera del repositorio, establezca un límite máximo para tokens por sesión y almacene las transcripciones junto a los fixtures de evaluación para que los cambios posteriores en los modelos sigan siendo comparables.
Lecturas relacionadas
- Notas prácticas: equipos de agentes Claude Code: cuándo y cómo pasar a multi-agent — Guía paso a paso de las Notas prácticas: equipos de agentes Claude Code: cuándo y cómo pasar a multi-agent, incluyendo contratos, verificaciones y espacios para código adicional para equipos que implementan este patrón.