gonzalezpazmonica/agent-code-map

Agent Code Map — Mapas Estructurales Persistentes

Genera ficheros .acm (Agent Code Map) pre-calculados que los agentes cargan al inicio de cada sesión. Elimina la exploración ciega de arquitectura.

Cuándo usar

• Inicio de pipeline SDD (/codemap:load): dar contexto de arquitectura al agente
• Post-sprint (/codemap:refresh): mantener mapas actualizados tras cambios
• Nuevo proyecto (/codemap:generate): generar mapas iniciales desde cero
• Verificación (/codemap:check): detectar mapas obsoletos o rotos

Comandos slash

| Comando | Descripción | |---------|-------------| | /codemap:generate [scope] | Genera todos los .acm para el proyecto o scope | | /codemap:check | Verifica frescura de todos los .acm (fresco/obsoleto/roto) | | /codemap:load <scope> | Carga los .acm relevantes en el contexto del agente | | /codemap:refresh --incremental | Regenera solo los .acm cuyo código fuente cambió | | /codemap:stats | Muestra: total .acm, líneas, estado de frescura, cobertura |

Formato .acm

Cada fichero .acm es Markdown con estructura fija:

# [Capa] — [Descripción] (.acm)
> hash: sha256:[HASH_CODIGO_FUENTE] | generated: YYYY-MM-DD | lines: N

## [Entidad/Módulo]
- **Tipo**: Clase | Interface | Servicio | Repositorio | Controller
- **Fichero**: `src/ruta/al/fichero.ext:LINEA`
- **Propósito**: [descripción 1 línea]
- **Dependencias**: [lista de dependencias clave]
- **API pública**: [métodos/endpoints expuestos]

@include domain/entities.acm   ← carga bajo demanda

INDEX.acm — Punto de entrada

# INDEX — Agent Code Map (.acm)
> hash: [HASH] | generated: YYYY-MM-DD | project: [nombre]

## Navegación por capa

| Capa | Fichero | Elementos | Prioridad |
|------|---------|-----------|-----------|
| Domain Entities | domain/entities.acm | N entidades | 🔴 Alta |
| Domain Services | domain/services.acm | N servicios | 🔴 Alta |
| Infrastructure | infrastructure/repositories.acm | N repos | 🟡 Media |
| API | api/controllers.acm | N controllers | 🟡 Media |

## Cargar por scope

- Todo: `@include domain/entities.acm`, `@include domain/services.acm`, ...
- Solo dominio: `@include domain/entities.acm`, `@include domain/services.acm`
- Solo API: `@include api/controllers.acm`

Estructura en disco

.agent-maps/
├── INDEX.acm              ← Siempre cargar primero
├── domain/
│   ├── entities.acm       ← Entidades de dominio
│   └── services.acm       ← Servicios de negocio
├── infrastructure/
│   └── repositories.acm   ← Repositorios y acceso a datos
└── api/
    └── controllers.acm    ← Controllers y endpoints

Modelo de frescura

| Estado | Condición | Acción del agente | |--------|-----------|------------------| | fresco | Hash .acm coincide con código fuente | Usar directamente | | obsoleto | Cambios internos, estructura intacta | Usar con aviso | | roto | Ficheros eliminados o firmas públicas cambiadas | Regenerar antes de usar |

Cálculo de hash: sha256 del contenido de todos los ficheros fuente del scope.

Sistema @include

Los agentes cargan .acm bajo demanda para minimizar tokens:

@include domain/entities.acm     ← Se resuelve en runtime
@include domain/services.acm     ← Solo si el agente lo necesita

Reglas: máximo 150 líneas por .acm. Si crece, dividir en subdirectorios: domain/entities/user.acm, domain/entities/order.acm, etc.

Integración en pipeline SDD

[0] CARGAR  — /codemap:check && /codemap:load <scope>
[1] Análisis — business-analyst lee spec + mapas
[2] Arquitectura — architect planifica con contexto real
[3] Spec    — sdd-spec-writer genera spec ejecutable
[4] Impl    — {lang}-developer implementa con mapas cargados
[5] QA      — test-engineer valida cobertura
[post-SDD]  ACTUALIZAR — /codemap:refresh --incremental

Gemelo humano: .hcm

Cada .acm tiene un gemelo narrativo: el .hcm (Human Code Map). Mientras el .acm responde "qué existe y dónde", el .hcm responde "por qué existe y cómo pensarlo".

| Dimensión | .acm (este skill) | .hcm (human-code-map) | |-----------|------------------|----------------------| | Audiencia | Agentes de IA | Desarrolladores humanos | | Lenguaje | Estructurado, denso | Narrativo, natural | | Contenido | Qué existe y dónde | Por qué existe y cómo pensarlo | | Frescura | Hash automático | last-walk actualizable solo por humano |

Directorio: .human-maps/ (paralelo a .agent-maps/). Skill: human-code-map.

Si .acm cambia (hash inválido) → .hcm se marca automáticamente como stale.

Anti-patterns

• NUNCA generar .acm con datos de proyectos privados de cliente (→ N4)
• NUNCA commitear .acm con información sensible al repo público
• NUNCA crear .acm de más de 150 líneas — dividir siempre
• NUNCA usar .acm roto sin regenerar primero