Cómo rastrear y recuperar un mal funcionamiento de la base de código provocado por un agente de IA
makedreamJuly 30, 2026
0
Computing/Software
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
Cuando conectas un agente de IA como Claude Code o Codex a un repositorio de backend con más de 100.000 líneas de código, al principio te maravillas con la velocidad. Sin embargo, en el momento en que se introduce un par de líneas de prompt incorrectas, la IA atraviesa las barreras de protección y termina tocando utilidades comunes o archivos de configuración del entorno. Los registros de sesión se inflan a varios megabytes, la compilación se rompe y, tras pasar una hora revisando el Git Diff para encontrar el archivo causante, te surge el pensamiento de que habría sido mejor escribirlo tú mismo desde el principio.
Para otorgar autonomía al agente y evitar al mismo tiempo daños innecesarios en los archivos, se requiere un aislamiento duro y claro junto con un sistema de seguimiento de trazas visualizado.
Los archivos de instrucciones en lenguaje natural como CLAUDE.md o .aiignore suelen ser eludidos por el agente a medida que la ventana de contexto se alarga. Las solicitudes en la fase de prompt no son más que sugerencias, por lo que en el momento en que el agente pierde el contexto, la ejecución de sus herramientas cruza el límite sin vacilar.
Para bloquear físicamente el alcance del agente, es necesario colocar directamente en la raíz del proyecto el motor de control de permisos determinista .claude/settings.json.
`json
{
"permissions": {
"deny": [
"Edit(src/core/config/)",
"Edit(src/shared/utils/)",
"Read(./.env*)",
"Bash(rm -rf *)"
],
"ask": [
"Edit(src/api/v1/legacy/**)"
]
}
}
`
Después de establecer reglas de bloqueo explícitas, es más seguro volver a bloquearlas a nivel del sistema de archivos. Para los scripts de compilación de producción o los archivos de claves de seguridad, lo ideal es retirar los permisos de escritura a nivel del sistema operativo.
.claude/settings.json en la raíz del proyecto.permissions.deny.chmod 444 .env*.Al controlar los permisos de esta manera, puedes eliminar en gran medida los errores de compilación causados por la modificación repentina de módulos comunes por parte de la IA.
Si mantienes los registros de sesión (.jsonl) solo en el entorno local del desarrollador, resultará difícil determinar la causa cuando surjan efectos secundarios más adelante. Configura un flujo de trabajo de GitHub Actions para comprimir y validar las trazas de la sesión al momento de abrir un PR.
`yaml
name: AI Agent Session Audit & Risk Analysis
on:
pull_request:
types: [opened, synchronize]
jobs:
audit-session:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Mindwalk Telemetry Extractor
run: |
docker run --rm -v ${{ github.workspace }}:/workspace \
cosmtrek/mindwalk:v0.1.0 parse --log-dir=./.claude/sessions --out=telemetry.json
- name: Run Deterministic Repo Audit
id: repo_audit
run: |
curl -sSL https://github.com/aletheore/releases/download/v1.0/aletheore -o aletheore
chmod +x aletheore
./aletheore audit --telemetry=telemetry.json --max-allowed-depth=3
- name: Upload Mindwalk 3D Visual Artifact
uses: actions/upload-artifact@v4
with:
name: mindwalk-3d-trace-${{ github.event.pull_request.number }}
path: telemetry.json
`
Si integras un motor de análisis basado en Rust o Tree-sitter para inspeccionar si el agente se ha salido del alcance, puedes hacer que la compilación de CI falle de inmediato cuando se modifiquen módulos superiores fuera del rango permitido.
Resulta útil calcular el riesgo de cambio centrándose en la conectividad de los nodos en lugar de contar simplemente el número de líneas de código.
Aquí, es el número de archivos modificados y es la conectividad 3D promedio de los nodos alterados. Si se supera el umbral, configurar el sistema para que envíe un enlace al mapa de visualización 3D mediante una notificación de Slack permite al revisor comprender el riesgo al instante.
Cuando el agente causa un desastre, en lugar de descartar todo el commit, se debe rastrear la línea de tiempo para recuperar selectivamente solo los archivos contaminados. Una vez extraído el marco de tiempo específico en que comenzó el mal funcionamiento, usa jq para extraer el prompt y la ruta de razonamiento de ese momento desde el registro JSONL.
`bash
jq -c 'select(.timestamp >= "2026-07-11T14:20:00Z" and .timestamp <= "2026-07-11T14:25:00Z") |
{timestamp: .timestamp, prompt: .payload.prompt, tool_use: .payload.tool_use, thinking: .payload.thinking}'
./.claude/sessions/session_abc123.jsonl
`
Una vez confirmada la causa, el proceso de recuperación se divide en las siguientes 3 etapas:
git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)git clean -fd -- src/unwanted_generated_dir/)Usando este método, puedes recuperar limpiamente solo los archivos dañados sin el desafortunado evento de perder código que funciona correctamente.
En un entorno monorepo, si los nodos aumentan a decenas de miles, la propia herramienta de visualización puede colapsar. Si el navegador se vuelve lento, la depuración se vuelve tediosa. Para reducir los directorios innecesarios del objetivo de renderizado, se debe configurar firmemente el filtro de exclusión mindwalk.config.json.
`json
{
"visualization": {
"excludePatterns": [
"/node_modules/",
"/vendor/",
"/.git/",
"/dist/",
"/coverage/",
"/*.log",
"/*.pb.go"
],
"maxDepth": 5,
"groupingStrategy": "directory-segmented"
}
}
`
Por último, cuando ejecutes pipelines de visualización o herramientas de análisis como contenedores Docker en segundo plano, debes limitar las cuotas de recursos para que el IDE local no se congele.
mindwalk.config.json para excluir los nodos de directorios de dependencias del objetivo de visualización.--cpus="1.5" y --memory="2g" al ejecutar el contenedor.--nice=19 al final del comando de ejecución del proceso en segundo plano para reducir la prioridad de la CPU al nivel más bajo.