---
title: "Manual de Buenas Prácticas de Vibe Coding con VS Code, Codex y GitHub"
summary: "Una guía práctica para conducir proyectos con agentes de IA, AGENTS.md, planificación incremental, validaciones y Git."
slug: "manual-buenas-practicas-vibe-coding"
language: "es"
publishedAt: "2026-05-20"
updatedAt: null
tags:
  - "guia"
  - "vscode"
  - "codex"
  - "github"
translationOf: "pt/manual-boas-praticas-vibe-coding"
translationStatus: "current"
---

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:

```txt
Crea una app de finanzas.
```

La mejor forma es dirigir el trabajo:

```txt
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:

```txt
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:

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

Inicializa Git:

```bash
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:

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

Resultado esperado:

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

### Fase 2: planificación

Después, en una nueva tarea:

```txt
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í:

```txt
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:

```txt
Crea todo el sistema.
```

Prefiere:

```txt
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:

```txt
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:

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

## 4. Modelo de AGENTS.md

```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

```txt
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

```txt
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.
```