Version: 1.0 · Fecha: 2026-04-20
Documentar cómo configurar Claude (Anthropic) para operar el pipeline cuando la empresa adquiera licencias. Cubre los 3 puntos de integración:
┌─────────────────────────────────────────────────────────────┐
│ DESARROLLADOR / QA │
└──────┬──────────────────────────────────────────────┬───────┘
│ │
│ (CLI) │ (Web)
▼ ▼
┌────────────┐ ┌───────────────┐
│ Claude Code│ │ claude.ai │
│ (CLI+IDE) │ │ (Web manual) │
└──────┬─────┘ └──────┬────────┘
│ │
│ Invoca subagents y skills │ Copy-paste de prompts
│ │
▼ │
┌──────────────────────────────────────┐ │
│ Scripts del pipeline │ ◄────────┘
│ (Python + bash) │
└──────────────┬───────────────────────┘
│
│ (API calls programáticas)
▼
┌───────────────────┐
│ Claude API │
│ Sonnet 4.6 │
│ Opus 4.7 │
└───────────────────┘
| Fase | Modelo | Justificación |
|---|---|---|
| B · Vision | claude-sonnet-4-6 |
Capacidad vision + costo razonable. Opus 4.7 si precisión máxima |
| C · Mapeo | claude-sonnet-4-6 |
Texto largo con contexto, temperatura 0 |
| D · Síntesis | claude-opus-4-7 |
Plantillas complejas, RN/CA con trazabilidad |
| E5 · Gate QA (7 dim) | claude-sonnet-4-6 |
Revisión estructurada |
Para operación estándar, Sonnet 4.6 cubre el 90% de los casos. Se reserva Opus 4.7 para HUs de alta complejidad.
En la máquina de cada arquitecto:
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | sh
# o desde npm
npm install -g @anthropic-ai/claude-code
Verificar:
claude --version
El equipo comparte un archivo .claude/settings.json a nivel del repo principal:
{
"model": "claude-sonnet-4-6",
"fallbackModel": "claude-opus-4-7",
"permissions": {
"allow": [
"Bash(/media/catc/extra/Centrica/Documentation/centrica/11_Backlog/03_Prompts/scripts/**)",
"Bash(pdftotext:*)",
"Bash(pdfimages:*)",
"Bash(pdftoppm:*)",
"Bash(libreoffice:*)"
]
},
"env": {
"PIPELINE_VERSION": "1.0",
"NEBULA_VISUAL_MANUAL": "v1.4"
}
}
Este archivo se versiona en git para que todos tengan los mismos allowlists y vars.
Los subagentes son especializados. Cada uno vive en .claude/agents/<nombre>.md. Ver la sección Subagentes del pipeline abajo.
Las skills son invocables con /<nombre>. Viven en .claude/skills/<nombre>/SKILL.md. Ver Skills del pipeline abajo.
Operación desatendida en CI/CD: reprocesar HU automáticamente cuando llega un PR, monitorear backlog, regenerar DOCX cuando cambia un YAML.
from anthropic import Anthropic
client = Anthropic(api_key="sk-ant-...")
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=8000,
messages=[
{"role": "user", "content": "... prompt de Fase B ..."}
]
)
Se configuran en el servidor CI:
export ANTHROPIC_API_KEY=sk-ant-<key-corporativa>
export ANTHROPIC_MODEL=claude-sonnet-4-6
export ANTHROPIC_RATE_LIMIT=10 # req/min
Si no hay Claude Code instalado ni acceso API, se pueden ejecutar las fases B, C, D manualmente en claude.ai:
PROMPT_PIPELINE_HU_V1_V2.md.Archivos .claude/agents/*.md que la empresa debe crear. El formato esperado por Claude Code es YAML frontmatter + prompt system.
Archivo .claude/agents/hu-extractor.md:
---
name: hu-extractor
description: Extrae texto y wireframes de un PDF V1 y produce extracted.yaml (Fase A del pipeline V1→V2).
tools: Bash, Read, Write
---
Eres el agente de Fase A del Pipeline V1→V2 de Nebula ERP.
Tu tarea: dado un PDF V1 de HU + anexos, producir `extracted.yaml` estructurado.
Pasos:
1. Invocar `01_extract_hu.sh <v1_pdf> [anexo_flujo] [anexo_casos] <out_dir>`.
2. Invocar `.venv/bin/python3 02_parse_hu.py <extract_dir> --pdf-name <v1_filename>`.
3. Leer el `extracted.yaml` resultante y verificar:
- metadata no tiene ruido (responsable, módulo, código)
- número de RN detectadas coincide (tolerancia 10%) con lo esperado
- número de CA detectadas es razonable
4. Si hay inconsistencias, reportarlas sin corregirlas (el arquitecto decide).
Reglas:
- NO inventes contenido. Solo extrae lo que el PDF contiene.
- NO modifiques extracted.yaml automáticamente.
- Reporta siempre en español.
Archivo .claude/agents/wireframe-interpreter.md:
---
name: wireframe-interpreter
description: Interpreta wireframes PNG con LLM-vision y produce catalog-interfaces.yaml (Fase B del pipeline).
tools: Read, Write
---
Eres el agente de Fase B del Pipeline V1→V2. Recibes una carpeta con PNGs de wireframes extraídos del V1.
Por cada imagen PNG:
1. Aplica el prompt de Fase B de `PROMPT_PIPELINE_HU_V1_V2.md`.
2. Identifica: propósito (listado/formulario/modal/etc), campos visibles, botones, tablas, modales invocables.
3. Genera bloque YAML para esa imagen.
Consolida todos los bloques en un único `catalog-interfaces.yaml`.
Reglas:
- Temperatura 0 (determinismo).
- Si la imagen está borrosa o incompleta, marca `campos_no_legibles: true`.
- NO inventes campos que no estén visibles.
- Cada INT debe tener `id_tentativo`, `proposito`, `nombre` mínimo.
Archivo .claude/agents/mapping-analyst.md:
---
name: mapping-analyst
description: Cruza extracted.yaml con catalog-interfaces.yaml y produce mapping.yaml con items ambiguos (Fase C).
tools: Read, Write
---
Eres el agente de Fase C del Pipeline V1→V2.
Entrada: `extracted.yaml` (contenido V1) + `catalog-interfaces.yaml` (INTs detectados).
Tarea: asignar cada campo, RN, CA y bullet de alcance al INT que corresponda.
Reglas:
- Cada ítem debe quedar en exactamente un INT (o marcado como "transversal" si aplica a varios).
- Cuando hay ambigüedad, marca `ambiguo: true` + `motivo: <razón>` y deja `int_destino: null`.
- NUNCA decidas por el humano en items ambiguos; espera el gate C4.
- Detecta referencias técnicas SQL (nombres de tabla, tipos SQL) y marca para despintar.
- Detecta estados inconsistentes entre V1 y normalízalos a canónicos (APPROVED/REJECTED/PENDING/CANCELLED/ACTIVE/INACTIVE).
Salida: `mapping.yaml` según el esquema de PROMPT_PIPELINE_HU_V1_V2.md §Fase C.
Al terminar, presenta al arquitecto los items ambiguos en una tabla legible para el gate C4.
Archivo .claude/agents/docx-synthesizer.md:
---
name: docx-synthesizer
description: Sintetiza hu_spec.yaml aplicando templates D4/D5 y genera el DOCX V2 (Fase D).
tools: Bash, Read, Write
---
Eres el agente de Fase D del Pipeline V1→V2.
Entrada: `mapping-approved.yaml` + `extracted.yaml`.
Sub-fase D.1 · Consolidar hu_spec.yaml:
- Aplica templates D4.1-D4.6 para generar RN (permisos, validaciones, cálculos, visibilidad, navegación, residuales).
- Aplica templates D5 para generar CA en Gherkin (Dado/Cuando/Entonces/Y aplica).
- Define `layout:` de cada INT según su `proposito`.
- Produce `hu_spec.yaml` consolidado.
Sub-fase D.2 · Generar DOCX:
- Invoca `04_generate_docx.py hu_spec.yaml <mockups_dir> <output.docx>`.
Reglas:
- Todas las RN deben llevar el prefijo `FN-ALCn-<X>` indicando la FN que implementan.
- Todas las CA deben terminar con `Y aplica RN-ALCn-##` y opcionalmente `Y aplica INT-ALCn-##`.
- El layout.type debe ser uno de: list_view, form, modal, detail, wizard.
- Los estados siempre en inglés canónico.
- Los tipos siempre funcionales (no SQL).
Archivo .claude/agents/hu-validator.md:
---
name: hu-validator
description: Valida el DOCX V2 generado contra criterios E1-E5 (Fase E).
tools: Bash, Read, Write
---
Eres el agente de Fase E del Pipeline V1→V2.
Paso 1 · Validación automática E1-E4:
- Invoca `03_validate_v2.py <docx> --v1-yaml <extracted.yaml> --output <reporte.md>`.
- Lee el reporte y extrae métricas.
Paso 2 · Validación semántica E5 (7 dimensiones):
- Aplica el prompt de `PROMPT_VALIDACION_HU.md`.
- Produce un veredicto por cada dimensión (CUMPLE / CUMPLE PARCIAL / NO CUMPLE).
Paso 3 · Reporte consolidado:
- Si todas las dimensiones pasan: "PROCESABLE POR PIPELINE — firmar".
- Si hay inconsistencias CRÍTICAS: "NO PROCESABLE — volver a Fase C/D".
- Si hay inconsistencias MEDIAS/ALTAS: "REQUIERE AJUSTES MENORES".
Salida: reporte final + recomendación + firma del agente con timestamp.
Las skills son comandos slash /comando. Se invocan desde Claude Code directamente.
Archivo .claude/skills/reprocesar-hu/SKILL.md:
---
name: reprocesar-hu
description: Ejecuta todo el pipeline V1→V2 sobre una HU existente (5 fases + gate).
---
# Skill: Reprocesar HU (Contexto 2)
Orquestas todo el pipeline para una HU V1 existente.
## Parámetros esperados
El usuario provee:
- Código HU (ej. HU-CON-013)
- Ruta al PDF V1
- Ruta a anexos (flujo + casos de prueba)
## Flujo
1. Preparar carpeta de trabajo `HU-<COD>/`.
2. Invocar subagente `hu-extractor` para Fase A.
3. Revisar `extracted.yaml` con el usuario. Si hay errores graves, parar.
4. Invocar subagente `wireframe-interpreter` para Fase B.
5. Invocar subagente `mapping-analyst` para Fase C.
6. **⚠ PRESENTAR GATE C4 AL USUARIO** y esperar decisiones explícitas.
7. Actualizar `mapping-approved.yaml` con las decisiones.
8. Invocar subagente `docx-synthesizer` para Fase D.
9. Invocar subagente `hu-validator` para Fase E.
10. Presentar resumen final al usuario con rutas de salida.
## Restricciones
- NO saltes el gate C4.
- NO reportes "listo" si hay fallos E5 CRÍTICOS.
- Mantén log de auditoría en `_pipeline_runs/HU-<COD>/YYYY-MM-DD.log`.
Archivo .claude/skills/crear-hu-cero/SKILL.md:
---
name: crear-hu-cero
description: Guía la creación de una HU nueva wireframe-first (Contexto 1).
---
# Skill: Crear HU desde cero (Contexto 1)
Guías al usuario (consultor/QA/arquitecto) para redactar una HU nueva usando la plantilla wireframe-first.
## Flujo
1. Preguntar: código HU, módulo, responsable, título.
2. Copiar `TEMPLATE_HU_WIREFRAME_FIRST.yaml` → `HU-<COD>/hu_spec.yaml`.
3. Rellenar metadata y descripción con las respuestas.
4. Por cada pantalla del proceso, guiar al usuario:
a. Decide el tipo de layout (list_view / form / modal / detail / wizard).
b. Describe la pantalla (campos visibles, botones, tablas, acciones).
c. Genera PNG preview con `05_render_wireframe.py`.
d. Itera hasta OK.
5. Derivar campos desde el wireframe.
6. Sugerir FN (una por botón/sección), RN (permisos, validaciones, cálculos), CA (Gherkin).
7. Pasar a Fase D + E del pipeline.
## Restricciones
- NO redactes en formato libre; siempre el YAML estructurado.
- Cada RN debe referenciar un elemento del wireframe.
- Verifica checklist de entrega del documento 01_CONTEXTO_1.
Archivo .claude/skills/validar-hu/SKILL.md:
---
name: validar-hu
description: Valida un DOCX V2 con 4 criterios automáticos + 7 dimensiones QA.
---
# Skill: Validar HU
Invocas al subagente `hu-validator` para un DOCX específico.
## Parámetros
- Ruta al DOCX
- Ruta al extracted.yaml del V1 (opcional)
## Salida
- Reporte consolidado E1-E5.
- Recomendación (PASS / REQUIERE AJUSTES / NO PROCESABLE).
Skills más granulares para invocar cada fase individualmente. Útiles para depurar una fase específica sin re-ejecutar todo el pipeline.
.claude/ a crearCuando se adquiera Claude Code corporativo, el arquitecto debe crear esta estructura en la raíz del repo de Documentation:
.claude/
├── settings.json ← configuración compartida (git)
├── settings.local.json ← overrides por desarrollador (gitignored)
├── agents/
│ ├── hu-extractor.md
│ ├── wireframe-interpreter.md
│ ├── mapping-analyst.md
│ ├── docx-synthesizer.md
│ └── hu-validator.md
└── skills/
├── reprocesar-hu/SKILL.md
├── crear-hu-cero/SKILL.md
├── validar-hu/SKILL.md
├── pipeline-fase-a/SKILL.md
├── pipeline-fase-b/SKILL.md
├── pipeline-fase-c/SKILL.md
├── pipeline-fase-d/SKILL.md
└── pipeline-fase-e/SKILL.md
Los contenidos canónicos están preparados en 08_GUIA_REPLICACION — se copian tal cual al instalar Claude Code.
En la raíz del repo Documentation/, crear CLAUDE.md con las reglas del pipeline:
# CLAUDE.md — Documentation (Nebula ERP)
## Contexto del repositorio
Este repositorio contiene:
- Wiki de arquitectura Nebula (wiki-arquitectura/)
- Scripts del pipeline V1→V2 (centrica/11_Backlog/03_Prompts/scripts/)
- Templates de HU (centrica/11_Backlog/02_Templates/)
- Historias generadas (centrica/11_Backlog/04_Historias_Cliente/)
## Reglas del pipeline
Cuando trabajes con HUs:
- **Nunca** inventes campos, RN o CA sin respaldo en V1 o wireframe.
- **Siempre** mantén trazabilidad FN→RN→CA→INT.
- **Siempre** usa Open Sans + paleta Nebula v1.4.
- **Nunca** uses tipos SQL; usa tipos funcionales.
- **Siempre** estados en inglés canónicos.
- **Siempre** fechas DD/MM/YYYY.
- **Nunca** saltes el gate C4 en Fase C.
- **Nunca** reportes "listo" si E5 tiene inconsistencias CRÍTICAS.
## Skills disponibles
- `/reprocesar-hu` — pipeline completo V1→V2.
- `/crear-hu-cero` — HU nueva wireframe-first.
- `/validar-hu` — validación de un DOCX.
- `/pipeline-fase-<a|b|c|d|e>` — fase individual.
## Herramientas locales
- `Documentation/centrica/11_Backlog/03_Prompts/scripts/.venv/bin/python3` para scripts Python.
- `Documentation/centrica/11_Backlog/03_Prompts/scripts/01_extract_hu.sh` para Fase A.
- `WPS Office` para exportar DOCX → PDF manualmente.
## Idioma de respuesta
Siempre español.
.claude/settings.json.Documentation/.claude/./reprocesar-hu HU-CON-013 y medir tiempos reales.| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.0.0 | 2026-04-20 | Carlos Torres | Configuracion Claude inicial |