HCP: Vertientes Avanzadas del Protocolo

HCP no es solo un sistema de archivos markdown. Es un protocolo completo de colaboración humano-IA con 7 vertientes avanzadas.

Resumen Ejecutivo

HCP maneja capacidades avanzadas que van mucho más allá de archivos básicos:

1. Flujos Externos (External Collaboration)

¿Qué es?

Sistema para capturar y estructurar interacciones con agentes/humanos externos al proyecto, manteniendo trazabilidad completa desde request hasta implementación.

Problema que Resuelve

En proyectos colaborativos, las interacciones con externos (clientes, stakeholders, contractors) suelen perderse en emails, Slack, o contexto oral. HCP estructura estos flujos.

Context Handoff Skill

8 Técnicas de Prompt Engineering:

1. Context Anchoring: Referenciar archivos (no copiar contenido)

   ❌ MAL: Copiar 5,000 tokens de contexto
   ✅ BIEN: Lee @project/.procontext/session.md
   

2. Reference-Based Context: Jerarquía de documentos (lazy loading)

3. State Transfer Minimal: Solo estado esencial (done vs pending)

   ✅ Lo que YA está hecho: [lista]
   🎯 Lo que FALTA: [tu tarea específica]
   

4. Constraint Re-injection: Re-inyectar P0 constraints críticos

5. Verification Metrics: Métricas para auto-validación

6. Task Continuation Pattern: Inputs/outputs claros

7. Tools Prescription: Sugerir herramientas óptimas

8. Quick Start Command: Comando copy-paste

Métricas Validadas

• Reducción tokens: 5,000 → 500 tokens (90%)
• Tiempo arranque: 30 min → 5 min (83%)
• Mensajes clarificación: 5-10 → 0-1 (90%)

2. Sistema de Roles y Prompt Engineering

Los 9 Roles Estándar

HCP usa personalidades basadas en ingenieros legendarios como sistema de prompt engineering avanzado:

Diferencia: Rol vs Capability vs Skill

Rol (quién eres):
  ejemplo: "Backend Developer Agent"
  persistente: true
  
Capability (qué sabes):
  ejemplo: "Python expert, FastAPI advanced"
  técnica: true
  
Skill (cómo lo haces):
  ejemplo: "orchestrate-subagents"
  proceso: documentado
  reutilizable: true

Relación:

Rol ──> tiene ──> Capabilities
                      └─> usa ──> Skills

Pattern 8: Multi-Role Activation

Combinar 2 roles complementarios para decisiones complejas:

Role: 'John_Carmack + Barbara_Liskov'
Vibe: 🎯 PRECISO

Diseña state manager reactivo:
- Latency P95 < 10µs (Carmack)
- Thread-safe, no races (Liskov)
- Zero unsafe blocks (Liskov)

Combos Validados:

Pattern 14: Emotional States (Vibes)

Los 4 Vibes:

3. Memoria y Contexto Persistente

Arquitectura de 5 Niveles

sessions/
│
├── YYYY-resumen-anual.md              # Nivel 1: Anual
│   - Historia completa del año
│   - Top 10 lecciones
│
├── YYYY-QN-trimestre-N.md             # Nivel 2: Trimestral
│   - Evolución trimestre
│   - Pivotes estratégicos
│
├── YYYY-MM-mes.md                     # Nivel 3: Mensual
│   - Hitos del mes
│   - Decisiones estratégicas
│
├── YYYY-WWW-semana-WWW.md             # Nivel 4: Semanal
│   - Logros semana
│   - Cambios técnicos clave
│
└── daily/                              # Nivel 5: Diario
    └── YYYY-MM-DD.md
        - Detalles técnicos completos
        - Decisiones y ambigüedades

Flujo de Contenido (Ambigüedad → Decisión → Lección)

DÍA 1: Identifica ambigüedad
  "¿Usar REST o GraphQL?"
  ↓
SEMANA 3: Consolida
  "Decidir REST vs GraphQL esta semana"
  ↓
MES 1: Documenta decisión
  "Decisión: REST (simplicidad > features GraphQL)"
  ↓
TRIMESTRE Q1: Analiza impacto
  "REST fue correcta, 0 arrepentimientos"
  ↓
AÑO: Extrae lección
  "Lección: Simplicidad > Hype en APIs"

Archivos de Memoria

learnings.md

### ✅ pgvector es suficiente para <100K documentos

**Learning**: No necesitas Qdrant/Weaviate si dataset es <100K docs

**Context**:
- Investigamos Qdrant, Weaviate, Milvus
- Testeamos pgvector con HNSW index
- Benchmark: ~50ms por query (10K docs)

**Conclusion**:
- pgvector + PostgreSQL es más simple operacionalmente
- HNSW index (m=16, ef_construction=64) funciona bien

**When to revisit**: Si escalamos >100K docs

decisions.md

## 2026-03-27: Text-Only Storage Strategy

**Decision**: Guardar solo TEXTO extraído en PostgreSQL, no archivos binarios

**Rationale**:
- Ahorro de espacio: 95% menos para PDFs
- Backups más rápidos
- Sin dependencias de filesystem
- Mejor para escalado horizontal

**Validation**:
- Test con hcp-viability-test.md (2.5KB)
- Status: ✅ VALIDADO 2026-03-27

ADRs (Architecture Decision Records)

Documentación formal con estructura Michael Nygard:

• Status, Context, Decision, Consequences
• Inmutable (supersede con nuevo ADR)
• Para arquitectos, tech leads, auditoría

Estrategia de Recovery de Contexto

# Nivel 1: Contexto Esencial (<5 min)
1. .procontext/context.md
2. .procontext/session.md
3. .procontext/memory/decisions.md (últimas 3)

# Nivel 2: Contexto Completo (<15 min)
4. sessions/YYYY-MM-mes.md
5. sessions/YYYY-WWW-semana-WWW.md
6. ADRs relevantes

# Nivel 3: Deep Dive (si necesario)
7. sessions/daily/últimos-3-días.md
8. memory/learnings.md

4. Orquestación Multi-Agente

Sistema de Coordinación Paralela

HCP no solo maneja un agente, sino orquestación de múltiples agentes especializados trabajando en paralelo.

Skill: orchestrate-subagents

Cuándo usar:

• Análisis completo/exhaustivo de proyecto grande
• Auditorías multi-dimensionales (seguridad, performance, UX, arquitectura)
• Acelerar tareas independientes ejecutándolas en paralelo
• Análisis desde múltiples perspectivas

Cuándo NO usar:

• Tareas simples (<5 minutos)
• Sub-tareas con dependencias secuenciales estrictas
• Proyectos muy pequeños (<10 archivos)

Proceso Completo

### Fase 1: Evaluación y Planificación
- ¿Qué aspectos independientes existen?
- ¿Qué roles se necesitan?
- Diseñar estrategia de subagentes

### Fase 2: Lanzamiento Paralelo
- Preparar prompts auto-contenidos
- Lanzar en UN SOLO mensaje (CRÍTICO)
- Cada subagente retorna ID único

### Fase 3: Consolidación de Resultados
- Extraer información clave
- Identificar patrones cross-dimensional
- Priorizar hallazgos (Impacto vs Esfuerzo)

### Fase 4: Output Final
- Documento consolidado
- Proporcionar IDs de subagentes para follow-up

Patterns de Coordinación

5. Biblioteca de Patterns

Sistema de 18+ Patterns Reutilizables

Estructura de un pattern:

pattern:
  id: "HCP-PAT-XXX-NN"
  nombre: "Nombre Descriptivo"
  versión: "X.Y.Z"
  estado: "FORMAL | PROPOSED | DEPRECATED"
  
contenido:
  intención: "Qué problema resuelve"
  triggers: "Cuándo aplicar"
  implementación: "Pasos concretos"
  métricas: "Cómo medir éxito"
  anti_patrones: "Qué evitar"

Patterns Destacados

Pattern 5: Temporal Hierarchy

propósito: Organizar sesiones en jerarquía temporal (diario → anual)
aplicable_a: Proyectos largos (6+ meses)
métricas_validadas:
  navegación: 30 min → 5 min (83% mejora)
  onboarding: 3 días → 2 horas (90% mejora)

Pattern 9: Context Fork + Contract Snapshot (CFCS)

propósito: Separar exploración de ejecución con contrato congelado
problema_resuelto: Drift, contradicciones, re-debates en chats largos
métricas_validadas:
  turnos_totales: 80-120 → 30-50 (40% reducción)
  correcciones: 15-25 → 3-6 (75% reducción)
  re_debates: 8-12 → 0 (100% eliminación)

Pattern 10: Drift Detection

propósito: Detectar cuando AI se desvía de constraints
triggers:
  - Constraint P0 violado
  - Implementación difiere del plan sin preguntar
  - Re-aparece error ya corregido

Pattern 11: Multi-Model Consensus

propósito: Usar múltiples modelos LLM para decisiones críticas
aplicable_a: Decisiones arquitectónicas de alto riesgo
proceso:
  1. Formular pregunta específica
  2. Consultar a N modelos (Claude, GPT-4, Gemini)
  3. Identificar consenso
  4. Si discrepancia → profundizar

Pattern 13: Confirmation Protocol

propósito: Forzar confirmación humana antes de acciones irreversibles
triggers:
  - Operación irreversible (delete, drop, migrate)
  - Cambios en producción
  - Refactors masivos (>20 archivos)

Composición de Patterns

Los patterns son composables:

# Proyecto: Refactor Arquitectónico Mayor

## Fase 1: Investigación
Pattern usado: Temporal Hierarchy (Nivel Diario)

## Fase 2: Decisión
Pattern usado: Context Fork + Contract (Pattern 9)

## Fase 3: Planificación
Pattern usado: Multi-Role (Pattern 8)

## Fase 4: Implementación
Pattern usado: Orchestrate Subagents

## Fase 5: Consolidación
Pattern usado: Temporal Hierarchy (Nivel Semanal)

6. Sistema de Aprendizaje (Learning Capture)

Ecosistema de Learnings

Estructura:

### ✅ [Learning Positivo]
**Learning**: [Frase concisa]
**Context**: [Situación]
**Implementation**: [Código/pasos]
**Benefit**: [Por qué útil]

### ⚠️ [Learning Precautorio]
**Learning**: [Frase concisa]
**Solution**: [Cómo resolver]
**Alternative**: [Opción alternativa]

### ❌ [Anti-pattern]
**Learning**: [Qué NO hacer]
**Problem**: [Consecuencias]
**Correct approach**: [Qué hacer en su lugar]

Anti-patterns Documentados

Ciclo de Vida de un Learning

DÍA 1: Descubrimiento
"Ollama primera llamada tarda 5-10s (cold start)"
    ↓
SEMANA 1: Validación
"Confirmado en múltiples ejecuciones"
    ↓
MES 1: Solución
"Implementamos warmup call al inicio"
    ↓
TRIMESTRE: Generalización
"Pattern: Warmup services con cold start"
    ↓
AÑO: Best Practice
"Lección: Servicios externos necesitan warmup"
    ↓
PERMANENTE: Context.md
"Constraint: SIEMPRE warmup en startup"

7. Flow Idea → Implementación

De Idea Rough a Código

## Stage 1: Idea Capture (10-15 min)
**Input**: Idea vaga
**Output**: .procontext/ideas/YYYY-MM-DD-idea-name.md
**Tools**: idea-template.md

## Stage 2: Research & Validation (2-4 horas)
**State**: RESEARCH
**Output**: .procontext/snapshots/IDEA-NAME-research.md
**Actividades**: Investigar soluciones, validar assumptions, prototipar

## Stage 3: Planning (1-2 horas)
**State**: PLAN
**Output**: .procontext/planning/tasks/IDEA-NAME-plan.md
**Actividades**: Arquitectura, fases, quality gates, timeline

## Stage 4: Setup (2-4 horas)
**State**: IMPLEMENT
**Output**: Proyecto con HCP completo + skeleton
**Actividades**: git init, dependencias, .procontext/, .cursorrules

## Stage 5: Implementation Iterativa
**States**: PLAN → IMPLEMENT → VERIFY (ciclo)
**Output**: Features implementadas
**Actividades**: Por fases, verificar quality gates

## Stage 6: Consolidation
**State**: COMPACT
**Output**: context.md actualizado, learnings.md consolidado
**Actividades**: Archivar, crear ADRs, limpiar

Skills de Structuring

Conclusión: Potencia Real de HCP

vertientes_avanzadas:
  1_flujo_externo:
    - Context handoff (8 técnicas)
    - Clarify first (3 niveles)
    - Historial trazable
  
  2_roles_prompt_engineering:
    - 9 roles estándar
    - Pattern 8 (multi-role)
    - Pattern 14 (vibes)
  
  3_memoria_persistente:
    - 5 niveles jerarquía
    - learnings + decisions + ADRs
    - Recovery progresivo
  
  4_orquestación_multi_agente:
    - Lanzamiento paralelo
    - Consolidación cross-dimensional
    - 3 patterns de coordinación
  
  5_patterns_library:
    - 18+ patterns validados
    - Composables entre sí
  
  6_learning_capture:
    - Anti-patterns documentados
    - Ciclo día → año → permanente
  
  7_idea_implementation_flow:
    - 6 stages estructurados
    - Skills de structuring

HCP permite:

• ✅ Proyectos complejos con múltiples agentes
• ✅ Memoria persistente que evoluciona
• ✅ Transfer de contexto 90% eficiencia
• ✅ Captura de learnings y anti-patterns
• ✅ Flow completo desde idea hasta código
• ✅ Onboarding en 2 horas (vs 2-3 días)
• ✅ Navegación de historial de 7 meses en 5 minutos

Aprende Más

• Sistema de 4 Capas - Arquitectura de memoria
• Patterns Completos - Referencia de 18 patterns
• Roles y Vibes - Sistema completo
• States y Workflow - Máquina de estados

Validado en 43+ proyectos de producción desde 2025.