Written with AI assistance from the source video. The video is the authority.
Log in to leave a comment
No posts yet
Cuando conectas Claude Code o Aider a un repositorio monolítico de cientos de miles de líneas, este empieza a leer archivos equivocados desde el principio. La ventana de contexto del modelo es limitada, por lo que al recopilar archivos irrelevantes agota el límite de tokens y termina modificando el código equivocado.
Este problema no se resuelve escribiendo un prompt largo. Debes reducir el radio físico del código que el agente explora e implantar reglas de verificación mecánica a nivel local.
En un repositorio monolítico, los puntos donde el agente cae en una exploración infinita suelen ser tres: la carpeta de utilidades comunes con funciones auxiliares dispersas (src/utils/), la capa de servicios con lógica de negocio entrelazada (src/services/) y el directorio de modelos globales (src/models/). Si estas tres carpetas comienzan a referenciarse entre sí, el agente termina leyendo docenas de archivos solo para corregir una sola línea de código.
Agrupar las carpetas divididas por capas técnicas en unidades de dominio ayuda a aislar y reducir el alcance de la búsqueda.
| Categoría | Estructura centrada en capas | Estructura de dominios separados | Cambio en el comportamiento del agente |
|---|---|---|---|
| Criterio de carpetas | Separación por capas técnicas (/controllers, /services) |
Separación por dominios (/domains/order) |
Busca únicamente los archivos necesarios dentro de una sola carpeta |
| Conexión de dependencias | Importación directa de entidades globales | Comunicación mediante límites de interfaz de dominio | Bloquea la carga en cadena de archivos irrelevantes |
| Lógica común | Funciones mezcladas en un src/utils/ único |
Separación en utilidades exclusivas del dominio y paquetes comunes | Previene la contaminación innecesaria del contexto global |
El orden para mover los directorios sin detener el servicio en ejecución es el siguiente:
src/domains/{nombre-dominio}/ y actualiza los alias de ruta en tsconfig.json.CLAUDE.md) dentro del subdirectorio separado.Las convenciones de código escritas extensamente en lenguaje natural son pasadas por alto fácilmente por el agente. Es necesario colocar números claros y prohibiciones en la parte superior del archivo de configuración para que sigan las directrices con precisión.
`markdown
`
Si el archivo de configuración supera las 200 líneas, es común que se pasen por alto las instrucciones posteriores.
CLAUDE.md del directorio raíz, mantén solo los comandos de compilación y las reglas de confirmación globales en menos de 200 líneas.src/domains/order/, en archivos de reglas dedicados dentro de esos mismos directorios.CLAUDE.local.md y regístralas en .gitignore para evitar conflictos.Los errores de sintaxis o de regresión en el código creado por el agente deben detectarse automáticamente al momento de realizar el commit. Utilizar Lefthook, que funciona como un binario único de Go, permite ejecutar comprobaciones en paralelo de manera más ligera que las herramientas basadas en Node.js.
Coloca lefthook.yml en la raíz para separar las comprobaciones estáticas ligeras de las fases de pruebas pesadas.
`yaml
pre-commit:
parallel: true
commands:
linter:
glob: ".{ts,tsx}"
run: npx eslint --fix {staged_files}
stage_fixed: true
formatter:
glob: ".{ts,tsx,json,md}"
run: npx prettier --write {staged_files}
stage_fixed: true
security-scan:
run: gitleaks git --staged --no-banner
pre-push:
parallel: false
commands:
typecheck:
run: npx tsc --noEmit
unit-tests:
run: npm run test:unit -- --passWithNoTests
`
El pre-commit de la fase de confirmación verifica únicamente los archivos en área de preparación (staged) en menos de 10 segundos, mientras que la verificación completa de tipos y las pruebas unitarias se trasladan a la fase de push (pre-push).
Para evitar que el agente use la opción --no-verify y evada los ganchos, registra el interceptor .claude/hooks/block-no-verify.mjs.
`javascript
import fs from 'fs';
const input = fs.readFileSync(0, 'utf8');
const parsed = JSON.parse(input);
if (parsed.tool_input?.command?.includes('--no-verify')) {
console.error("Policy Violation: --no-verify flag is strictly prohibited.");
process.exit(1);
}
process.exit(0);
`
Si un gancho falla, la salida de error de la consola se introduce en el siguiente mensaje para que el agente corrija el código por sí mismo.
Si el agente comienza a leer resultados de compilación o archivos de bloqueo (lockfiles), los tokens se agotan rápidamente. Es necesario cerrar el rango de búsqueda de archivos para prevenir costos imprevistos.
Crea un archivo .ignore o .aiderignore en la raíz del proyecto y registra los artefactos pesados.
`text
node_modules/
dist/
build/
coverage/
*.min.js
*.svg
*.lock
package-lock.json
public/assets/
db/migrations/
`
Especifica también el directorio de trabajo al ejecutar comandos en la terminal para bloquear el escaneo global.
`bash
aider "Refactor Order validation logic" --path=src/domains/order/ --exclude=src/domains/order/tests/
`
Verificar primero los cambios en modo de planificación antes de modificar el código, escribir pruebas unitarias fallidas y hacer que elabore únicamente código que las supere mantendrá el radio de trabajo del agente de forma segura.