Agent Context Files: `CLAUDE.md`, `AGENTS.md` y mirrors

Cada workspace AWaC genera, tras wsp bootstrap o wsp sync, archivos de contexto que cualquier agente IA que abra el workspace lee al iniciar. Esto hace que el workspace sea agnóstico al editor: el mismo workspace funciona en Claude Code, Cursor, OpenAI Codex, Aider sin renombrar nada.

El problema que resuelve

Cada agente busca su archivo “de fábrica” en lugares distintos:

Agente	Archivo que busca
Claude Code	CLAUDE.md
OpenAI Codex	AGENTS.md (plural)
Cursor (versión moderna)	AGENTS.md
Cursor (legacy)	.cursorrules o .cursor/rules/*.mdc
Aider	AGENTS.md o CONVENTIONS.md

Si un dev del equipo trabaja en Cursor y otro en Claude Code, no podemos pedirle a cada uno que renombre el archivo. AWaC genera los necesarios automáticamente.

Default recomendado

# <transversal-org>/agent-stack-core/awac.yml
agent_context:
  canonical: CLAUDE.md
  mirrors:
    - AGENTS.md

Cubre el ecosistema mainstream con dos archivos:

Archivo	Propósito	Cubre
CLAUDE.md	Canónico — donde vive el bloque editable a mano	Claude Code
AGENTS.md	Mirror — regenerado en cada sync	OpenAI Codex, Cursor moderno, Aider, AGENTS.md spec

¿Por qué solo dos? AGENTS.md cubre Codex, Cursor y Aider (3 herramientas). CLAUDE.md cubre Claude Code (otra herramienta). Entre ambos, ~95% de los devs en cualquier equipo. AGENT.md (singular) y CONVENTIONS.md se descartaron porque son demasiado nicho.

Cómo funciona la composición

1. El canónico se escribe primero

wsp bootstrap / wsp sync genera el archivo CLAUDE.md componiéndolo desde:

1. Stack core (sus secciones contribuibles).
2. Cada stack adicional declarado en stacks: (en orden).
3. Bloque editable preservado del archivo previo (entre marcadores <!-- @awac:editable-start --> y <!-- @awac:editable-end -->).

2. Los mirrors se generan iguales al canónico

Cada archivo en mirrors: recibe el mismo contenido que el canónico, con un header de “no editar”:

<!-- Generated by AWaC. Edit CLAUDE.md (canonical). This file is regenerated on `wsp sync`. -->

# ... (contenido idéntico al canónico)

3. El bloque editable te pertenece

En el canónico (CLAUDE.md), entre los marcadores, podés escribir notas específicas del workspace que NO pertenecen a ningún stack:

<!-- @awac:editable-start -->
## Notas del workspace billing-feature

- El cliente cambió de opinión sobre la integración con Stripe — ahora quieren PayPal también.
- Branch del orchestrator está en `feature/payments-v2`, no `develop`.
- Reunión de definición agendada para el martes.
<!-- @awac:editable-end -->

wsp sync preserva este bloque entre regeneraciones. Los mirrors lo replican.

4. Detección de drift en mirrors

Si vos (o un agente) editás un mirror a mano (digamos AGENTS.md), wsp status reporta:

WARN: AGENTS.md was edited locally but is a mirror of CLAUDE.md.
Your changes will be overwritten on `wsp sync`. Move them to CLAUDE.md
(within the editable block) to preserve them.

El agente que detecta el warning puede mover el contenido al canónico automáticamente y re-correr sync.

Override por workspace

Si tu workspace necesita archivos extra (porque algún dev usa Cursor con el formato legacy, o Copilot, o Aider con CONVENTIONS.md), declaralo en workspace.yml:

agent_context:
  canonical: CLAUDE.md
  mirrors:
    - AGENTS.md
  extras:
    - path: .cursorrules
      header: false                  # Cursor legacy no parsea bien HTML comments
    - path: .github/copilot-instructions.md
      header: true

Cada extra recibe el mismo contenido que el canónico, con (o sin) header según se configure.

Caso especial: Cursor con .cursor/rules/*.mdc

Cursor reciente usa archivos individuales por regla en .cursor/rules/. Si tu equipo es heavy user de Cursor:

agent_context:
  extras:
    - format: cursor-rules-dir
      path: .cursor/rules/
      # AWaC genera un .mdc por cada rule de los stacks activos

Cada rule del stack se transforma en un archivo individual .cursor/rules/<rule_name>.mdc con la sintaxis de Cursor. Más limpio para usuarios pesados de Cursor.

Anatomía del CLAUDE.md generado

Un CLAUDE.md típico tras bootstrap se ve así:

<!-- AWaC composed CLAUDE.md — workspace: billing-feature -->
<!-- Stacks active: core, aws, my-product -->
<!-- Generated 2026-05-02T14:23:11Z. Edit only within the editable block. -->

# AWaC Workspace: billing-feature

## Active stacks

- **core** (`<transversal-org>/agent-stack-core@a1b2c3`)
- **aws** (`<transversal-org>/agent-stack-aws@d4e5f6`)
- **my-product** (`<my-product-org>/agent-stack@g7h8i9`)

## Universal rules (from core)

[contenido stitched de las rules más importantes de core]

## AWS-specific rules (from aws)

[contenido]

## Product-specific rules (from my-product)

[contenido]

## Available skills

[lista enumerada de skills cargadas, con purpose de cada una]

## Available workflows

[lista enumerada]

## Workspace notes

<!-- @awac:editable-start -->
(escribí acá tus notas específicas; sobreviven a `wsp sync`)
<!-- @awac:editable-end -->

El AGENTS.md tiene el mismo contenido (con header de “no editar” arriba).

Reglas de regeneración

1. El bloque editable a mano vive solo en el canónico entre marcadores.
2. wsp sync:
   • Lee el canónico → extrae el bloque editable.
   • Recompone el resto desde los stacks activos.
   • Escribe el canónico con el bloque editable preservado.
   • Escribe cada mirror con el mismo contenido (excepto el header de “no editar”).
3. Detección de drift: si un mirror fue editado a mano (su contenido difiere del canónico), wsp status lo reporta antes de sobrescribir.

Anti-patterns

• ❌ Editar mirrors a mano: tus cambios se pierden en el próximo sync. Editá solo el canónico.
• ❌ Editar fuera del bloque editable en el canónico: tus cambios se pierden en el próximo sync. Las secciones generadas desde stacks NO son lugar para anotaciones — esas van al bloque editable.
• ❌ Versionar el bloque editable como parte de un stack: si tu nota es genérica y aplica a múltiples workspaces, debe ser una rule del stack apropiado, no una nota local.

Cómo se relaciona con wsp promote

Si en el bloque editable escribís algo y te das cuenta “esto debería ser una rule de core o de un stack de producto para todos los workspaces”, lo movés del bloque editable a .agents/rules/<nombre>.md. Después corrés wsp promote .agents/rules/<nombre>.md y se abre PR contra el stack correspondiente.

Es decir: el bloque editable es la incubadora de aprendizajes que aún no maduraron a regla. Cuando maduran, se promueven al stack.

Decisiones detrás del diseño

• Por qué CLAUDE.md como canónico: es el archivo que más tiempo lleva en el ecosistema y el que más herramientas reconocen.
• Por qué AGENTS.md como único mirror: cubre el resto del ecosistema mainstream (Codex, Cursor, Aider) con un solo archivo. Sumar más mirrors es ruido innecesario.
• Por qué no incluir AGENT.md (singular) ni CONVENTIONS.md: son demasiado nicho. Si algún workspace específico los necesita, los agrega como extras opt-in.

Ver también

• 03-manifest-reference.md — schema de agent_context en workspace.yml.
• 04-stack-reference.md — schema de agent_context en core.
• 02-architecture.md — modelo conceptual de composición.