Saltar al contenido principal

AGENTS.md Contexto de Proyecto

El archivo AGENTS.md (popularizado por desarrolladores como Mitchell Hashimoto y adoptado por herramientas como Claude, Pi u OpenCode) es un elemento clave del "arnés de usuario" diseñado para guiar de forma automática a los agentes de programación.

info

Podemos decir que un AGENTS.md es como un README pero para agentes: un archivo dedicado para proveer el contexto y las instrucciones a los agentes de código para trabajar en tu proyecto.

🎧 Podcast: AGENTS.md

Aquí tienes los puntos clave sobre su funcionamiento, jerarquía y mejores prácticas según las fuentes:

1. Propósito principal​

  • Contexto persistente: Sirve para dar instrucciones específicas al agente sobre cómo trabajar en un proyecto sin tener que repetir las reglas en cada prompt.
  • Comprensión de la arquitectura: Permite que la IA comprenda la estructura del repositorio, las convenciones del código y el stack de tecnologías utilizado.

2. Jerarquía de carga (¿Cómo lo procesa la IA?)​

Por nuerma general, el agente busca y carga de forma jerárquica los archivos de contexto al iniciar la sesión:

  • Instrucciones globales: Carga primero el archivo global en ~/.[coding-agent]/AGENTS.md.
  • Instrucciones locales: Carga los archivos AGENTS.md (o CLAUDE.md) desde los directorios padres hasta llegar al directorio actual de trabajo ~/mi-proyecto/AGENTS.md.
  • Sobrescritura: Algunos agentes soportan la sobrescritura del AGENTS.md; es decir, si un subdirectorio del proyecto contiene un archivo llamado AGENTS.override.md, el agente cargará este archivo en lugar del local estándar para ese directorio específico.
  • Actualización: Si realizas cambios en el archivo, debes reiniciar el agente o ejecutar un comando de reload (depende del agente) para que asimile los nuevos parámetros.
nota

Los procesos de carga y comandos pueden variar segun el agente usado. Consulta la documentación oficial de tu agente para conocer en profundidad cómo soporta AGENTS.md.

3. Contenido y estructura típica​

El archivo se escribe en formato Markdown y suele contener instrucciones precisas con viñetas, listas numeradas y bloques de código. Algunos elementos comunes son:

  • Comandos de verificación: Qué comandos ejecutar tras realizar cambios en el código (ej. Run npm run check after code changes).
  • Restricciones de seguridad: Qué cosas tiene estrictamente prohibido hacer (ej. Do not run production migrations locally).
  • Estilo de comunicación: Cómo prefieres las respuestas (ej. Keep responses concise).
~/mi-proyecto/AGENTS.md
# AGENTS.md

## Setup
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

## Testing
...

## Not obvious conventions
- All monetary amounts are stored in cents (integers), never decimals
- Types in `src/types/generated/` are regenerated with `pnpm types`, do not edit
- Dates are always stored in UTC in the database, convert to local time in the view

## Don't change
- `migrations/` — do not change applied migrations, add new ones instead
- `src/legacy/billing/` — forzen legacy application, do not modify

## Topics docs
- API Design Patterns (`docs/api-patterns.md`) — Required reading when adding endpoints
- Database Rules (`docs/database-rules.md`) — Required when modifying database operations
- Testing Standards (`docs/testing-standards.md`) — Reference when writing tests

4. Buenas prácticas de uso​

  • Añádelo a Git: se recomienda encarecidamente subir y versionar el archivo AGENTS.md en Git para que todo el equipo (y la IA) compartan las mismas instrucciones.
  • Mantenerlo actualizado: actualiza junto con el código. Vincula las actualizaciones de conocimiento a los cambios de código.
  • Mínimo pero completo: No necesita contener toda la información, pero debe permitir que el agente responda rápido tres preguntas: "Qué es este proyecto", "Cómo lo ejecuto" y "Cómo lo verifico". 50-100 líneas bastan.
  • Referencia otros docs: puedes referenciar otros archivos con información relevante, esto optimiza el contexto y evita problemas al generar AGENTS.md demasiado grandes.
  • Evita información sensible: no incluyas secretos, contraseñas ni datos privados. El AGENTS.md es para el agente, no para humanos.
  • Escribe en inglés: la mayoría de agentes funcionan mejor con prompts en inglés, aunque algunos soportan varios idiomas. Si tu equipo es multilingüe, considera mantenerlo en inglés para compatibilidad y optimización de tokens.

Ejemplos de prompt para la creación de un AGENTS.md:​

Prompt custom para crear un AGENTS.md de un proyecto WordPress. Puedes copiarlo y adaptarlo a tu caso de uso.

Generador de AGENTS.md para WordPress
Crear un AGENTS.md para un proyecto WordPress
Genera un archivo AGENTS.md para este proyecto WordPress.

PRINCIPIO GUÍA: el AGENTS.md es la página de aterrizaje del agente. No necesita
contener toda la información, sólo permitir que el agente responda rápido a
estas preguntas:
- ¿Qué es este proyecto?
- ¿Cómo lo ejecuto?
- ¿Cómo lo verifico?
- ¿Cómo está organizado? → ARCHITECTURE.md o docs/
- ¿Dónde estamos ahora? → PROGRESS.md, feature_list, historial git o plans/

50-200 líneas bastan. Todo lo que no quepa aquí sin romper ese límite va en un
directorio docs/ (un .md por tema), enlazado desde la sección correspondiente.

Analiza el repo (wp-config.php, composer.json/package.json, estructura de
plugins/theme custom, .env.example si existe, historial git reciente) y
completa estas secciones, sólo si aportan a las preguntas anteriores:

1. Qué es — una o dos frases: qué hace el sitio/negocio, stack (WP + PHP +
   servidor + BD) en una línea.
2. Cómo lo ejecuto — comandos exactos y copy-paste-ready: instalación local,
   build de assets si hay JS/CSS compilado, comandos WP-CLI habituales.
   Entornos típicos usados en mis proyectos: DDEV, Docker-compose, Laragon, WP Studio, Local by Flywheel, YERD, LERD, COVE.run
3. Cómo lo verifico — comandos ejecutables reales (tests, linter, build)
   cuyo resultado indique éxito/fallo sin ambigüedad.
4. Cómo está organizado — sólo carpetas donde vive código custom, como theme
   activo (por lo general en theme/XXXX-child) y plugins propios; omite lo estándar de WordPress. Si hay más
   detalle relevante, enlaza a ARCHITECTURE.md o docs/ARCHITECTURE.md.
5. Dónde estamos ahora — estado actual del proyecto: qué está en curso, qué
   falta, qué se rompió recientemente. Si existe PROGRESS.md, feature_list,
   o carpeta plans/, enlázalos aquí en vez de duplicar su contenido; si no
   existen pero el historial git reciente lo sugiere, resume en 2-3 líneas.
6. Convenciones — sólo lo que no es obvio ni deducible con un vistazo al
   código (hooks propios, decisiones no estándar, namespaces).
7. Integraciones externas — APIs, pasarelas de pago, servicios de terceros
   con los que interactúa el código.
8. Cuidado con... — trampas conocidas: qué no tocar sin confirmación
   (wp-config, BD en producción, plugins parcheados). Si existe
   CONSTRAINTS.md, enlázalo aquí.

Reglas:
- Prioriza lo que un agente adivinaría mal sobre lo que es obvio en el código.
- Nunca incluyas credenciales ni secretos, ni de ejemplo — sólo referencia a
  dónde están (.env.example, gestor de secretos).
- Si ya existe ARCHITECTURE.md, CONSTRAINTS.md o PROGRESS.md en el repo,
  enlázalos en la sección correspondiente en vez de duplicar su contenido.
- Si una sección necesita más detalle del que cabe en pocas líneas, crea o
  actualiza un archivo en docs/ (ej. docs/deployment.md, docs/testing.md) y
  deja en AGENTS.md sólo la línea con el enlace.
- Jerarquía plana: encabezados de un sólo nivel cuando sea posible.
- Sólo lo cierto hoy en el repo. Nada aspiracional ni especulativo.
- Si algo no se puede deducir del repo, márcalo como TODO breve — nunca
  inventes ni rellenes con un párrafo para "completar" la sección. 
  Consulta al usuario si tienes dudas pero sólo en caso de ser información estrictamente necesaria 
  para completar el AGENTS.md.
- Al terminar, poda: si una sección no ayuda a responder ninguna de las
  preguntas anteriores, resúmela a una línea o elimínala.

Creación rápida: en la mayoria de herramientas, puedes usar el comando /init (o similar) para que analice tu repositorio y autogenere la plantilla inicial en la raíz de tu proyecto.

Opencode y Kilo Code prompt para generar AGENTS.md
https://github.com/kilo-org/kilocode/blob/ff74e2ea/packages/opencode/src/command/template/initialize.txt
Create or update `AGENTS.md` for this repository.

The goal is a compact instruction file that helps future Kilo sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.

User-provided focus or constraints (honor these):
$ARGUMENTS

## How to investigate

Read the highest-value sources first:
- `README*`, root manifests, workspace config, lockfiles
- build, test, lint, formatter, typecheck, and codegen config
- CI workflows and pre-commit / task runner config
- existing instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
- repo-local Kilo config such as `kilo.json`

If architecture is still unclear after reading config and docs, inspect a small number of representative code files to find the real entrypoints, package boundaries, and execution flow. Prefer reading the files that explain how the system is wired together over random leaf files.

Prefer executable sources of truth over prose. If docs conflict with config or scripts, trust the executable source and only keep what you can verify.

## What to extract

Look for the highest-signal facts for an agent working in this repo:
- exact developer commands, especially non-obvious ones
- how to run a single test, a single package, or a focused verification step
- required command order when it matters, such as `lint -> typecheck -> test`
- monorepo or multi-package boundaries, ownership of major directories, and the real app/library entrypoints
- framework or toolchain quirks: generated code, migrations, codegen, build artifacts, special env loading, dev servers, infra deploy flow
- repo-specific style or workflow conventions that differ from defaults
- testing quirks: fixtures, integration test prerequisites, snapshot workflows, required services, flaky or expensive suites
- important constraints from existing instruction files worth preserving

Good `AGENTS.md` content is usually hard-earned context that took reading multiple files to infer.

## Questions

Only ask the user questions if the repo cannot answer something important. Use the `question` tool for one short batch at most.

Good questions:
- undocumented team conventions
- branch / PR / release expectations
- missing setup or test prerequisites that are known but not written down

Do not ask about anything the repo already makes clear.

## Writing rules

Include only high-signal, repo-specific guidance such as:
- exact commands and shortcuts the agent would otherwise guess wrong
- architecture notes that are not obvious from filenames
- conventions that differ from language or framework defaults
- setup requirements, environment quirks, and operational gotchas
- references to existing instruction sources that matter

Exclude:
- generic software advice
- long tutorials or exhaustive file trees
- obvious language conventions
- speculative claims or anything you could not verify
- content better stored in another file referenced via `kilo.json` `instructions`

When in doubt, omit.

Prefer short sections and bullets. If the repo is simple, keep the file simple. If the repo is large, summarize the few structural facts that actually change how an agent should work.

If `AGENTS.md` already exists at `${path}`, improve it in place rather than rewriting blindly. Preserve verified useful guidance, delete fluff or stale claims, and reconcile it with the current codebase.
Última actualización en