DLN.

Prepara tu codebase para los agentes

Prepara tu codebase para los agentes
English English Español Español Français Français

Estás ahogándote en herramientas de código IA ahora mismo. Claude Code, Cursor, Aider, AMP, Droid—quizás estás usando todas a la vez. He estado exactamente donde tú estás. Y aquí está el problema: cada una de estas herramientas quiere su propia forma especial de cargar reglas, habilidades y comandos.

¿El resultado? Duplicación por todas partes. Las mismas instrucciones dispersas en cinco carpetas de configuración diferentes. Créeme, es una pesadilla.

Déjame mostrarte cómo lo solucioné.

El Problema

Imagina esto, amigo. Escribes una directriz de código una vez. Luego la copias a .claude/, a .cursor/, a .aider.conf.yml. Una semana después actualizas el original. Ahora tus configs están completamente desincronizadas.

Esto no es sostenible. Y lo sabes.

Necesitas una única fuente de verdad para todas tus instrucciones de agentes. Un solo lugar. No cinco.

La Solución

Esto es lo que realmente funciona: un único archivo AGENTS.md en la raíz de tu proyecto, más un directorio agents/ para contenido modular.

Piensa en AGENTS.md como el índice. La tabla de contenidos. El jefe. Cada herramienta apunta hacia él.

agents/
├── rules/
│   ├── python.md
│   ├── nextjs.md
│   ├── security.md
│   └── ...
├── skills/
│   ├── testing.md
│   ├── infrastructure.md
│   ├── refactoring.md
│   └── ...
├── commands/
│   ├── fix-tests.md
│   ├── fix-linter.md
│   ├── add-feature.md
│   └── ...
└── scripts/
    ├── parse_test_coverage.py
    ├── run_linter_fix.sh
    └── ...

Tu AGENTS.md se convierte en el hub central:

  • Instrucciones obligatorias arriba
  • Secciones para reglas, habilidades, comandos con referencias estilo @ donde sea soportado
  • Guía de carga clara (“Siempre cargar rules/python.md para archivos Python”)

Ahora configuremos cada herramienta para que apunte aquí. Te guiaré a través de cada una.

Configuración de Herramientas

Primero las Buenas Noticias

Aquí hay algo que te hará la vida más fácil. Muchas herramientas ahora soportan habilidades compatibles con Claude (el formato .claude/skills/):

  • OpenCode
  • AMP
  • Cursor

¿Por qué importa esto? Porque puedes compartir archivos de habilidades entre ellas con cambios mínimos. Un formato, múltiples herramientas. Escribe una vez, usa en todas partes.

Claude Code

Docs: Skills • Changelog

Directorio: .claude/

Estado (2026): Los comandos slash y las habilidades ahora están unificados (v2.1+). Tus archivos de comandos existentes siguen funcionando.

Crea .claude/skills/my-skill/SKILL.md:

---
description: Brief purpose of this skill
user-invocable: true           # optional: show in / menu
---

# My Skill

Follow the relevant instructions in `AGENTS.md` (usually under /skills/ or /commands/).
Load matching content from agents/ when the task matches.

Y tu CLAUDE.md (o mejor, usa AGENTS.md directamente):

## Mandatory

- **ALWAYS** read and follow `AGENTS.md` at the project root before any action.
- For language-specific rules, load from `agents/rules/`.
- For task patterns, reference `agents/skills/` or `agents/commands/`.

OpenCode

Docs: Rules • Skills • Commands

Directorio: Raíz del proyecto (no se necesita carpeta obligatoria)

OpenCode ya prefiere AGENTS.md nativamente. Usa CLAUDE.md como respaldo si es necesario. Esta es la configuración más fácil que verás hoy.

¿Quieres incluir más archivos automáticamente? Crea opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENTS.md",
    "agents/rules/*.md"
  ]
}

Listo. Eso es todo.

AMP

Docs: Agent Skills • Custom Commands

Directorio: .agents/

Crea .agents/skills/my-skill/SKILL.md (formato compatible con Claude):

---
description: [your description]
---

# My Skill

Read and follow instructions in `AGENTS.md` — usually under agents/skills/.

Para comandos, usa .agents/commands/my-command-name.md:

---
name: my-command-name
description: [brief description]
---

# My Command

Follow the matching section in `AGENTS.md`.

Aider

Docs: Config Reference

Archivo: .aider.conf.yml (o ~/.aider.conf.yml)

Esta es la configuración más simple de todas. En serio:

read:
  - AGENTS.md
  - agents/rules/python.md     # optional: include specific rules

Aider carga estos archivos en el contexto automáticamente. Boom. Ya terminaste.

Droid

Docs: Skills • Custom Slash Commands

Directorio: .factory/

Crea .factory/skills/my-skill/SKILL.md:

---
description: [your description]
---

# My Skill

Refer to `AGENTS.md` for detailed instructions (agents/skills/ section).

Los comandos funcionan igual en .factory/commands/.

Cursor

Docs: Rules • Skills • Commands

Directorio: .cursor/

Aquí está el truco con Cursor: carga automáticamente AGENTS.md cuando está presente. No necesita configuración. Cero esfuerzo.

Pero si quieres asegurarte absolutamente de que tus reglas siempre se apliquen, crea .cursor/rules/general.mdc:

---
description: Core project instructions — always apply
alwaysApply: true
---

## Mandatory Instructions

- **ALWAYS** read `AGENTS.md` at project root.
- Load relevant rules from `agents/rules/` based on file type.
- Use `@agents/skills/...` syntax to reference skills when applicable.

Las habilidades y comandos siguen el formato compatible con Claude.

Antigravity

Docs: Rules & Workflows • Skills

Directorio: .agent/ (proyecto) o global ~/.gemini/

Crea .agent/rules/general.md:

---
description: Always read this before anything
trigger: always_on
---

## Core Rules

- **ALWAYS** read `AGENTS.md`.
- Reference `agents/` subfolders as needed.

Las habilidades usan el formato estándar en .agent/skills/my-skill/SKILL.md.

Consejos Que Realmente Importan

Déjame compartir lo que aprendí de la manera difícil.

Mantén AGENTS.md bajo 400-500 líneas. La presión de contexto es real. Tu IA solo puede mantener cierta cantidad de información en su memoria de trabajo antes de que las cosas empiecen a ponerse borrosas.

Usa encabezados Markdown y anclas. ¿Por qué? Porque hace que referenciar secciones específicas sea trivialmente fácil. Tu yo del futuro te lo agradecerá.

Para equipos: commitea agents/ y AGENTS.md en git. Considera symlinks o submódulos para reglas compartidas entre proyectos. Así es como se escala.

Prueba tu configuración. Pregunta a cada herramienta “Explica las reglas del proyecto” y verifica que referencie AGENTS.md. Si no lo hace, tu configuración está rota. Arréglala ahora.

Y por favor—nunca pongas secretos en estos archivos. No debería tener que decirlo, pero lo he visto pasar. Usa variables de entorno o vaults seguros. Siempre.

El Beneficio

Un solo lugar para todas tus instrucciones de agentes. Actualiza una vez, cada herramienta lo recoge.

No más duplicación. No más desincronización. No más caos.

Esto es todo. Así es como debería funcionar.