AGENTS.md con OpenSpec

Dos herramientas, un objetivo

AGENTS.md y OpenSpec resuelven problemas diferentes pero complementarios:

Herramienta	Que resuelve
AGENTS.md	Como debe comportarse el agente al trabajar en tu proyecto
OpenSpec	Que debe construir el agente y en que orden

AGENTS.md da contexto persistente (stack, convenciones, boundaries). OpenSpec da estructura al cambio (proposal, specs, design, tasks).

El flujo combinado

AGENTS.md          → Contexto del proyecto (siempre presente)
config.yaml        → Contexto de OpenSpec (artefactos, rules)
CLAUDE.md          → Bridge + extensiones Claude Code
                   ↓
openspec new       → Crear cambio
openspec ff        → Generar artefactos (usando contexto de AGENTS.md + config.yaml)
/opsx:apply        → Implementar (siguiendo AGENTS.md + CLAUDE.md)
openspec verify    → Validar
openspec archive   → Cerrar ciclo

El agente recibe instrucciones de las 3 fuentes simultaneamente. Cada una tiene su rol.

Que va en cada archivo

AGENTS.md: contexto universal del proyecto

E-commerce API. Hono + TypeScript + PostgreSQL.

## Commands
- Test: `bun test`
- Lint: `bunx biome check src/`
- Build: `bun run build`

## Code style
- Hexagonal architecture
- Files under 150 lines
- Named exports only

## Boundaries
- Never commit secrets
- Always run tests after changes
- Ask before adding dependencies

config.yaml: contexto de OpenSpec

schema: spec-driven

context: |
  ## Stack
  - Hono 4, TypeScript 5.7, PostgreSQL 17
  - Testing: Vitest 3
  - Linting: Biome 2

rules:
  tasks: |
    Include test tasks for every new module.
  design: |
    Include Security section for endpoints handling user data.

CLAUDE.md: bridge + extensiones

@AGENTS.md

## OpenSpec
Este proyecto usa OpenSpec para spec-driven development.
- Directorio: `openspec/`
- Schema: spec-driven
- Antes de implementar, verificar que existen artefactos en `openspec/changes/`

Evitar duplicacion de contexto

El error mas comun es repetir el stack en AGENTS.md y en config.yaml. Esto desperdicia tokens y crea riesgo de divergencia.

Estrategia: dividir responsabilidades

Informacion	Donde va
Comandos de build/test/lint	AGENTS.md
Tech stack (versiones)	AGENTS.md
Convenciones de codigo	AGENTS.md
Boundaries de seguridad	AGENTS.md
Rules por artefacto (tasks, design, specs)	config.yaml
Prioridades de generacion de artefactos	config.yaml
Skills y sub-agentes	CLAUDE.md

Referenciar en vez de repetir

En config.yaml, puedes referenciar AGENTS.md:

context: |
  See AGENTS.md for project stack, conventions, and boundaries.

  ## OpenSpec-specific
  - Idioma de artefactos: espanol
  - Terminos tecnicos en ingles

rules:
  tasks: |
    Follow boundaries from AGENTS.md.
    Include test tasks for every new module.

Patron: AGENTS.md como fuente, OpenSpec como estructura

Piensa en los tres archivos como capas:

┌─────────────────────────────────┐
│         CLAUDE.md               │  ← Bridge + extensiones Claude
│  @AGENTS.md                     │
│  Skills, MCP, sub-agentes       │
├─────────────────────────────────┤
│         config.yaml             │  ← Estructura del cambio
│  Rules por artefacto            │
│  Schema de workflow             │
├─────────────────────────────────┤
│         AGENTS.md               │  ← Contexto base universal
│  Stack, comandos, boundaries    │
│  Convenciones, estructura       │
└─────────────────────────────────┘

Cada capa agrega valor sin repetir la anterior.

Ejemplo practico

Tienes un proyecto con AGENTS.md + OpenSpec + Claude Code. Quieres agregar autenticacion.

1. AGENTS.md ya tiene el contexto base

El agente sabe: stack, convenciones, boundaries, comandos.

2. Creas el cambio con OpenSpec

openspec new add-auth --description "JWT auth with login and register"
openspec ff add-auth

OpenSpec genera artefactos usando el contexto de AGENTS.md + config.yaml. Las tasks incluyen tests porque config.yaml tiene esa regla.

3. Implementas con apply

/opsx:apply

Claude Code implementa siguiendo:

• AGENTS.md: convenciones de codigo, boundaries (no hardcodear secretos, validar inputs)
• config.yaml rules: las tasks ya incluyen testing
• CLAUDE.md: prioridades de Claude (seguridad primero, archivos < 150 lineas)

4. Todo se refuerza mutuamente

Si AGENTS.md dice “never commit secrets” y config.yaml tiene una rule de seguridad en design, el agente:

• No hardcodea JWT secrets en el codigo (AGENTS.md boundary)
• Incluye seccion de seguridad en el design (config.yaml rule)
• Valida inputs con Zod (CLAUDE.md prioridad)

Resumen

• AGENTS.md da contexto universal, OpenSpec da estructura al cambio
• Dividir responsabilidades: no repetir stack en ambos archivos
• AGENTS.md = base, config.yaml = reglas de artefactos, CLAUDE.md = bridge
• Los tres se refuerzan: boundaries + rules + prioridades trabajan juntos
• Referenciar entre archivos en vez de duplicar contenido

---

← Capitulo 7: AGENTS.md con Claude Code | Capitulo 9: Ecosistema de Herramientas →