¿Qué hace Coding Harness Designer v1?
"El agente no falló por falta de capacidad, sino por falta de entorno." — OpenAI "No dejes que el generador evalúe su propio trabajo." — Anthropic "Si un agente comete un error, ingenia para que nunca vuelva a cometerlo." — Mitchell Hashimoto
Relación entre este skill y harness-designer
┌─────────────────────────────────────────────────────────────┐
│ Base común: Los 5 pilares del diseño de arneses │
│ Progressive Disclosure / Mechanical Enforcement / │
│ Feedback Loop / Session Continuity / Entropy Management │
├──────────────────────────┬──────────────────────────────────┤
│ harness-designer (existente) │ coding-harness-designer (este) │
│ Espacio de trabajo de análisis/decisiones │ Espacio de trabajo de codificación/desarrollo │
│ Agente = rol de perspectiva │ Agente = trabajador de codificación │
│ Producto = informes/decisiones │ Producto = código fuente/pruebas │
│ Validación = listas de verificación/debate │ Validación = CI/linters/pruebas de navegador │
│ "Diseño de sala de reuniones" │ "Diseño de línea de producción" │
└──────────────────────────┴──────────────────────────────────┘
Los 7 pilares del arnés de codificación
A los 5 pilares existentes se añaden 2 específicos para codificación:
| Pilar | Pregunta clave | Principio |
|---|---|---|
| Progressive Disclosure | ¿Puede el agente ver solo lo que necesita? | AGENTS.md ~100 líneas índice → docs/ |
| Mechanical Enforcement | ¿Se impone la arquitectura mecánicamente? | Linters, pruebas de estructura, CI |
| Feedback Loop | ¿Se autocorrige el agente al fallar? | El mensaje de error enseña cómo corregir |
| Session Continuity | ¿Es limpia la transferencia entre sesiones? | progress + feature-status + git |
| Entropy Management | ¿Se mantiene la calidad del código con el tiempo? | Escaneo automático, refactorización, calificación de calidad |
| Architectural Rigidity ← nuevo | ¿Se imponen los límites de los módulos? | Reglas de capas, verificación de dirección de dependencias |
| Observable Runtime ← nuevo | ¿Puede el agente ver los resultados de la ejecución? | Acceso a logs, métricas, DOM, capturas de pantalla |
Relación entre las dos capas
┌─────────────────────────────────────────────────────────────┐
│ CAPA 1: Meta (Rol de este skill) │
│ │
│ Planificador ──→ Generador ──→ Evaluador │
│ ↑ (Secuencial unidireccional, sin referencias inversas) │
│ └──── Retroalimentación si es insuficiente ─────────────────────────────┘ │
│ │
│ Propósito: Diseñar, crear y validar la estructura del arnés de codificación │
└─────────────────────────┬───────────────────────────────────┘
│ Una vez aprobado, el arnés está completo
▼
┌─────────────────────────────────────────────────────────────┐
│ CAPA 2: Operativa (Rol del arnés de codificación completado) │
│ │
│ ─ Inicializador (primera ejecución) → Scaffold + configuración del entorno │
│ │ │
│ └ Agente de Codificación (ejecución repetitiva): │
│ 1. Leer progress → Seleccionar la siguiente tarea │
│ 2. Implementar (generar código) │
│ 3. Autoverificación (pruebas, linters, navegador) │
│ 4. Solicitar revisión (revisión de código entre agentes) │
│ 5. Incorporar comentarios → Repetir │
│ 6. Commit con estado limpio │
│ │
│ Propósito: Escribir, probar, refactorizar e implementar código real │
└─────────────────────────────────────────────────────────────┘
CAPA 1: Meta — Proceso de diseño del arnés de codificación
L1 Los 3 tipos de agente (Secuencial unidireccional, sin referencias inversas)
Planificador (Planificación)
Analiza los requisitos del usuario y diseña la estructura del arnés de codificación.
- Entrada: Requisitos del proyecto (recopilados mediante preguntas)
- Salida: Diseño de arquitectura + estructura de carpetas + reglas obligatorias + criterios de evaluación
Generador (Construcción)
Convierte el diseño del Planificador en archivos y configuraciones reales.
- Entrada: Diseño aprobado por el Planificador
- Salida: AGENTS.md, docs/, reglas de linter, configuración de CI, estructura de pruebas
Evaluador (Validación)
Valida de forma independiente los resultados del Generador basándose en los 7 pilares.
- Entrada: Archivos generados por el Generador + Criterios de evaluación del Planificador
- Salida: Puntuación por pilar + validación funcional + comentarios de mejora
L1 Fase 0: Coincidencia de Patrones (Pattern Match) — Referencia harness-100 (Nuevo v1.1)
"El 99% de un buen diseño ya lo hizo alguien. Encuéntralo y adáptalo."
Antes de entrar en Discovery, busca el exemplar más similar entre los validados de harness-100 (https://github.com/revfactory/harness-100, Apache-2.0) para usarlo como referencia. Si el usuario no es desarrollador, indícale que use el skill harness-starter-coding.
Exemplars objetivo (27 dominios de codificación)
- Dev&DevOps #16–30: fullstack-webapp, mobile-app-builder, api-designer, database-architect, devops-pipeline, security-audit, performance-tuning, refactoring-squad, test-automation, monitoring-setup, etc.
- Data&AI/ML #31–42: ml-experiment, data-pipeline, rag-llm-app, nlp-processor, recommendation-engine, design-system, etc.
Procedimiento de la Fase 0
- Extraer palabras clave del tipo de aplicación de la solicitud de 1 a 2 frases del usuario
- Presentar los 3 candidatos principales de los 27 anteriores + confirmación del usuario
- Registrar el número de exemplar seleccionado en el campo
reference_exemplarde_workspace/00_input.md - Similitud de coincidencia < 0,5 → Retroceder al modo de diseño libre (continuar con la Fase 1 existente)
Aplicar los resultados de la Fase 0 en los pasos posteriores
- Planificador: Tomar como base la configuración de 5 agentes del exemplar, pero ajustar según el Modo de Escala (Completo/Reducido/Individual)
- Generador: Usar primero el scaffold del esqueleto del exemplar, forzar la convención de numeración
_workspace/NN_*.md - Evaluador: Usar los 8 ítems de Estándares de Calidad del exemplar (Modo de Equipo de Agentes / Experiencia en el Dominio / Salidas Estructuradas / DAG de Dependencias / Manejo de Errores / Modos de Escala / Escenarios de Prueba / Límites de Activación) como rúbrica
Fidelidad del Patrón (Evaluación cualitativa, solo para la Fase 0)
No se incluye en la puntuación automática de los 7 pilares. Se evalúa cualitativamente al hacer coincidir el exemplar en la Fase 0.
Verificar los 8 Estándares de Calidad del exemplar de harness-100 seleccionado en la Fase 0 (Modo de Equipo de Agentes / Experiencia en el Dominio / Salidas Estructuradas / DAG de Dependencias / Manejo de Errores / Modos de Escala / Escenarios de Prueba / Límites de Activación) por separado de la puntuación del Evaluador.
- Momento de aplicación: Una vez en la Fase 0 (selección del exemplar), y una vez al informar después de que el Evaluador lo apruebe
- Sin puntuación: No se incluye en la puntuación de los 23 ítems de los 7 pilares
- pillar-weight: Solo se permite el ajuste de los pesos de los 7 pilares. La Fidelidad del Patrón no está sujeta a pesos
Límites de Activación (should + NOT)
El Planificador/Generador debe incluir una sección should-NOT trigger en el archivo orchestrator skill.md que se genere. Ejemplo: "No usar para aplicaciones móviles, microservicios empresariales, sitios web estáticos".
Principios de Comportamiento del Agente de Codificación (Inspirados en Karpathy, inyección obligatoria)
El Generador debe incluir la siguiente sección al final del .claude/CLAUDE.md que genere. Estos 4 principios se sincronizan con el skill karpathy-guidelines (instalado de forma independiente) y se convierten en las pautas de comportamiento básicas para todos los agentes de codificación dentro del arnés.
## Principios de Comportamiento del Agente de Codificación (Inspirados en Karpathy)
Todos los agentes de codificación cumplen los siguientes 4 principios al trabajar.
Consulte el skill karpathy-guidelines para más detalles (activación automática).
1. Piensa antes de codificar — Explicita suposiciones, pregunta si hay ambigüedad, sugiere alternativas
2. Primero la simplicidad — Solo lo solicitado. Prohibidas abstracciones especulativas y funcionalidades no solicitadas
3. Cambios quirúrgicos — Modifica solo las líneas solicitadas. Prohibido mejorar el código circundante
4. Ejecución impulsada por objetivos — Criterios de éxito verificables → Bucle → Confirmación
Añadir el ítem "Existencia de la sección de los 4 principios de Karpathy en CLAUDE.md" a la lista de verificación del Evaluador.
Modos de Escala (Valores por defecto de la capa operativa)
| Modo | Composición de agentes |
|---|---|
| Completo | architect + frontend + backend + qa + devops |
| Backend | architect + backend + qa |
| Frontend | architect + frontend + qa |
| Refactorización | architect + desarrollador relevante + qa |
| DevOps | devops solo |
L1 Fase 1: Descubrimiento (Discovery) — Funcionamiento del Planificador
Discovery consta de 4 etapas de preguntas. Se procede en orden por cada etapa, pero las preguntas de seguimiento se ramifican según las respuestas del usuario. Se pasa a la siguiente etapa solo después de recibir la respuesta de la etapa actual. No se preguntan todas a la vez.
1-1. Etapa 1 — Propósito y Contexto (POR QUÉ / QUIÉN)
Comprender la razón de ser del proyecto, no la tecnología.
P1. ¿Cuál es el problema que este proyecto intenta resolver?
(¿Qué incomodidad/ineficiencia se quiere eliminar?)
P2. ¿Quién lo usa?
(Empleados internos / Clientes / Desarrolladores / Público en general)
→ Seguimiento: ¿Cuántos usuarios? ¿Cuál es su nivel de competencia técnica?
P3. ¿Cuál es el criterio de éxito de este proyecto?
(¿Qué debe ocurrir para que se considere "bien hecho"?)
P4. ¿Existe algún sistema similar existente?
(¿Se reemplaza uno? / ¿Se crea uno nuevo?)
→ Seguimiento [Reemplazo]: ¿Cuál es el mayor problema del sistema existente?
→ Seguimiento [Nuevo]: ¿Hay algún servicio de referencia?
Ramificación de preguntas de seguimiento:
- Si en P2 responde "Empleados internos" → "¿Cuántos? ¿Existe una estructura de departamentos? ¿Se necesita un sistema de permisos?"
- Si en P2 responde "Clientes" → "¿Cuál es el método de registro? ¿Hay pagos? ¿Se manejan datos personales?"
- Si en P3 se mencionan cifras concretas → "¿Cómo se mide esa cifra?"
- Si en P3 la respuesta es vaga → "¿Qué pantalla/función específica, al funcionar, indicaría éxito?"
1-2. Etapa 2 — Funcionalidad y Contenido (QUÉ)
¿Qué contiene? ¿Cuáles son las funciones principales?
F1. Enumera las 3 funciones principales por orden de prioridad.
(Desde la que debe funcionar primero)
F2. ¿Cuál es la naturaleza de los datos?
(Relacional / Documentos / Series temporales / Archivos / Mixto)
→ Seguimiento: ¿Son complejas las relaciones entre los datos? ¿Son importantes las agregaciones/estadísticas?
F3. ¿Existen requisitos de autenticación/autorización?
(Ninguno / Inicio de sesión simple / Basado en roles / Permisos jerárquicos de organización)
→ Seguimiento [Basado en roles o superior]: ¿Cuántos niveles de permisos? ¿Se necesita aislamiento de datos?
F4. ¿Hay integración con sistemas externos?
(Ninguna / Integración por API / import/export de archivos / Pagos / Notificaciones)
F5. ¿Se necesita soporte offline o para móviles?
Ramificación de preguntas de seguimiento:
- Si en F1 se mencionan más de 3 funciones → "Si evaluaras la complejidad de cada función como Alta/Media/Baja, ¿cómo sería?"
- Si en F2 responde "Mixto" → "¿Qué tipos se mezclan? ¿Es necesario separar los repositorios?"
- Si en F3 responde "Jerarquía de organización" → "¿Se añaden/cambian departamentos con frecuencia? ¿Necesita ser escalable sin cambios de código?"
1-3. Etapa 3 — Tecnología y Estructura (CÓMO)
¿Cómo se va a construir? Reflejando las respuestas de las Etapas 1 y 2, se proponen las tecnologías adecuadas.
T1. ¿Tienes preferencia por la pila tecnológica?
(Si la tienes, especifícala / Si no, "Recomiéndame")
→ Recomendar "Tecnología Aburrida": Los agentes trabajan mejor con tecnologías estables y con abundantes datos de entrenamiento (principio de OpenAI)
→ Proponer una pila adecuada basada en las respuestas de las Etapas 1 y 2
T2. ¿Cuál es el entorno de despliegue?
(Vercel / AWS / Servidor interno / No lo sé)
T3. ¿Qué herramientas de agente de codificación?
(Claude Code / Codex / Cursor / Otras)
→ La configuración del arnés varía según la herramienta
T4. ¿Cuál es el nivel de autonomía del agente?
(Un humano revisa y hace merge / Revisión entre agentes y merge automático / Completamente autónomo)
T5. ¿Cuál es el alcance y la duración del proyecto?
(Prototipo de 1 a 2 semanas / Mediano de 1 a 3 meses / Grande a largo plazo)
T6. ¿Existe una base de código existente?
(Nuevo / Aplicar el arnés a código existente)
→ Si es código existente, diseñar una estrategia de aplicación gradual
Ramificación de preguntas de seguimiento:
- Si en T1 responde "Recomiéndame" → Basándose en las respuestas de las Etapas 1 y 2, presentar una tabla comparativa de 2 a 3 opciones y pedir que elija
- Si en T2 responde "No lo sé" → Recomendar basándose en el tamaño del usuario y las funcionalidades
- Si en T5 responde "Grande" → "¿Cuál es el tamaño del equipo? ¿Cuántos agentes trabajarán simultáneamente?"
1-3.5. Etapa 3.5 — Seguimiento del Historial de Cambios de Flujo (HISTORIAL DE FLUJO) [Opcional]
Se recomienda cuando exista la posibilidad de que el arnés de codificación evolucione a lo largo de proyectos a largo plazo o múltiples sesiones. Se puede omitir en prototipos de 1 a 2 semanas.
F1. "Cuando en el futuro se cambien prompts, protocolos, plantillas, scripts de API, comandos o CLAUDE.md, ¿te gustaría guardar un historial?"
Uso:
- Revisión del historial de mejora del proyecto (por qué cambió)
- Asegurar la base para la reversión a una versión anterior cuando sea necesario
- Referencia para el diseño de futuros arneses de codificación similares
※ No está diseñado para ser leído en cada nueva sesión.
Solo se consulta al modificar, revertir o trasplantar el flujo.
→ "No" → No incluir 05-flow-history/. Ir a la Etapa 4.
→ "Sí" → Ir a F2.
F2. "¿Quieres registrar automáticamente la compilación inicial (v1) como un registro de cambio 0001?"
- Valor por defecto: Sí (Las respuestas del Planificador Discovery se conservan como base de diseño)
- No → Solo se genera el CHANGELOG y se registra manualmente en el primer cambio
Principios de gestión del historial de flujo (basados en la operación posterior a la creación):
Este historial registra solo los cambios en el sistema de flujo de trabajo (prompts, protocolos, plantillas, scripts de API, comandos, CLAUDE.md).
Los resultados generados por el sistema (código, informes, resultados de análisis) no son objeto de registro.
Criterio de distinción: "Si este cambio no hubiera ocurrido, ¿sería diferente el resultado de la próxima ejecución?"
→ Si es diferente = cambio de sistema = registrar / Si no es diferente = resultado = no es necesario registrar
Detalles: 00-system/protocols/flow-change-protocol.md
Añadir a la salida del Planificador (relacionado con el historial de flujo):
flow_history_enabled: true/falseflow_history_initial_record: true/false(respuesta de F2)
1-4. Etapa 4 — Criterios de Calidad y Evaluación (CALIDAD / EVALUAR)
Comprender los valores que el usuario considera importantes y acordar los criterios de evaluación.
E1. ¿Cuáles son los atributos de calidad más importantes de este proyecto? (Seleccionar los 3 principales)
□ Seguridad (permisos, aislamiento de datos, autenticación)
□ Rendimiento (velocidad de respuesta, conexiones concurrentes)
□ Escalabilidad (escalar sin cambios de código)
□ Mantenibilidad (fácil de modificar por otras personas/agentes)
□ Experiencia de usuario (UI intuitiva, respuesta rápida)
□ Capacidad de prueba (garantía de calidad mediante pruebas automáticas)
□ Lanzamiento rápido (MVP primero, calidad después)
□ Consistencia de datos (registros precisos, sin pérdidas)
E2. ¿Hay planes de expansión futura?
(Ninguno / Añadir funciones / Combinar con otros sistemas / Escalar el número de usuarios)
→ Seguimiento: ¿Qué tipo de expansión específicamente? ¿Cuándo?
E3. ¿Qué es lo que nunca se debe comprometer en este proyecto?
(Ej: "El aislamiento de permisos no debe romperse", "Los datos no deben perderse")
E4. Por el contrario, ¿qué puede faltar en las fases iniciales?
(Ej: "La versión para móviles puede venir después", "El panel de estadísticas es para la segunda fase")
Ramificación de preguntas de seguimiento:
- Si en E1 se selecciona "Seguridad" → "¿Qué tipo de seguridad? ¿Autenticación/permisos/cifrado de datos/registros de auditoría?"
- Si en E2 responde "Combinar con otros sistemas" → "¿Qué sistemas? ¿Son compatibles los formatos de datos?"
- La respuesta de E3 → Se utiliza como entrada clave para los pesos del Evaluador
1-5. Acuerdo de Pesos de Evaluación (Después de completar la Etapa 4)
Analizar las respuestas de las Etapas 1 a 4 para proponer los pesos de los 7 pilares. Acordar con el usuario para finalizarlos.
[PROCESO DE PROPUESTA DE PESOS]
PASO 1. Extraer palabras clave de las respuestas de las Etapas 1 a 4
- "Aislamiento de permisos" → Mechanical Enforcement, Architectural Rigidity ↑
- "Escalar sin cambios de código" → Architectural Rigidity ↑
- "Lanzamiento rápido" → Entropy Management ↓, Observable Runtime ↑
- "Consistencia de datos" → Feedback Loop ↑, Mechanical Enforcement ↑
PASO 2. Ajustar desde los pesos base y proponer
Pesos base (antes de reflejar las características del proyecto):
| Pilar | Base | Fundamento del ajuste | Propuesta |
|------|------|----------|------|
| Progressive Disclosure | 15% | (fundamento de la variación) | ?% |
| Mechanical Enforcement | 20% | (fundamento de la variación) | ?% |
| Feedback Loop | 15% | (fundamento de la variación) | ?% |
| Session Continuity | 10% | (fundamento de la variación) | ?% |
| Entropy Management | 10% | (fundamento de la variación) | ?% |
| Architectural Rigidity | 20% | (fundamento de la variación) | ?% |
| Observable Runtime | 10% | (fundamento de la variación) | ?% |
"Considerando [fundamento] para este proyecto,
hemos ajustado el peso de [pilar] de [base]% a [propuesta]%.
Por favor, indíquenos su opinión o si necesita alguna modificación."
PASO 3. Reflejar los comentarios del usuario
- De acuerdo → Finalizado
- "Aumenta más la seguridad" → Aumentar el peso del pilar relacionado, reducir otros y volver a proponer
- "Este pilar no es necesario" → Establecerlo al 0%, redistribuir el resto y volver a proponer
PASO 4. Aprobación final
"Confirmamos los pesos finales. El Evaluador puntuará con estos pesos."
→ Usar estos pesos acordados en lugar de los pesos base de evaluator-protocol.md
1-6. Mapeo Automático de Patrones de Arquitectura
→ Consultar references/architecture-patterns.md
→ Proponer el patrón más adecuado basándose en las respuestas de las Etapas 2 y 3
| Tipo de aplicación | Estructura de capas recomendada |
|---|---|
| Aplicación web Full Stack | Types→Config→Repo→Service→Runtime→UI |
| Servicio API | Types→Config→Repo→Service→Runtime |
| Herramienta CLI | Types→Config→Core→CLI |
| Librería | Types→Core→Public API |
1-7. Resultados del Planificador
① Resumen del contexto del proyecto — Propósito, usuarios, criterios de éxito, restricciones clave (basado en Etapas 1 y 2)
② Diseño de la arquitectura — Estructura de capas, límites de módulos, dirección de dependencias
③ Borrador de la estructura de carpetas — Basado en references/coding-folder-patterns.md
④ Diseño de reglas obligatorias — Qué reglas se imponen mediante linters/CI/pruebas de estructura
⑤ Estrategia de pruebas — Alcance de unitarias/integración/E2E y criterios de cobertura
⑥ Diseño de autonomía del agente — Bucles de revisión, puertas de aprobación, criterios de escalamiento
⑦ Estrategia de expansión — Decisiones de diseño para prepararse para la expansión futura (basado en Etapa 4 E2)
⑧ Criterios de evaluación + Pesos acordados — Lista de verificación de 7 pilares + tabla de pesos
[Planificador completado — Solicitar aprobación del usuario]
Revise los puntos ① a ⑧ y comente si necesita alguna modificación.
Una vez aprobado, el Generador comenzará la construcción.
L1 Fase 2: Construcción (Build) — Funcionamiento del Generador
2-1. Generación de resultados clave (en orden)
| Orden | Resultado | Descripción |
|---|---|---|
| 2-1a | Diagrama de arquitectura | Mermaid — Capas, módulos, dirección de dependencias |
| 2-1b | AGENTS.md (~100 líneas) | Función de índice, incluye enrutamiento de referencias |
| 2-1c | Directorio docs/ | Detalles a continuación |
| 2-1d | Reglas de enforce de arquitectura | Reglas de linter + pruebas de estructura |
| 2-1e | Diseño de pipeline CI/CD | Definición de puertas de validación |
| 2-1f | Estructura de pruebas | Directorio de pruebas + configuración básica |
| 2-1g | Resultados de transferencia de sesión | progress.json + feature-status.json |
| 2-1h | Configuración del bucle de revisión de código | Protocolo de revisión entre agentes |
| 2-1i | Configuración de observabilidad | Métodos de acceso a logs, métricas, DOM |
| 2-1j | README.md | Guía para desarrolladores |
| 2-1k | Inicialización del proyecto bkit | Solo si en T3 se detecta Claude Code + bkit instalados, y solo después de preguntar al usuario si opta por ello (detalles a continuación) |
| 2-1l | Configuración del entorno | Entorno virtual, variables de entorno, hooks — No se genera forzosamente. El LLM propone en la Fase 3-7 y el usuario elige |
| 2-1m | Wiki de historial de cambios de flujo (opcional) | Solo si F1 de la Etapa 3.5 = Sí. Consultar ~/.claude/skills/harness-designer-workspace/references/flow-history-template.md para crear 05-flow-history/ + 00-system/protocols/flow-change-protocol.md. Añadir 2 líneas de enrutamiento en AGENTS.md + sección "Seguimiento de cambios de flujo (registro selectivo)". Principio de gestión: Solo registrar cambios en el sistema (reglas, procedimientos, herramientas). Los resultados (código, informes) no necesitan registro. Criterio de distinción: "¿Si este cambio no hubiera ocurrido, sería diferente el resultado de la próxima ejecución?" |
2-1b. Reglas de redacción de AGENTS.md (Críticas)
→ Consultar references/agents-md-template.md
Aplicar las lecciones clave del borrador original de OpenAI:
Índice de ~100 líneas. No es una enciclopedia.
# [Nombre del proyecto]
> [Descripción de una línea]
## Resumen de la arquitectura
[Resumen de la estructura de capas en 3 líneas]
→ Detalles: docs/architecture.md
## Enrutamiento de referencias
| Situación | Archivo a leer |
|------|----------|
| Reglas de arquitectura | → docs/architecture.md |
| Convenciones de codificación | → docs/conventions.md |
| Diseño del dominio | → docs/design/[domain].md |
| Plan de ejecución | → docs/exec-plans/[plan].md |
| Calidad por niveles | → docs/quality-grades.md |
| Deuda técnica | → docs/exec-plans/tech-debt-tracker.md |
| Estado de la sesión | → progress.json |
| Estado de las funciones | → feature-status.json |
## Reglas principales (máximo 5)
1. [Regla inmutable 1 — Ej: "Validar la forma de los datos en todos los límites"]
2. [Regla inmutable 2 — Ej: "Prohibir dependencias inversas entre capas"]
3. [Regla inmutable 3]
## Reglas de prueba
→ docs/testing-strategy.md
## Comandos
| Comando | Función |
|--------|------|
| /implement [función] | Implementar función |
| /review | Ejecutar revisión de código |
| /test | Ejecutar pruebas |
| /refactor [objetivo] | Refactorizar |
## Última actualización: AAAA-MM-DD
2-1c. Directorio docs/ (System of Record)
→ Consultar references/docs-structure.md
docs/
├── architecture.md ← Estructura de capas, límites de módulos, ...
├── conventions.md ← Convenciones de nomenclatura, estilo de código
├── testing-strategy.md ← Estrategia de pruebas, cobertura, mocks
├── quality-grades.md ← Criterios de calidad automáticos
├── design/ ← Documentos de diseño por dominio
│ └── [domain].md
├── exec-plans/ ← Planes de ejecución activos
│ ├── current.md
│ ├── tech-debt-tracker.md
│ └── archive/ ← Planes completados
├── api/ ← Documentación de API
│ └── [endpoint].md
└── runbooks/ ← Procedimientos operativos
└── [scenario].md
Principio de gestión de docs/:
"Si tienes que decidir entre un archivo grande y un archivo pequeño, hazlo grande. Si tienes que decidir entre un bloque de código y una explicación en lenguaje natural, escribe la explicación. La referencia a la que el agente vuelve más a menudo debe ser la más fácil de encontrar."
L1 Fase 3: Verificación (Evaluation) — Funcionamiento del Evaluador
3-1. Entrada del Evaluador
| Elemento | Fuente |
|---|---|
| Resultados del Generador | Archivos AGENTS.md, docs/, CI, etc. |
| 7 pilares: lista de verificación de 23 ítems | references/evaluator-checklist-7pillars.md |
| Pesos base + ajustes acordados | Fase 1, resultado del acuerdo de la Etapa 5 (si no hay acuerdo, usar los valores por defecto) |
3-2. Proceso de ejecución del Evaluador
PASO 1. Verificación de la integridad de los resultados Verificar si existen todos los archivos de la lista de la Fase 2 (2-1a a 2-1l). Si falta alguno → DEVOLVER al Generador con el motivo.
PASO 2. Puntuación por pilar (0 a 100 puntos)
Lista de verificación de 23 ítems por pilar:
Progressive Disclosure (Peso base: 15% → Acordado: ?%)
□ 1. AGENTS.md ≤ 150 líneas (no 300) ✓/✗
□ 2. El contenido de AGENTS.md es una tabla de contenido y rutas, no un manual de usuario ✓/✗
□ 3. La información detallada se distribuye en docs/ ✓/✗
□ 4. El diseño garantiza que el agente puede iniciar la codificación con solo leer AGENTS.md ✓/✗
Mechanical Enforcement (Peso base: 20% → Acordado: ?%)
□ 5. Reglas de linter definidas para la pila correspondiente ✓/✗
□ 6. Existen pruebas de estructura (pruebas que verifican la estructura de carpetas/archivos) ✓/✗
□ 7. CI pipeline configurado para ejecutar las reglas anteriores ✓/✗
□ 8. Si la comprobación falla, el pipeline falla (no solo una advertencia) ✓/✗
Feedback Loop (Peso base: 15% → Acordado: ?%)
□ 9. Cuando ocurre un error, el mensaje guía al agente para solucionarlo ✓/✗
□ 10. Existe un protocolo de revisión de código entre agentes (2-1h) ✓/✗
□ 11. Cuando el agente se queda atascado, existe un camino de escalamiento claro ✓/✗
□ 12. Existe un mecanismo para que el agente mismo registre su tasa de éxito/fracaso ✓/✗
Session Continuity (Peso base: 10% → Acordado: ?%)
□ 13. Cada sesión comienza con la lectura de progress.json ✓/✗
□ 14. feature-status.json registra el estado de cada función (no implementada/en progreso/completada) ✓/✗
□ 15. La convención de commits de git está definida (tipo de commit + mensaje descriptivo) ✓/✗
□ 16. El diseño de la sesión considera el cambio de contexto (se puede saber dónde se dejó en 5 minutos) ✓/✗
Entropy Management (Peso base: 10% → Acordado: ?%)
□ 17. Existe una herramienta de escaneo automático de calidad (linter + análisis estático) ✓/✗
□ 18. quality-grades.md define niveles de calidad (A/B/C/D) y criterios de degradación ✓/✗
□ 19. Existe tech-debt-tracker.md y se actualiza periódicamente ✓/✗
□ 20. Existe un plan de refactorización para el momento en que la calidad baja al nivel C ✓/✗
Architectural Rigidity (Peso base: 20% → Acordado: ?%)
□ 21. Las reglas de dirección de dependencias entre capas están claramente definidas ✓/✗
□ 22. Existe una prueba o script que verifica automáticamente la violación de las reglas de la capa ✓/✗
Observable Runtime (Peso base: 10% → Acordado: ?%)
□ 23. El agente puede acceder a logs en tiempo real o registros de ejecución (archivo o stdout) ✓/✗
Regla de puntuación (Capa 1, Evaluador):
- Puntuación por pilar = (ítems cumplidos / ítems del pilar) × 100
- Puntuación total = suma de (puntuación de cada pilar × peso)
Criterio de aprobación: ≥ 75 puntos → APROBADO (PASS) < 75 puntos → DEVOLVER al Generador con puntuación + motivos + sugerencias de mejora
PASO 3. Evaluación adicional (no incluida en la puntuación)
① Evaluación del Patrón de Fase 0 (Evaluación cualitativa, se repite cuando se informa de PASS)
- ¿La referencia del exemplar es adecuada para el proyecto actual?
- ¿La configuración de agentes del exemplar se ha traducido correctamente?
- (Solo informar, no puntuar)
② Existencia de Karpathy 4 principios en CLAUDE.md
- ¿Existe la sección? ✓/✗ (Si no existe → sugerir corrección)
PASO 4. Redactar el informe final del Evaluador
## Informe de Evaluación del Arnés de Codificación
### Puntuación por pilar
| Pilar | Peso | Puntuación | Puntuación ponderada |
|------|------|----------|------|
| Progressive Disclosure | ?% | ?/100 | ? |
| Mechanical Enforcement | ?% | ?/100 | ? |
| Feedback Loop | ?% | ?/100 | ? |
| Session Continuity | ?% | ?/100 | ? |
| Entropy Management | ?% | ?/100 | ? |
| Architectural Rigidity | ?% | ?/100 | ? |
| Observable Runtime | ?% | ?/100 | ? |
| **Total** | **100%** | | **?/100** |
### Resultado
□ **APROBADO** (≥ 75) — El arnés de codificación está completo. Pasar a la Fase 4.
□ **DEVUELTO** (< 75) — Es necesario mejorar los siguientes elementos:
- [Elemento de mejora 1]
- [Elemento de mejora 2]
### Evaluación cualitativa adicional
- Fidelidad del Patrón Fase 0: [Adecuado / Necesita ajuste] (Fuera de puntuación)
- Existencia de Karpathy 4 principios: [✓/✗]
L1 Fase 4: Finalización (Wrap-up)
Confirmar el resultado de la Fase 3 al usuario. Cuando el Evaluador aprueba, el arnés de codificación está completo y listo para la Capa 2 (Operativa).
Caso 1: APROBADO
## Arnés de codificación completado ✓
El arnés ha pasado la verificación de los 7 pilares.
Ahora puede empezar el desarrollo en la Capa 2.
Resumen del arnés:
| Elemento | Valor |
|----------|-------|
| Arquitectura | [Tipo de arquitectura] |
| Número de agentes | [Número] |
| Autonomía | [Nivel de autonomía] |
| CI/CD | [Tipo de pipeline] |
| Observabilidad | [Método] |
### Recomendaciones para el inicio de la Capa 2
1. Ejecutar primero el Initializer (scaffold + configuración del entorno)
2. El agente de codificación lee progress.json → comienza la primera tarea
3. Seguir el protocolo de revisión de código entre agentes
4. Si surge algún problema, revisar el diseño del arnés (volver a la Capa 1)
Caso 2: DEVUELTO (cuando el usuario solicita una nueva ronda)
## El arnés necesita mejoras
[Puntuación] puntos. Las siguientes áreas necesitan mejora:
- [Área 1]: [Problema específico]
- [Área 2]: [Problema específico]
El Generador se reinicia para reflejar las sugerencias del Evaluador.
Se mantienen las decisiones de la Fase 1 (Discovery).
CAPA 2: Operativa — Funcionamiento del agente de codificación dentro del arnés
Una vez completado el arnés de codificación, el flujo de trabajo real se divide en dos modos. La primera ejecución la realiza el Initializer, y las ejecuciones posteriores el Agente de Codificación.
Modo 1: Initializer (Ejecución única)
Cuándo ejecutar: Primera ejecución del proyecto, o cuando se inicia una nueva base de código o un gran refactor. Quién ejecuta: El desarrollador humano o el agente principal (architect) bajo instrucción explícita.
Proceso
flowchart TD
A[Inicio] --> B[Crear estructura de carpetas según docs/]
B --> C[Configurar linters según .eslintrc / .prettierrc]
C --> D[Instalar dependencias del proyecto]
D --> E[Configurar CI (Github Actions / etc.)]
E --> F[Inicializar progress.json + feature-status.json]
F --> G[Ejecutar pruebas básicas para verificar el estado del arnés]
G --> H[Registrar en git: commit inicial del arnés]
H --> I[Fin]
Resultados clave de la inicialización
- Acuerdo sobre la estructura de carpetas con el sistema de archivos real
- Linters ejecutándose (verificables con
npm run linto equivalente) - Las pruebas básicas de CI se ejecutan en local
- progress.json registra el punto de partida
Modo 2: Agente de Codificación (Ejecución repetitiva)
Cuándo ejecutar: Después de que el Initializer haya completado la configuración base. Quién ejecuta: Claude Code / Codex / Cursor u otros agentes de codificación.
Bucle principal
1. [Inicio de sesión] Leer progress.json + feature-status.json → estado actual
Si es la primera sesión: progress = "setup completado", feature-status = "ninguna completada"
2. [Selección de tarea] Elegir la siguiente tarea de la lista de tareas
Criterio: La más simple primero, o la que tiene más dependencias
Si hay múltiples agentes: Reparto según el rol (architect/frontend/backend/qa)
3. [Implementación] Generar código según el plan de ejecución
- Seguir las reglas de capas de la arquitectura
- Escribir pruebas junto con el código (TDD o pruebas después)
- Seguir las convenciones de nomenclatura
4. [Autoverificación] Ejecutar pruebas + linter + compilación
- Si falla: Usar el mensaje de error para corregir
- Éxito: Continuar
5. [Revisión] Solicitar revisión a otro agente (o al humano)
- El revisor verifica: ¿Cumple con la arquitectura? ¿Las pruebas son suficientes?
- Si hay comentarios: Reflejar y volver al paso 4
- Aprobado: Continuar
6. [Confirmación] Commit con estado limpio
- Tipo de commit: [feat/fix/refactor/docs/test] + descripción
- Actualizar progress.json (completado: [tarea])
- Actualizar feature-status.json (función: [estado])
7. [Siguiente iteración] Volver al paso 2
Si no hay más tareas: Notificar al usuario "Todas las funciones completadas"
Si surge un obstáculo: Registrar el obstáculo en progress.json y escalar
Gestión de errores (durante la ejecución repetitiva)
| Tipo de error | Acción |
|---|---|
| Error de compilación/sintaxis | El agente autocorrige basándose en el mensaje de error (Sin escalar) |
| Prueba fallida | El agente analiza la causa y corrige (Sin escalar) |
| Violación de la regla de capas | Registrar en progress.json como deuda técnica + Notificar al revisor (Escalar al revisor) |
| El agente se queda atascado (más de 3 reintentos) | Solicitar ayuda al agente architect (Escalar al architect) |
| Problema de diseño que requiere decisión humana | Pausar y preguntar al humano (Humano necesario) |
Transferencia de sesión (handoff)
Cuando se necesita cambiar de agente a mitad de una función o entre sesiones:
Estado de la función:
- ¿Qué función se está implementando?
- ¿Qué archivos se han modificado?
- ¿Qué pruebas están pasando/fallando?
- ¿Hay algún obstáculo conocido?
- ¿Cuál debería ser el siguiente paso?
Registro de transferencia:
En progress.json → [Handoff]: {de: agente_A, a: agente_B, función: X, estado: "implementación completada, revisión pendiente"}
Gestión del workspace del skill (Meta-capa)
A diferencia del workspace del proyecto (Capa 2), la meta-capa (Capa 1) tiene su propio espacio de trabajo para gestionar las decisiones de diseño.
Estructura de "/workspace/" (Meta-capa)
_workspace/
├── 00_input.md ← Registro de la solicitud inicial del usuario (se sobrescribe en cada sesión)
│ └── reference_exemplar ← Estado de la Fase 0 (número del exemplar, o "free_design")
├── 01_discovery.md ← Registro de respuestas de las Etapas 1 a 4 + pesos acordados
├── 02_architecture.md ← Salida del Planificador (diseño y reglas)
├── 03_generator_output.md ← Salida del Generador (lista de archivos generados + cambios)
├── 04_evaluation.md ← Informe del Evaluador (puntuaciones y resultado)
├── 05_flow-history/ ← Solo cuando la Etapa 3.5 F1 = Sí
│ ├── 0001_initial-build.md ← Registro de la compilación inicial
│ ├── 0002_...
│ └── template.md ← Plantilla de registro
├── 00-system/ ← Sistema/Definiciones/Protocolos
│ ├── definitions/ ← (Enlace simbólico referenciado externamente)
│ │ └── skill-definition.md
│ ├── protocols/
│ │ ├── planner-protocol.md
│ │ ├── generator-protocol.md
│ │ ├── evaluator-protocol.md
│ │ └── flow-change-protocol.md
│ └── flows/
│ ├── main-flow.md
│ └── flow-history.md
├── references/
│ ├── agents-md-template.md
│ ├── architecture-patterns.md
│ ├── coding-folder-patterns.md
│ ├── docs-structure.md
│ └── evaluator-checklist-7pillars.md
└── _archive/ ← Archivo de sesiones anteriores
└── YYYY-MM-DD_session-notes.md
Apéndice: Resumen de preguntas para Fase 1 Discovery
| Etapa | Preguntas principales |
|---|---|
| 1. Propósito | P1. Problema / P2. Usuario / P3. Criterio de éxito / P4. Sistema existente |
| 2. Funciones | F1. 3 funciones principales / F2. Tipo de datos / F3. Autenticación / F4. Integración externa / F5. Offline/Móvil |
| 3. Tecnología | T1. Pila tecnológica / T2. Entorno de despliegue / T3. Herramienta de agente / T4. Autonomía / T5. Escala / T6. Código existente |
| 3.5. Historial de flujo | F1. Habilitar historial / F2. Registro inicial |
| 4. Calidad | E1. Atributos de calidad (top 3) / E2. Plan de expansión / E3. Límite no negociable / E4. Lo que puede faltar al inicio |
| 5. Pesos | Acordar pesos de 7 pilares basados en las respuestas anteriores |
Apéndice: Información de contacto y licencia
- Repositorio:
https://github.com/kkh2114/claude-skills-public - Licencia: Apache-2.0
- Skill relacionado: harness-designer (para análisis/decisiones, no para codificación)