La IA no corrige deficiencias estructurales — las magnifica. La calidad de tu sistema determina directamente la calidad de los resultados que obtenés al trabajar con agentes de IA, LLMs y herramientas automatizadas.
Esto no se trata de productividad individual. Se trata de diseñar un sistema de desarrollo en el cual la IA pueda operar bajo condiciones estructurales adecuadas: contexto explícito, contratos claramente definidos, validaciones automáticas confiables, reducción de ambigüedad y trazabilidad completa.
Estos son los principios, estándares y prácticas que seguimos en BlackBox Vision para estructurar proyectos de software optimizados para desarrollo asistido por IA.
1. Arquitectura: monorepo con estructura deliberadamente simple
Todos los proyectos deberían organizarse bajo un esquema de monorepo, gestionado mediante Turborepo o herramienta equivalente.
Principios arquitectónicos
- Separación clara de responsabilidades entre paquetes
- Convenciones de naming consistentes y explícitas
- Estructura fácilmente navegable desde CLI
- Contratos bien definidos entre módulos
- Bajo acoplamiento y alta cohesión
- Minimización de dependencias implícitas
Por qué importa para la IA
Un monorepo permite que agentes y herramientas automatizadas puedan:
- Comprender dependencias internas
- Identificar límites arquitectónicos (boundaries)
- Ejecutar tareas de forma localizada
- Operar sin requerir inferencias complejas
El monorepo reduce la fragmentación contextual y mejora el razonamiento automatizado sobre el sistema completo. Cuando un agente de IA puede ver el grafo completo de dependencias en un solo workspace, toma mejores decisiones.
2. Documentación estructural obligatoria
Cada proyecto debe incluir un README estructurado que contenga, como mínimo:
- Contexto del producto
- Problema que resuelve
- Arquitectura general
- Stack tecnológico
- Features principales
- Comandos disponibles
- Setup local
- Proceso de despliegue
- Convenciones internas relevantes
El README constituye un insumo estructural para agentes — no es solo documentación para humanos. Donde corresponda, debe complementarse con archivos de contexto persistente, tales como:
AGENTS.mdCLAUDE.md- Archivos equivalentes de inyección contextual
El objetivo es permitir que cualquier herramienta de IA reconstruya el modelo mental del sistema sin depender de conocimiento tácito. Si alguien necesita explicar tu proyecto verbalmente para que la IA sea útil, tenés un problema de documentación.
3. Normalización estricta de scripts
Todos los proyectos deben estandarizar, como mínimo, los siguientes scripts:
linttypecheckbuildtest
Cada subproyecto dentro del monorepo debe alinear sus scripts con el pipeline global.
¿Por qué estandarizar scripts?
- Estandarizar puntos de validación
- Permitir ejecución sistemática por agentes
- Reducir dependencia en disciplina manual
- Establecer contratos ejecutables del sistema
Los scripts constituyen la interfaz formal entre el código y los mecanismos de validación automatizada. Cuando un agente de IA ejecuta pnpm test y obtiene un exit limpio, eso es un contrato verificado — no una esperanza.
4. Convenciones de commits y versionado
Usá commitlint (o herramienta equivalente) para asegurar el cumplimiento automático de un formato estándar de commits.
Beneficios
- Historial legible con trazabilidad semántica clara
- Compatibilidad con versionado semántico
- Generación automática de changelogs confiables
- Análisis histórico automatizado por agentes
La consistencia en los commits es esencial para preservar coherencia temporal y facilitar análisis automatizados. Un agente de IA leyendo tu historial de git debería poder entender qué cambió, por qué y cuándo — sin adivinar.
5. Proceso de Pull Requests basado en niveles de impacto
El proceso de revisión de Pull Requests debe ser proporcional al impacto estructural del cambio.
En entornos optimizados para IA, donde el pipeline ejecuta validaciones exhaustivas, la revisión humana deja de cumplir una función técnica básica y pasa a cumplir un rol de gobernanza arquitectónica y estratégica.
5.1 Clasificación de PRs
Todo PR debe clasificarse explícitamente según su nivel de impacto.
Nivel 1 — Operativo (auto-merge permitido)
Cambios que:
- No modifican contratos públicos
- No alteran entidades de dominio
- No introducen nuevas dependencias
- No modifican límites entre paquetes
- Constituyen refactors locales o mejoras acotadas
Si el pipeline pasa lint, typecheck, build, test y análisis estático — el PR puede aprobarse automáticamente.
Un alto porcentaje de PRs de Nivel 1 indica arquitectura modular sólida, separación efectiva de responsabilidades, bajo acoplamiento y capacidad de evolución incremental.
Nivel 2 — Estructural (revisión obligatoria)
Cambios que:
- Modifican modelos de dominio
- Alteran contratos entre módulos
- Introducen nuevas dependencias externas
- Modifican boundaries arquitectónicos
- Impactan múltiples paquetes del monorepo
- Afectan componentes core del producto
Estos PRs requieren revisión humana obligatoria enfocada en coherencia arquitectónica, consistencia con decisiones previas, impacto sistémico y complejidad introducida.
El objetivo no es validar sintaxis — es preservar dirección estructural.
Nivel 3 — Estratégico (revisión + discusión formal)
Cambios que:
- Introducen nuevos patrones estructurales
- Modifican decisiones arquitectónicas fundacionales
- Impactan la estrategia técnica del producto
- Afectan roadmap o posicionamiento
- Implican reestructuración relevante del sistema
Son decisiones con impacto de largo plazo. Requieren revisión humana, discusión explícita y alineación previa.
5.2 Indicador de salud arquitectónica
La distribución de PRs funciona como métrica indirecta de madurez del sistema:
- Mayoría Nivel 1 → Arquitectura modular y saludable
- Algunos Nivel 2 → Evolución controlada
- Pocos Nivel 3 → Cambios estratégicos deliberados
Si la mayoría de los PRs son Nivel 2 o 3, es una señal de alerta: acoplamiento excesivo, boundaries insuficientemente definidos, diseño frágil o necesidad de refactorización estructural.
Un sistema bien diseñado permite cambios locales sin impacto estructural amplio.
5.3 Principio rector
La automatización valida corrección técnica. La revisión humana valida dirección arquitectónica.
6. Automatizaciones y skills compartidos
La eficiencia en el trabajo con agentes se incrementa cuando el equipo comparte automatizaciones y flujos estandarizados.
Ejemplo — un skill ship:
- Crea rama
- Genera commit con formato estándar
- Realiza push
- Abre o actualiza PR automáticamente
Objetivos
- Reducir fricción operativa
- Minimizar errores repetitivos
- Estandarizar flujos
- Eliminar decisiones innecesarias
Automatizar tareas repetitivas libera capacidad cognitiva para decisiones estratégicas. Cuando tu equipo gasta cero tiempo en ceremonias de git, dedica todo su tiempo al problema real.
7. Seguridad, dependencias y revisión automatizada
Incorporá herramientas de análisis continuo dentro del pipeline de PR:
- SonarQube — análisis estático y detección de vulnerabilidades
- Dependabot — monitoreo automático de dependencias
- CodeRabbit — revisión inicial automatizada de PRs
Estas herramientas complementan el trabajo con IA y refuerzan la calidad estructural del sistema. No son reemplazos de agentes de IA — son guard rails que hacen que los agentes sean más efectivos.
8. Infraestructura compartida (MCPs y herramientas extendidas)
Estandarizá las configuraciones de MCPs y herramientas extendidas dentro del equipo para garantizar acceso homogéneo a capacidades avanzadas.
Herramientas clave:
- Playwright — pruebas end-to-end con navegador real
- GitHub API — operación programática sobre repositorios
- Context7 — documentación estructurada optimizada para consumo por LLMs
La estandarización de herramientas reduce divergencia operativa y facilita colaboración asistida por IA. Cuando cada desarrollador tiene los mismos servidores MCP configurados, los agentes de IA se comportan consistentemente en todo el equipo.
9. TDD como punto de partida
Al trabajar con agentes generadores de código, iniciá cada implementación bajo disciplina TDD (Test-Driven Development).
Beneficios en contexto IA
- Define intención explícita
- Reduce la ambigüedad funcional
- Permite validación inmediata
- Mejora el ciclo iterativo: agente → validación → ajuste
El test funciona como contrato verificable de la especificación. Cuando le pasás a un agente de IA un test fallando y le pedís que lo haga pasar, obtenés resultados dramáticamente mejores que pedir "implementá el feature X."
10. SDD (Specification-Driven Development)
La IA requiere especificaciones claras de intención.
SDD implica:
- Definir con precisión el problema a resolver
- Describir inputs y outputs estructurados
- Establecer criterios de aceptación verificables
- Delegar la implementación una vez definida la intención
Este enfoque replica el modelo operativo de equipos de ingeniería maduros: intención primero, ejecución después. Cuanto más clara sea tu especificación, menos necesita adivinar la IA — y mejor es el output.
¿Cómo se ve un proyecto optimizado para IA?
Un proyecto optimizado para IA debe contar con:
- Arquitectura explícita — boundaries claros, bajo acoplamiento, alta cohesión
- Documentación estructurada — README, CLAUDE.md, archivos de contexto que la IA pueda consumir
- Scripts estandarizados — lint, typecheck, build, test como contratos ejecutables
- Validaciones automatizadas — pipelines que detecten problemas antes de que los humanos tengan que hacerlo
- Convenciones estrictas — formato de commits, naming, estructura de archivos
- Procesos trazables — cada cambio es auditable y comprensible
- Gobernanza proporcional — el esfuerzo de revisión coincide con el impacto estructural
- Especificaciones claras — la intención se define antes de que comience la implementación
La IA amplifica el sistema existente. La ventaja estructural surge cuando el sistema es explícito, coherente y deliberadamente diseñado.
