Genera tu AGENTS.md

Para que es este capitulo

Este capitulo esta diseñado para que un agente de codigo IA lo lea y, basandose en estas instrucciones, genere un AGENTS.md optimizado para tu proyecto.

Copia la URL de este capitulo y pegala en tu agente de IA favorito con el prompt:

Lee este articulo y genera un AGENTS.md para mi proyecto: [URL]

---

Instrucciones para el agente IA

Lo que sigue esta escrito para ti, agente de codigo. Siguelo paso a paso.

Paso 1: Detectar tipo de proyecto

Antes de generar nada, determina si el proyecto es:

• Proyecto simple: un solo package.json / Cargo.toml / pyproject.toml en la raiz
• Monorepo: multiples paquetes (workspaces en package.json, directorio packages/ o apps/)
• Multi-lenguaje: mezcla de tecnologias (ej: backend Go + frontend React)

Para detectarlo, busca:

# Indicadores de monorepo
package.json → campo "workspaces"
pnpm-workspace.yaml
lerna.json
turbo.json
nx.json
Cargo.toml → campo [workspace]

Si es monorepo, salta al Paso 6 despues de completar el analisis base.

Paso 2: Analizar el proyecto

Busca y lee estos archivos si existen:

• package.json / Cargo.toml / pyproject.toml / go.mod (dependencias y scripts)
• tsconfig.json / biome.json / .eslintrc.* / .prettierrc (tooling)
• Dockerfile / docker-compose.yml (infraestructura)
• .github/workflows/ / .gitlab-ci.yml (CI/CD)
• README.md (contexto general)
• CLAUDE.md / .cursorrules / AGENTS.md existente (instrucciones previas)

Del package.json (o equivalente), extrae:

• Runtime y version (Node.js, Bun, Deno, Python, Rust, Go)
• Framework principal (React, Vue, Svelte, Express, Hono, FastAPI, Actix)
• Package manager (npm, pnpm, bun, yarn, cargo, pip)
• Scripts disponibles (dev, build, test, lint, format)
• Testing framework (Vitest, Jest, Playwright, pytest)
• Linter/formatter (Biome, ESLint, Prettier, Ruff)

De la estructura de directorios, identifica:

• Patron arquitectural (MVC, hexagonal, flat, monorepo, modular)
• Directorios principales y su proposito
• Donde van los tests (junto al fuente, carpeta separada, ambos)
• Archivos de referencia: 2-3 archivos que mejor representan el estilo del proyecto

Paso 3: Generar el AGENTS.md

Usa esta plantilla. Elimina secciones que no apliquen. No inventes informacion que no puedas confirmar del codebase.

# AGENTS.md

[Descripcion en 1-2 oraciones. Stack principal con versiones.]

## Commands

- Install: `[comando]`
- Dev: `[comando]` (port [puerto])
- Build: `[comando]`
- Test all: `[comando]`
- Test file: `[comando] path/to/file.test.ts`
- Lint: `[comando]`
- Lint fix: `[comando]`
- Type check: `[comando]`

## Tech stack

- Runtime: [runtime version]
- Language: [lenguaje version]
- Framework: [framework version]
- Database: [DB + ORM si aplica]
- Testing: [framework]
- Linting: [linter/formatter]
- Package manager: [pm]

## Project structure

[arbol de directorios con descripcion de cada uno]

## Code style

[Convenciones extraidas del codebase real]
- [exports: named/default]
- [naming: kebab-case archivos, PascalCase tipos]
- [limites de tamaño si hay convencion]

### Reference files
- `path/to/good-example.ts` - [por que es buen ejemplo]
- `path/to/another.ts` - [que patron demuestra]

## Testing

- Framework: [nombre]
- Location: [junto al fuente / carpeta separada]
- Naming: `[patron].test.ts`
- Run related: `[comando]`

## Git workflow

- Branch: `feat/`, `fix/`, `refactor/`
- Commit: `feat: description` / `fix: description`
- [hooks si existen]

## Boundaries

### Always do
- Run tests after modifying source files
- Run linter before committing
- [boundaries del proyecto]

### Ask first
- Before adding production dependencies
- Before modifying database schemas
- Before changing CI/CD configuration

### Never do
- Never commit .env, secrets, or API keys
- Never delete or skip failing tests
- Never force-push to main
- [boundaries especificos]

Paso 4: Reglas de generacion

Sigue estas reglas estrictamente:

1. Solo informacion verificable: si no puedes confirmar una version o convencion, no la incluyas
2. Comandos reales: extrae del package.json scripts, no los inventes
3. Bajo 150 lineas: si supera 150, extrae detalle a archivos en docs/
4. Sin redundancia: no repitas lo que ya esta en tsconfig.json, biome.json u otros configs
5. Boundaries del proyecto: si existe CLAUDE.md con reglas, migralas a boundaries
6. Archivos de referencia reales: apunta a archivos que existan, verificalo antes de incluirlos
7. Idioma del AGENTS.md: escribe en ingles (es el estandar), a menos que el proyecto tenga instrucciones explicitas de usar otro idioma

Paso 5: Integrar con herramientas existentes

Si existe CLAUDE.md: genera AGENTS.md con instrucciones universales y simplifica CLAUDE.md a:

@AGENTS.md

## Claude-specific
[Solo extensiones de Claude Code: skills, MCP, sub-agentes, prioridades]

Si existe .cursorrules: genera AGENTS.md y sugiere reemplazar .cursorrules con symlink:

ln -s AGENTS.md .cursorrules

Si existe GEMINI.md: mismo patron, symlink: ln -s AGENTS.md GEMINI.md

Si no existe ninguno: simplemente genera AGENTS.md en la raiz.

Paso 6: Monorepos — generar multiples archivos

Si detectaste un monorepo en el Paso 1, genera un AGENTS.md por nivel:

AGENTS.md raiz (maximo 50 lineas)

Solo convenciones globales compartidas por todos los paquetes:

# AGENTS.md

[Nombre del monorepo]. [Tecnologia workspace].

## Workspace commands
- Install all: `[comando]`
- Build all: `[comando]`
- Test all: `[comando]`

## Shared conventions
- [Lenguaje y modo, ej: TypeScript strict]
- [Formatter/linter compartido]
- Commit format: `feat(package): description`

## Package navigation
- `packages/api/` - [descripcion breve]
- `packages/web/` - [descripcion breve]
- `packages/shared/` - [descripcion breve]

## Global boundaries

### Never do
- Never commit .env or secrets
- Never force-push to main

AGENTS.md por paquete (maximo 100 lineas cada uno)

Para cada paquete con su propio package.json o config, genera un AGENTS.md especifico:

# AGENTS.md

[Descripcion del paquete]. [Stack especifico].

## Commands
- Dev: `[comando especifico del paquete]`
- Test: `[comando especifico]`
- Build: `[comando especifico]`

## Architecture
[Estructura de directorios de este paquete]

## Code style
[Convenciones especificas de este paquete]

## Testing
[Framework y patrones de test de este paquete]

## Boundaries
[Boundaries especificos de este paquete]
### Ask first
- [Acciones criticas de este paquete]
### Never do
- [Restricciones de este paquete]

Reglas para monorepos

• Raiz = global: solo lo que aplica a TODOS los paquetes
• Paquete = especifico: stack, comandos y boundaries propios de ese paquete
• Sin repeticion: si la raiz dice “TypeScript strict”, los paquetes no lo repiten
• El mas cercano gana: si la raiz dice “use npm” y el paquete dice “use pnpm”, gana pnpm
• Navegar entre paquetes: la raiz debe listar todos los paquetes con descripcion breve

Ejemplo monorepo real

Estructura detectada:

mi-saas/
├── package.json          # workspaces: ["packages/*"]
├── packages/
│   ├── api/              # Hono + PostgreSQL
│   │   └── package.json
│   ├── web/              # React + Vite
│   │   └── package.json
│   └── shared/           # Tipos compartidos
│       └── package.json

Archivos a generar:

AGENTS.md (raiz):

# AGENTS.md

SaaS monorepo with pnpm workspaces. TypeScript strict in all packages.

## Workspace commands
- Install: `pnpm install`
- Build all: `pnpm -r build`
- Test all: `pnpm -r test`
- Lint all: `pnpm -r lint`

## Shared conventions
- TypeScript 5.7 strict mode
- Biome for formatting and linting
- Commits: `feat(api): description` / `fix(web): description`

## Packages
- `packages/api/` - REST API (Hono + Drizzle + PostgreSQL)
- `packages/web/` - Frontend (React 19 + Vite 6 + Tailwind)
- `packages/shared/` - Shared types and utilities

packages/api/AGENTS.md:

# AGENTS.md

REST API for the SaaS platform. Hono 4, Drizzle ORM, PostgreSQL 17.

## Commands
- Dev: `pnpm dev` (port 3000)
- Test: `pnpm test`
- Test file: `pnpm vitest run src/path/file.test.ts`
- Migrate: `pnpm drizzle-kit push`

## Architecture
src/
├── domain/          # Entities, value objects
├── application/     # Use cases, ports
├── infrastructure/  # DB adapters, external APIs
└── routes/          # HTTP handlers

## Boundaries
### Ask first
- Before modifying database schema or migrations
### Never
- Never expose domain types directly in API responses
- Never hardcode connection strings

packages/web/AGENTS.md:

# AGENTS.md

SaaS frontend. React 19, Vite 6, Tailwind CSS 4, TanStack Query.

## Commands
- Dev: `pnpm dev` (port 5173)
- Test: `pnpm test`
- Build: `pnpm build`
- Storybook: `pnpm storybook`

## Architecture
src/
├── components/     # Reusable UI components
├── pages/          # Route pages
├── hooks/          # Custom React hooks
├── services/       # API client layer
└── stores/         # Zustand state management

## Code style
- Functional components only
- Named exports, no default exports
- CSS with Tailwind utility classes, no custom CSS files
- See `src/components/Button.tsx` for component pattern

## Boundaries
### Never
- Never use inline styles
- Never import from packages/api directly (use API client)

Paso 7: Verificar

Despues de generar, ejecuta esta checklist:

1. Cada comando listado existe en el package.json scripts correspondiente
2. Cada directorio del project structure existe en el filesystem
3. Cada archivo de referencia existe y es buen ejemplo
4. Ningun archivo supera 150 lineas
5. No se repite informacion entre la raiz y los paquetes (monorepo)
6. No se repite informacion que ya esta en archivos de config
7. Los boundaries son verificables (no vagos como “write good code”)

Paso 8: Proponer al usuario

Muestra el resultado al usuario y explica:

• Archivos generados: lista cada AGENTS.md con su ubicacion
• Informacion pendiente: que no pudiste confirmar (para que el usuario complete)
• Archivos simplificados: si migraste CLAUDE.md o .cursorrules
• Recomendaciones: secciones que el usuario deberia revisar o expandir

Si es monorepo, explica la jerarquia: “Genere X archivos: uno global en la raiz y uno por paquete. El global tiene convenciones compartidas, cada paquete tiene su stack especifico.”

---

Resumen

Este capitulo es una guia ejecutable para agentes IA:

1. Detectar tipo de proyecto (simple vs monorepo)
2. Analizar codebase: configs, scripts, estructura, convenciones
3. Generar AGENTS.md con plantilla estandarizada
4. En monorepos: un archivo global + uno por paquete
5. Integrar con herramientas existentes (CLAUDE.md, .cursorrules)
6. Verificar que todo es real y verificable
7. Proponer al usuario con explicacion de decisiones

Compartelo con tu agente favorito y obtendras un AGENTS.md hecho a medida.

---

← Capitulo 10: Mejores Practicas y Antipatrones | Indice