Vibe coding no es pedir código y cruzar los dedos.

Es montar un ambiente donde un agente rápido puede trabajar con contexto, límite y validación.

1. Mentalidad correcta

La peor forma de empezar es pedir algo genérico:

Crea una app de finanzas.

La mejor forma es dirigir el trabajo:

Lee AGENTS.md y PLANS.md.
Implementa solo la primera etapa.
Antes de editar, di qué archivos pretendes alterar.
Después ejecuta lint, pruebas y build.

El agente necesita:

  • contexto del proyecto;
  • reglas claras;
  • criterios de listo;
  • comandos de validación;
  • límites de lo que no puede hacer;
  • historial versionado en Git.

El AGENTS.md funciona como un archivo de instrucciones para agentes de IA.

Se parece a un README.md, pero orienta cómo el agente debe navegar, alterar, probar y documentar el proyecto.

2. Estructura recomendada

Una estructura inicial simple:

mi-proyecto/
├── AGENTS.md
├── README.md
├── PLANS.md
├── CHANGELOG.md
├── .gitignore
├── .env.example
├── exploraciondelproyecto/
│   ├── idea.md
│   ├── referencias.md
│   ├── requisitos.md
│   └── restricciones.md
├── docs/
│   ├── arquitectura.md
│   ├── base-de-datos.md
│   └── backlog.md
├── src/
├── tests/
└── .vscode/
    ├── settings.json
    ├── tasks.json
    └── extensions.json

Esta división separa tres capas:

  • AGENTS.md: reglas permanentes para el agente.
  • exploraciondelproyecto/: material bruto de idea, referencia y restricción.
  • docs/: documentación limpia, consolidada y revisable.

3. Flujo recomendado

Fase 0: preparar el repositorio

Antes de pedir implementación, crea la base:

AGENTS.md
README.md
PLANS.md
exploraciondelproyecto/
docs/
.vscode/

Inicializa Git:

git init
git add .
git commit -m "chore: estructura inicial del proyecto"

Fase 1: exploración

No pidas código todavía.

Pide al agente:

Lee exploraciondelproyecto/.
Entiende la idea.
Produce un resumen crítico con alcance, riesgos, dudas y sugerencias.
No implementes nada.

Resultado esperado:

docs/vision-general.md
docs/requisitos.md
docs/riesgos.md
docs/decisiones-iniciales.md

Fase 2: planificación

Después, en una nueva tarea:

Con base en AGENTS.md, README.md y documentos en docs/,
crea un plan de implementación incremental en PLANS.md.
No alteres código todavía.

Fase 3: implementación incremental

Ahora sí:

Implementa solo la etapa 1 de PLANS.md.
Antes de editar, explica qué archivos pretendes alterar.
Después implementa, ejecuta validaciones y actualiza documentación si es necesario.

La regla de oro es una etapa por vez.

Evita:

Crea todo el sistema.

Prefiere:

Implementa autenticación local simple.
Ahora implementa el CRUD de clientes.
Ahora añade pruebas.
Ahora refactoriza la capa de servicios.

Fase 4: validación

En cada etapa, pide:

1. Ejecuta lint.
2. Ejecuta pruebas.
3. Ejecuta build.
4. Lista archivos alterados.
5. Explica riesgos restantes.
6. Sugiere el próximo commit.

Fase 5: commit y sincronización

Solo después de validar:

git status
git add .
git commit -m "feat: implementa cadastro de clientes"
git push origin main

4. Modelo de AGENTS.md

# AGENTS.md

## Objetivo del proyecto

Este proyecto tiene como objetivo construir una aplicación [describa aquí la idea central].

El agente debe ayudar en el desarrollo incremental, priorizando claridad, seguridad, testabilidad y simplicidad.

## Cómo trabajar en este proyecto

Antes de implementar cualquier cosa:

1. Lee este AGENTS.md.
2. Lee el README.md.
3. Lee los archivos relevantes en docs/.
4. Consulta PLANS.md si existe.
5. Haz un breve plan antes de alterar archivos.

## Reglas de implementación

- Trabaja en etapas pequeñas.
- Prefiere código simple, legible y testeable.
- Evita abstracciones prematuras.
- No sobrescribas cambios manuales del usuario.
- Actualiza documentación cuando cambie el comportamiento.

## Criterios de listo

Una tarea solo está lista cuando:

1. el código fue implementado;
2. las pruebas relevantes fueron creadas o actualizadas;
3. las validaciones fueron ejecutadas o justificadas;
4. la documentación fue actualizada si era necesario;
5. riesgos o pendientes fueron listados.

5. Prompts útiles

Exploración

Lee AGENTS.md y todos los archivos dentro de exploraciondelproyecto/.
No implementes nada.

Produce:
1. resumen de la idea;
2. requisitos funcionales;
3. requisitos no funcionales;
4. riesgos técnicos;
5. dudas relevantes;
6. sugerencia de stack;
7. alcance sugerido para MVP.

Planificación

Con base en AGENTS.md, README.md y docs/,
crea un plan incremental en PLANS.md.

El plan debe dividir el proyecto en etapas pequeñas, testeables y commiteables.
No alteres código fuente todavía.