Manual de Metodología de Desarrollo Híbrido: Humanos y Agentes IA (2026)

Esta guía establece el estándar operativo para los desarrolladores de la startup. Su objetivo central es maximizar la eficiencia y seguridad en la escritura de código, integrando herramientas de Inteligencia Artificial sin perder el control sobre la arquitectura del producto.

1. Gestión Cognitiva: Thinking Levels y Orquestación

Para maximizar la productividad sin disparar los costos ni los tiempos de respuesta de la API, debemos entender cómo administrar el esfuerzo cognitivo de los modelos.

Thinking Levels (Budget Thinking)

Los modelos avanzados (como Claude Opus 4.8 o GPT-5.5) permiten configurar su "Esfuerzo de Razonamiento" (Low, Medium, High). * Default (Low Thinking): Para el 80% de las tareas diarias (ej. escribir un test unitario, hacer un refactor mecánico, leer un log de error), debes usar el modo de bajo esfuerzo. Es rápido, económico y suficiente. * High Thinking (Incremento de Budget): Cuando te enfrentes a un problema arquitectónico duro, un bug sutil de concurrencia que no logras encontrar, o al planificar la implementación de una nueva feature desde cero, vale totalmente la pena aumentar el budget. El modelo gastará más tiempo y tokens "pensando" (Chain of Thought interno) antes de emitir la primera línea de código, garantizando un diseño mucho más robusto.

Buena Práctica por Testear: Orquestación Asimétrica

No necesitas que el modelo más caro y lento del mundo escriba cada línea de código. Una estrategia emergente a probar es la Orquestación Asimétrica: 1. El Arquitecto (GPT-5.5 High / Opus 4.8 High): Se usa exclusivamente para analizar el problema, trazar el plan en un archivo implementation_plan.md y dividir el trabajo en tareas pequeñas (DAG). 2. Los Agentes Ejecutores (Modelos más baratos/rápidos): El arquitecto delega las tareas aisladas a agentes que corren en paralelo usando modelos más económicos (ej. Claude Sonnet, GPT-5.5 Low, Gemini Flash). Estos agentes escriben el código de bajo nivel y ejecutan los tests. 3. Optimización de Suscripciones: Esto permite aprovechar distintas cuotas y límites (rate limits) de tus suscripciones sin bloquearte, reservando la "inteligencia cara" solo para las tareas que realmente necesitan modelos más caros.

2. El Problema del "Context Rot" (Pudrición del Contexto)

¿Qué es el Context Rot?

Los Modelos de Lenguaje Grandes (LLMs) modernos tienen ventanas de contexto enormes. Sin embargo, el "Context Rot" ocurre cuando inyectamos un exceso de información (todo el repositorio, decenas de reglas globales, miles de líneas de logs) en un solo chat. El mecanismo de "atención" del modelo se diluye, provocando amnesia de reglas de seguridad, alucinaciones aumentadas y pérdida de eficiencia.

Estrategias Profundas para Evitarlo

1. Micro-Sesiones (Rotación de Chats): Debes iniciar un chat nuevo para tareas no relacionadas, feature o bugfix específico. No mantener un chat "infinito".
2. Carga Bajo Demanda: Nunca pegues archivos enteros "por si acaso". Si el agente necesita leer un archivo, que use sus herramientas.
3. Uso del patrón handoff: Al cambiar de chat, el agente actual genera un archivo resumen_traspaso.md con lo que logró y lo que falta. Es importante revisar y corregir errores de conceptos u objetivos. El nuevo agente lee ese archivo y retoma exactamente donde quedó, reiniciando la memoria de la ventana de contexto a cero, pero conservando la dirección. Esto es parecido a lo que hacen los agentes cuando se les acaba la ventana de contexto y automaticamente compactan el contexto(crean un resumen) pero creando un archivo modificable podemos ver y corregir errores de los modelos.

3. Herramientas de Estandarización: Reglas, Linters, RuleSync y Skillshare

Para gobernar un equipo donde coexisten humanos y múltiples agentes de IA (Cursor, Antigravity, Claude Code), necesitamos centralizar el conocimiento.

Reglas Globales y RuleSync

• Reglas Globales (AGENTS.md / CLAUDE.md): Archivo corto en la raíz que define los límites duros arquitectónicos y de estilo del proyecto.
• ¿Qué es RuleSync? Es una herramienta que distribuye y adapta estas reglas núcleo hacia las carpetas específicas que requiere cada agente (ej. .cursorrules, .agent/rules). Garantiza que, sin importar qué herramienta IA use un desarrollador, las directrices base del equipo sean idénticas.

Las "Skills" y Skillshare

• ¿Qué es Skillshare? Es un gestor por línea de comandos (CLI) que administra y sincroniza paquetes de habilidades IA ("Skills"). Permite que el agente cargue instrucciones ultra-especializadas solo bajo demanda, en lugar de ahogar al modelo con un AGENTS.md de mil líneas.
• Skill lint-and-validate: Enseña al agente a correr linters locales (ESLint, Ruff) y autocorregir sus propios errores de sintaxis leyendo la consola en bucle.

Profundización: Onboarding Interactivo con teach

En el desarrollo de software tradicional, cuando un Dev ingresa al equipo, un desarrollador con experiencia debe detener su trabajo productivo durante horas para explicarle cómo está estructurada la base de datos o el sistema de autenticación. Al invocar la skill teach, el agente IA asume el rol de ese Senior, pero bajo un método socrático. El flujo funciona así: 1. El nuevo desarrollador ejecuta la skill en un archivo complejo, por ejemplo: /teach auth.ts. 2. En lugar de devolver un resumen aburrido, el agente le pide al desarrollador que lea un bloque de código y le hace una pregunta: "Veo que usamos tokens opacos almacenados en Redis en lugar de JWTs convencionales. Mirando el código, ¿puedes deducir por qué tomamos esta decisión de seguridad?". 3. El desarrollador responde. El agente valida, corrige o profundiza usando como contexto los PRs históricos y los ADRs (Architecure Decision Records). Esto permite un onboarding asíncrono, profundo y sin interrumpir a los ingenieros clave.

Profundización: Validación Arquitectónica con grill-with-docs

Esta es una skill de fricción intencional. Antes de que cualquier desarrollador escriba una sola línea de código para un feature grande, debe enfrentarse a esta habilidad, donde el agente asume el rol de un Staff Engineer hostil y minucioso. 1. El desarrollador presenta un borrador inicial: "Voy a agregar RabbitMQ para encolar la validación de archivos de los clientes". 2. El agente lee la documentación del repositorio (docs/architecture/) e inmediatamente bombardea al desarrollador buscando vulnerabilidades lógicas y casos borde: "¿Qué pasa si el worker de RabbitMQ falla en medio del archivo? ¿Cómo vas a asegurar la idempotencia? Según el ADR-004, nuestro stack estándar de colas es AWS SQS, ¿por qué quieres introducir una nueva dependencia como RabbitMQ?". 3. El desarrollador debe defender su diseño o ajustarlo a las reglas del proyecto. 4. Solo cuando el agente está "satisfecho" de que no hay cabos sueltos ni deudas técnicas injustificadas, procede a redactar el implementation_plan.md final y actualiza el ADR oficial con la nueva decisión.

4. Entendimiento Semántico con Graphify - Herramienta por validar, reduce costo de cuota de planes/tokens y aumenta calidad del output de modelos.

Para evitar el Context Rot de inyectar archivos ciegamente en el chat, usamos Graphify como servidor MCP de extracción de contexto.

Funcionalidad

Graphify lee el código fuente utilizando Tree-sitter (análisis estático abstracto). Extrae la declaración de clases, funciones (Nodos) y cómo se llaman entre sí (Aristas), delegando a un modelo pequeño la generación de un resumen para cada bloque. Con esto, construye un Knowledge Graph (Grafo de Conocimiento) interactivo almacenado en NetworkX.

Beneficios para los Desarrolladores y Agentes

1. Ahorro Masivo de Tokens: Cuando un agente necesita entender un proyecto gigante, en vez de tragarse 50 archivos fuente enteros, le hace una consulta a Graphify: "¿Qué módulos dependen de auth.ts?". Graphify le devuelve exactamente los nombres y firmas de las dependencias.
2. Detección de God Nodes: Revela arquitecturas acopladas al mostrar visualmente qué archivos concentran demasiada lógica, facilitando refactors quirúrgicos.
3. Reducción Crítica de Alucinaciones: Ningún sistema es infalible, pero Graphify permite que el agente escriba código nuevo basándose en un mapa arquitectónico real y preciso de dependencias, reduciendo drásticamente las alucinaciones por contexto perdido.

5. TDD Riguroso y Calibración de Confianza (DoD)

TDD como "Cerca Eléctrica"

El TDD es un método donde escribes la prueba automatizada antes de escribir el código real. Los agentes sufren de no saber "cuándo detenerse", arreglando cosas que no estaban rotas. 1. Escribes el test estricto. 2. El agente usa la skill verifying-completion para ejecutar las pruebas, leer el error y reescribir en bucle hasta que pase (Verde).

Definition of Done (DoD) y Calibración

Los agentes tienden a hablar con extrema seguridad afirmando haber resuelto el problema, incluso si no compila. Por lo tanto, el TDD unitario no es suficiente. El DoD para un agente debe incluir obligatoriamente: * Typecheck Exitoso: Ejecutar tsc, mypy, etc., sin errores. * Calibración Explícita: El agente debe listar en su respuesta qué validó empíricamente (ej. "Ejecuté el test y pasó") vs. qué está asumiendo (ej. "Asumo que el puerto 8080 está libre en el entorno staging"). Las suposiciones ciegas son inaceptables en producción.

6. Deuda de Plataforma y Reproducibilidad del Entorno

Los agentes de IA interactúan con el código a través de la terminal. Si el agente no puede levantar el proyecto ejecutando comandos documentados y estándar, el problema no es del agente, es de deuda técnica de plataforma.

• Reproducibilidad Estricta: El entorno local debe estar contenido. Se exige el uso de Devcontainers, Nix, o herramientas como Volta/mise para asegurar que el agente tenga las mismas dependencias exactas que la máquina del humano.
• Comandos de Un Solo Toque: En lugar de dejar que el agente intente adivinar cómo compilar, el repositorio debe proveer scripts universales y simples: make test, make lint, make typecheck, npm run build.

7. Prevención de Conflictos Físicos: Git Worktrees

Si un humano y un agente clonan y trabajan en la rama main de una misma carpeta al mismo tiempo, los checkouts de rama o instalación de dependencias se romperán mutuamente. * La Solución: Git Worktrees. En lugar de clonar el repo dos veces (lo cual desincroniza el historial), git worktree crea una segunda carpeta "física" atada a la misma base de datos oculta .git. El agente puede aislar su entorno e instalar dependencias sin que el código del humano sufra alteraciones en su editor local.

8. Revisión Asistida en CI/CD: CodeRabbit y Riesgo Humano

Dado que la IA puede generar Pull Requests (PRs) de 500 líneas en un segundo, los humanos no pueden revisar todo manualmente en el pipeline de Integración Continua (CI/CD).

CodeRabbit como Filtro Auxiliar

CodeRabbit es un Agente de Revisión de Código impulsado por IA. Lee los PRs automáticamente y ejecuta: * Comentarios Línea por Línea: Sugerencias contextuales sobre seguridad o rendimiento en los diffs. * Resúmenes Ejecutivos: Explicación en lenguaje natural de la intención del PR.

Política de Revisión Basada en Riesgo

CodeRabbit es NO una Autoridad. Para evitar cuellos de botella sin sacrificar seguridad, establecemos una matriz de riesgo: * Bajo Riesgo (Auto-Aprobación asíncrona permitida): Cambios en CSS, refactors mecánicos de variables, actualizaciones de dependencias menores, documentación. * Alto Riesgo (Revisión Humana Obligatoria): Modificaciones a la lógica de autenticación (auth), acceso a bases de datos, permisos, pagos, o arquitecturas clave. En estos casos, la aprobación de un desarrollador senior es legalmente requerida sin importar el visto bueno de la IA.