Que la IA no se desvíe: un método de colaboración realmente aplicable (con plantillas)

• Le pides a la IA que arregle un bug, pero termina tocando código que no tiene nada que ver—y luego te toca revertir a mano
• Escribes un montón de prompts y aun así no encuentra el archivo correcto; acaba “adivinando”
• A mitad de una conversación larga, empieza a olvidar restricciones y la calidad se desploma

• AGENTS.md: restricciones duras a nivel de repo (líneas rojas, valores por defecto, definición de done)
• docs/ai-playbook/index.md: entrada de una sola página (alta señal)
• docs/ai-playbook/code-map.md: mapa de código (dónde tocar)
• docs/ai-playbook/flows.md: flujos clave (cómo corre)
• docs/ai-playbook/collab-rules.md: reglas de colaboración + plantilla de plan de cambio (cómo trabajamos)

Step 0: Define límites y “done” (no empieces por el prompt)

1. Boundary (límite): lo que nunca debe ocurrir (líneas rojas de privacidad/arquitectura, compatibilidad de protocolo, guardrails de parámetros críticos)
2. Scope (alcance): un objetivo por cambio; prohibido “ya que estoy, optimizo…”
3. Done (hecho): build/tests + checklist de regresión manual deben quedar escritos

Un solo objetivo, primero el plan; no cruzar líneas rojas de privacidad/arquitectura; “done” significa que compila y trae checklist de regresión.

Antipatrones comunes (evita estas trampas)

1. Pedirle a la IA “cambia el código” sin plan
   • Resultado: cambia 10 archivos y luego descubres que la dirección era incorrecta; revertir duele
   • Correcto: exigir un plan primero; implementar solo tras aprobarlo
2. Meter todos los documentos en el prompt
   • Resultado: explosión de contexto; la IA pierde la señal (ni encuentra los entry points)
   • Correcto: usar index + code-map como navegación de alta señal
3. Dejar que la IA “arregle cosas de paso”
   • Resultado: un PR mezcla múltiples objetivos; el review se encarece y los bugs son más difíciles de revertir
   • Correcto: single-scope, cambios mínimos y reversibles

Step 1: Escribe AGENTS.md (restricciones duras, reutilizables)

• Plan first: AGENTS.en.md:7
• One change, one purpose: AGENTS.en.md:8
• Privacy & architecture red line: AGENTS.en.md:9
• Docs must stay in sync: AGENTS.en.md:12
• Verification required: AGENTS.en.md:13

# AGENTS — Repo Rules

First Principles

- Plan-first: Propose a change plan and get approval before writing code
- Single-scope: One PR solves one goal; avoid “while I’m here” fixes
- Redlines: Never cross privacy/architecture/protocol/key-parameter guardrails
- Docs-sync: Keep the playbook docs in sync when entry points/flows/interfaces change
- Validation: Must include build/tests and key manual regression checklist

Soporte multi-idioma

• Mantén AGENTS.en.md como versión canónica
• Añade variantes localizadas si hace falta (p. ej. AGENTS.<locale>.md)
• Tras clonar, cada persona crea el symlink local según idioma:

# English users
ln -s AGENTS.en.md AGENTS.md

• Añade AGENTS.md a .gitignore para evitar conflictos de symlinks

Idea clave
La colaboración con IA no se arregla con “mejores prompts”, sino con “restricciones dentro del repo”. AGENTS.md hace que las reglas se reutilicen; el AI Playbook hace que el contexto dure.

Step 2: Escribe docs/ai-playbook/index.md (entrada de alta señal)

• Se lee en 30 segundos: solo “snapshot del proyecto + índice de enlaces”
• Navegación de un clic: llevar a code-map / flows / collab-rules

# AI Playbook — Index

## Project Snapshot

- Stack: Next.js / Node / ...
- Red lines: ...

## Document Index

- Code map: docs/ai-playbook/code-map.md
- Key flows: docs/ai-playbook/flows.md
- Collaboration rules: docs/ai-playbook/collab-rules.md

Step 3: Escribe code-map.md (dónde tocar)

• Solo directorios clave y archivos de entrada clave
• Una frase por archivo: su responsabilidad
• Al llegar una solicitud: identifica 3–8 candidatos en code-map antes de leer en profundidad

Common request routing

- New page / SEO: frontend/app/\*\*/page.tsx + metadata.ts
- i18n copy: frontend/constants/messages/\*
- Blog: frontend/content/blog/\* + frontend/lib/blog.ts

• Primera versión: que la IA resuma “directorios + entry points” para navegación, no para exhaustividad
• Iteración: actualiza incrementalmente por PR/commit; evita reescrituras completas

Step 4: Escribe flows.md (cómo corre)

• Con secuencia + invariantes claros, deja de “parchear por intuición”
• Los pitfalls históricos se vuelven checklist reutilizable

1. Secuencia / flow clave (Mermaid si hace falta)
2. Checklist de debug (logs/estados cruciales)
3. Plantilla de micro-plan (plan-first antes de tocar código)

• Primera versión: que la IA reexponga el flujo E2E + secuencia clave + invariantes; tú corriges (sobre todo red lines e invariantes) y lo dejas en docs
• Iteración: actualizar por cambios en interfaces/secuencias

Step 5: Haz “plan first” obligatorio (un plan = mini diseño)

Title: <short, clear title>

Goals
- <what you want to achieve>

Scope / Files
- <list of files you’ll change/add + why>

Approach
- <implementation plan and key design points>

Risks & Mitigations
- <risk> → <mitigation>

Acceptance Criteria
- <verifiable acceptance items>

Rollback
- <how to revert quickly>

Docs to Update
- docs/ai-playbook/index.md / code-map.md / flows.md / collab-rules.md / others?

Validation
- Build: next build
- Manual: <key cases & regression points>

1. Leer index + code-map + flows (solo lectura, sin tocar código)
2. Reexplicar estado actual y restricciones (tú corriges una vez)
3. Escribir el plan de cambio (implementación solo tras aprobación)

Evita pitfalls
Corrige la dirección en la fase de plan; evita construir y luego tirar. Single-scope baja el costo de rollback y facilita el merge.

Step 5.1: Resistencia de contexto (checkpoint → chat nuevo)

# Handoff

## Problem statement (3–5 sentences)

## Confirmed plan (bullets)

## Done / Not done

## Key files and entry points

## Red lines and invariants

## Acceptance & regression checklist

## Next-step checklist

Step 6: Cierra el loop (trata al agente como a un nuevo compañero)

1. Solicitud → restricciones (citar AGENTS.md)
2. Localización → entry points (citar index + code-map)
3. Alineación → secuencia (citar flows)
4. Plan → mini diseño (plantilla en collab-rules)
5. Implementación → cambios pequeños y single-scope (rollback fácil)
6. Verificación → next build + regresiones clave
7. Sincronización → docs del playbook al día

• Corregir dirección al planear, no al final
• Single-scope hace barato el rollback y fácil el merge
• Flows convierte pitfalls en checklist

• ¿Incluye link/resumen del plan de cambio?
• ¿Actualizaste docs/ai-playbook/* si cambiaste entry points/flows/interfaces?

Ejemplos de prompt (listos para copiar)

Referencia de industria: cómo OpenAI organiza un sprint con Codex

• Tratar al agente como un “nuevo senior”: capaz, pero necesita arquitectura/limitaciones claras
• Externalizar reglas: mantener un AGENTS.md fuerte compensa
• Plan antes de cambios reales: depura el plan antes que el código
• Resistencia de contexto: cuando llegues al límite, escribe el plan en un archivo y continúa
• Multi-sesión en paralelo: más parecido a “gestionar un equipo” que a usar una sola herramienta

Estructura mínima de directorios (copiable)

AGENTS.en.md             # Canonical rules (English)
AGENTS.<locale>.md       # Optional localized rules
AGENTS.md                # Symlink (created locally after git clone)
docs/
  ai-playbook/
    index.md             # High-signal entry point
    code-map.md
    flows.md
    collab-rules.md

Próximos pasos

1. Empieza ya: copia la estructura mínima y comienza por AGENTS.md
2. Implementación de referencia: PrivyDrop GitHub
3. Feedback: abre un issue o comenta si te sirve (o te atoras)
4. Star: si te aporta valor, deja una estrella 🌟

Cierre