# 18 consejos de desarrollo agéntico con Claude > Delegar trabajo real en un agente como Claude Code exige disciplina. 18 consejos para mantener la calidad del código y el control sin perder velocidad. José Obregón · 2026-10-01 · https://joseobregon.me/es/blog/consejos-desarrollo-agentico-claude-code/ Delegar trabajo real de ingeniería en un agente como **Claude Code**, con **GitHub** como eje del flujo, exige disciplina y estructura. Estos 18 consejos te ayudan a mantener la calidad del código y el control de la arquitectura sin perder velocidad. ## Preparar ### 1. Empieza por el harness y el contexto del repositorio Claude Code es tan bueno como el contexto y las herramientas que le das. Antes de pedirle la primera funcionalidad: - **Contexto explícito:** documenta arquitectura, convenciones, limitaciones, preferencias, comandos frecuentes, herramientas, skills y reglas de negocio. Mantén un `CLAUDE.md` conciso (que puede importar un `AGENTS.md` con `@AGENTS.md`) en la raíz (y en subdirectorios clave si es un monorepo) y enlaza desde ahí toda la documentación importante del proyecto, para que Claude la lea solo cuando la necesite. - **Herramientas y verificaciones:** dale a Claude el conocimiento y los permisos para ejecutar scripts, chequeos de tipos, linters, formatters, tests y skills. Así puede comprobar por sí mismo si rompió algo e iterar hasta entregarte una solución limpia. Estas verificaciones le aportan determinismo a un proceso que, por naturaleza, no lo tiene. - **Integraciones:** con `gh` o el servidor MCP de GitHub, Claude trabaja directamente sobre issues, PRs, revisiones y ejecuciones de CI. Suma otros servidores MCP según tu stack: Slack, Gmail, Confluence, Jira, tu base de datos o tu herramienta de monitoreo de errores. - **Permisos:** dale a Claude la mayor autonomía posible en un entorno aislado; cuantas menos confirmaciones necesite, más fluido y productivo será el trabajo. Empieza por el [modo automático](https://code.claude.com/docs/es/permission-modes), en el que un clasificador revisa por ti las acciones de riesgo, y suma [`/sandbox`](https://code.claude.com/docs/es/sandboxing) para aislar los comandos de shell. Eso sí, con criterio. ### 2. Elige el modelo según la tarea | Modelo | Cuándo usarlo | | ---------- | ------------------------------------------------------------------------------------------------------------------- | | **Haiku** | Tareas simples y repetitivas, refactors mecánicos, consultas rápidas sobre el codebase | | **Sonnet** | Tareas bien acotadas, cambios de UI, implementación a partir de specs muy detalladas | | **Opus** | Desarrollo más complejo, sesiones largas, comprensión profunda del codebase | | **Fable** | Arquitectura compleja, refactors a escala de repo, incidentes críticos, problemas ambiguos o sin una solución clara | > Modelos vigentes a octubre de 2026. No hace falta usar un solo modelo por tarea: puedes planificar con Opus o Fable e implementar con Sonnet. El modelo no es lo único que define el costo: usa [`/effort`](https://code.claude.com/docs/es/model-config) para fijar cuánto razona Claude, más para los casos difíciles y menos para las idas y vueltas rápidas, y revisa [`/usage`](https://code.claude.com/docs/es/costs) para ver en qué se van tus tokens. ## Planificar ### 3. Planifica antes de implementar Usa el **modo plan** para que Claude explore el repo, identifique los archivos afectados y los casos borde, valide supuestos y discuta trade-offs sin modificar nada. Iterar sobre las ideas y tomar decisiones junto con Claude en esta fase te ahorrará tiempo, dinero y esfuerzo. ### 4. Convierte el plan en una spec (`.md`) Antes de implementar, materializa lo acordado en un archivo (por ejemplo, `specs/feature-x.md`). Una buena spec cubre: - **Qué:** el objetivo concreto. - **Para qué:** el problema que resuelve y el valor que aporta. - **Para quién:** usuarios, agentes, servicios o equipos afectados. - **Guardrails:** límites y restricciones; qué no se debe tocar, decisiones ya tomadas, dependencias no permitidas y requisitos de seguridad o rendimiento. - **Criterios de aceptación:** un checklist verificable para dar la tarea por terminada. La spec es un documento **vivo**: si durante la implementación cambia una decisión, aparece un caso borde o se ajusta un criterio, Claude debe actualizar la spec en ese momento. Una spec desactualizada confunde más que no tener ninguna. Además de alinear al equipo, la spec funciona como memoria persistente que sobrevive a cada limpieza de contexto. ## Construir ### 5. Gestiona tu ventana de contexto Una sesión larga que mezcla tareas acumula intentos fallidos y logs viejos que degradan la atención del modelo, aumentan las alucinaciones y encarecen cada mensaje. Limpia el contexto con `/clear` al cerrar una subtarea o al pasar de la spec a la implementación, o usa `/compact` para resumirlo si necesitas seguir en la misma tarea. Para no perder el control de la ventana de contexto, usa `/btw` para preguntas rápidas que no necesitan quedar en el historial, delega la exploración y la investigación en subagentes (trabajan con su propio contexto y solo devuelven el resultado) y separa las tareas en paralelo con `git worktree` (consejo 9). Si Claude se desvía, pulsa `Esc` para detenerlo sin perder lo hecho, o usa [`/rewind`](https://code.claude.com/docs/es/checkpointing) para devolver el código, la conversación o ambos a un punto anterior. Tras dos correcciones fallidas, no intentes una tercera: ejecuta `/clear` y escribe un mejor prompt con lo que aprendiste. ### 6. Escribe commits con contexto y trazabilidad Con la velocidad a la que Claude genera código, el historial de Git pasa a ser una de las principales fuentes de contexto del equipo. Además de [Conventional Commits](https://www.conventionalcommits.org/es/v1.0.0/), que alimentan los changelogs automáticos, exige un cuerpo de 2 a 4 líneas con el **qué** y el **por qué**: es lo que hace útil el `git log`. Atribuye siempre el commit a Claude y al modelo exacto usado con el trailer `Co-Authored-By`, para que GitHub lo muestre como coautor del cambio. Esta trazabilidad permite auditar el código con contexto y comparar qué modelos rinden mejor en cada parte del stack. ### 7. Exige PRs detalladas y siempre actualizadas Delega en Claude la redacción de la PR: problema, enlace a la spec, decisiones técnicas y pasos para probar. Si durante la revisión surgen nuevos commits, pídele que actualice la descripción para que refleje el estado real antes del merge. Pide PRs pequeñas e incrementales: un agente puede generar diffs enormes que nadie revisa de verdad. Si un cambio crece demasiado, divídelo en varias PRs. Las PRs son una parte fundamental del contexto que le das a Claude: cuando retoma un módulo, ahí encuentra qué se cambió, por qué y qué alternativas se descartaron. ### 8. Vincula cada PR a un issue de GitHub Ningún cambio debería nacer en el vacío: cada requerimiento, bug o mejora nace como issue y cada PR lo cierra. De esta forma, cualquiera puede ir del commit a la PR y de ahí al issue, donde están el pedido formal, los responsables, la prioridad y toda la discusión que llevó a la decisión: trazabilidad completa de punta a punta. Organiza los issues en un tablero de **GitHub Projects** con estados y prioridades para tener un backlog ordenado que refleje en todo momento qué se está haciendo y qué viene después. Claude puede mantenerlo al día cambiando el estado de los issues y ajustando prioridades por ti. Así como los commits y las PRs le dan a Claude el contexto de lo que ya se hizo, los issues le dan el contexto de lo que viene. Si configuras [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action), basta con mencionar a `@claude` en un issue para que implemente el cambio en una rama y te deje el enlace para abrir la PR, o en una PR para que aplique los cambios pedidos en la revisión. ### 9. Trabaja en paralelo con `git worktree` Un worktree por rama te permite correr varias sesiones de Claude Code a la vez sin `git stash` ni esperas: mientras Fable hace un refactor pesado en una rama, en otra resuelves un bug rápido con Sonnet. Con [`claude -w feature-x`](https://code.claude.com/docs/es/worktrees), Claude Code crea el worktree e inicia la sesión en él. Ten en cuenta que cada worktree necesita sus propias dependencias instaladas y puertos distintos si levantas servidores. ### 10. Empaqueta el conocimiento repetitivo en skills En vez de repetir prompts complejos o inflar el `CLAUDE.md` con casos puntuales, conviértelos en [skills](https://code.claude.com/docs/es/skills): crear migraciones seguras, auditar vulnerabilidades OWASP, diseñar componentes según tu design system, preparar un release, hacer un code review (consejo 11), crear PRs o issues. Claude las carga solo cuando la tarea lo requiere, ahorrando contexto y estandarizando la calidad del equipo. Además, las skills le aportan **consistencia** al flujo: en lugar de improvisar un procedimiento distinto cada vez, Claude parte de los mismos pasos, plantillas y criterios, lo que hace los resultados más predecibles. Siguen siendo instrucciones, no garantías: para lo que no puede fallar, usa hooks (consejo 16). ## Revisar ### 11. Haz siempre un code review Nunca des por bueno el primer código que genera Claude. Ejecuta la revisión en una ventana de contexto limpia, sin el sesgo de la sesión en la que se implementó el código. [`/code-review`](https://code.claude.com/docs/es/code-review-local) hace justo eso: revisa el diff en un subagente que nunca vio tu conversación. Lo recomendable es tener además una skill propia de code review que verifique siempre los mismos puntos: seguridad, rendimiento, lógica, manejo de errores, limpieza del código y cumplimiento de las convenciones del repo y de la spec. También es buena idea sumar una revisión con otro modelo: si implementaste con Sonnet u Opus, revisa con Fable. Un modelo distinto detecta errores que el original tiende a pasar por alto. ### 12. Exige pruebas E2E reales No confíes solo en los tests unitarios y la cobertura de código: los agentes tienden a abusar de los mocks y dejan tests en verde aunque la integración real esté rota. Exige pruebas E2E (por ejemplo, con Playwright) sobre los flujos críticos. Son la red de seguridad para refactorizar rápido sin romper el negocio. ### 13. Trata el contenido externo como no confiable Si Claude lee issues, PRs, comentarios o páginas web escritos por terceros, ese contenido puede incluir instrucciones maliciosas (prompt injection). Limita lo que Claude puede hacer cuando procesa contenido público y revisa cada dependencia nueva que agregue. ## Automatizar ### 14. Automatiza el mantenimiento con tareas programadas - **Monitoreo:** con `/loop`, Claude Code repite un prompt a intervalos mientras la sesión está abierta; así puede revisar procesos asíncronos, como los checks de CI de una PR, y actuar cuando terminan, ya sea corrigiendo un fallo o avanzando al siguiente paso. - **Mantenimiento periódico:** deja que Claude revise las alertas de Dependabot, la auditoría de dependencias de terceros y las alertas de code scanning, y que **abra la PR con el fix** lista para tu revisión. - **Triage del backlog:** deja que Claude clasifique y etiquete periódicamente los issues nuevos, detecte duplicados y proponga prioridades, para que el backlog del consejo 8 se mantenga ordenado sin esfuerzo manual. - **Documentación al día:** deja que Claude revise periódicamente que el `CLAUDE.md`, las specs y la documentación reflejen el estado real del código, y que abra una PR con las correcciones. Para las tareas periódicas que no dependen de una sesión abierta, usa GitHub Actions con `anthropics/claude-code-action` y un disparador `schedule`, o [`/schedule`](https://code.claude.com/docs/es/routines) (en research preview), que las ejecuta en la nube de Anthropic aunque tengas la laptop cerrada. ### 15. Automatiza los checks en pre-commit, pre-push y GitHub Actions Aquí, `pre-commit` y `pre-push` son hooks de Git, no de Claude Code (consejo 16). Cada barrera le da a Claude feedback inmediato para autocorregirse antes de que el error llegue a revisión: - **`pre-commit` y `commit-msg` (segundos):** formateo y lint sobre los archivos modificados, escaneo de secretos y validación de Conventional Commits. - **`pre-push`:** chequeo de tipos global, build y tests unitarios afectados. - **GitHub Actions (el guardián final):** análisis estático profundo, cobertura, lint de todo el repo y la suite completa en cada PR. Márcalos como required checks en la protección de `main` para que nada se mergee en rojo. Si algo falla, Claude puede leer los logs del run y proponer el fix. Cuanto antes se detecta un defecto, más rápido y más barato es solucionarlo. ### 16. Usa hooks para lo que no puede fallar Las reglas del `CLAUDE.md` son instrucciones que el modelo puede pasar por alto; los [hooks de Claude Code](https://code.claude.com/docs/es/hooks-guide) se ejecutan siempre. Úsalos para formatear y validar después de cada edición, proteger archivos sensibles o correr chequeos antes de dar una tarea por terminada. Son la pieza más determinista de todo el flujo. ## Mantener el control ### 17. Mejora tu flujo continuamente El desarrollo agéntico cambia semana a semana. Revisa periódicamente qué falla con más frecuencia, dónde se desperdician tokens y qué tareas todavía requieren intervención manual, y aplica las correcciones necesarias en el `CLAUDE.md`, las skills o las automatizaciones. El contexto de Claude Code nunca está terminado: mejora junto con el equipo. ### 18. La responsabilidad sigue siendo tuya Claude implementa, pero el código que llega a `main` es tuyo. Entiende cada decisión importante y no mergees nada que no puedas defender en una revisión. La autonomía del agente funciona porque al final del flujo hay alguien con criterio. ## Conclusión Dominar el desarrollo agéntico no es delegar a ciegas, sino diseñar un sistema: ingeniería de contexto, trazabilidad, documentación, skills, automatizaciones y mejora continua. Pero, por sobre todas las cosas: **criterio**. Así, la velocidad de Claude Code juega siempre a favor de la calidad y la mantenibilidad del proyecto.