# 18 consejos para el desarrollo agéntico con Claude Code > 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-11-05 · https://joseobregon.me/es/blog/agentic-development-tips/ 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. ## 1. Primero 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` (o `AGENTS.md`) conciso en la raíz (y en subdirectorios clave si es un monorepo) y enlaza desde ahí toda la documentación clave 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 es. - **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 es el trabajo. 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** (clase Mythos) | Arquitectura compleja, refactors a escala de repo, incidentes críticos, auditorías de seguridad, problemas ambiguos o sin una solución clara | > Modelos vigentes a noviembre de 2026. No hace falta usar un solo modelo por tarea: puedes planificar con Opus o Fable e implementar con Sonnet. ## 3. Planifica antes de implementar Usa el **modo plan** para que Claude explore el repo, identifique los archivos afectados y los casos borde, valide hipótesis y discuta trade-offs sin modificar archivos. Iterar 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 responde: - **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, funciona como memoria persistente que sobrevive a cada limpieza de contexto. ## 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 al cerrar una subtarea o al pasar de la spec a la implementación. 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` (punto 10). ## 6. 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, exige un body de 2 a 4 líneas con el **qué** y el **por qué**: es lo que hace útiles el `git log`, el `git bisect` y los changelogs automáticos. Atribuye siempre el commit y la PR a Claude y al modelo exacto usado con el trailer `Co-Authored-By`, que GitHub muestra como coautor del cambio. Esta trazabilidad permite auditar el código con contexto y medir 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 chicas 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á 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 asignadas para tener un backlog ordenado y **vivo**, que refleja en todo momento qué se está haciendo y qué viene después. Claude puede mantenerlo al día moviendo issues de estado 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. Con `anthropics/claude-code-action`, basta con mencionar a `@claude` en un issue para que lo implemente y abra la PR, o en una PR para que aplique los cambios pedidos en la revisión. ## 9. 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ó. Lo recomendable es tener una skill específica 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. ## 10. 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. Ten en cuenta que cada worktree necesita sus propias dependencias instaladas y puertos distintos si levantas servidores. ## 11. Empaqueta el conocimiento repetitivo en skills En vez de repetir prompts complejos o inflar el `CLAUDE.md` con casos puntuales, conviértelos en skills: crear migraciones seguras, auditar vulnerabilidades OWASP, diseñar componentes según tu design system, preparar un release, hacer un code review (punto 9), crear PRs o crear issues. Claude las carga solo cuando la tarea lo requiere, ahorrando contexto y estandarizando la calidad del equipo. Además, las skills le aportan **determinismo** al flujo: en lugar de improvisar un procedimiento distinto cada vez, Claude sigue siempre los mismos pasos, plantillas y criterios, lo que reduce las alucinaciones y hace los resultados más predecibles. ## 12. Automatiza el mantenimiento con tareas programadas - **Monitoreo:** con `/loop`, Claude Code vigila procesos asíncronos, como los checks de CI de una PR, y actúa apenas 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 periódicamente clasifique y etiquete los issues nuevos, detecte duplicados y proponga prioridades, para que el backlog del punto 8 se mantenga ordenado y vivo 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, usa GitHub Actions con `anthropics/claude-code-action` y un disparador `schedule`. ## 13. Automatiza los checks en pre-commit, pre-push y GitHub Actions 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. ## 14. 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 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 determinística de todo el flujo. ## 15. 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. ## 16. Trata el contenido externo como no confiable Si Claude lee issues, PRs, comentarios o páginas web escritas 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. ## 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 está vivo y 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 podrías 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, medición 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.