HCP Templates — Guía Visual Completa

Para: Decidir qué template usar en 30 segundos
Formato: Visual + decisión rápida

Decisión Rápida: Flowchart

¿Cuánto durará el proyecto?
│
├─ <1 día (experimento)
│  └─> NIVEL 0 (Ultra)
│      1 archivo, 2 min setup
│
├─ 1 semana - 1 mes (side project)
│  └─> NIVEL 1 (Minimal)
│      3-5 archivos, 10 min setup
│
├─ 1-3 meses (proyecto serio)
│  │
│  ├─ Solo tú
│  │  └─> NIVEL 2 (Standard)
│  │      5-8 archivos, 30 min setup
│  │
│  └─ Con colaboradores
│     └─> NIVEL 3 (Professional)
│         8-12 archivos, 2h setup
│
└─ 6+ meses (producción)
   │
   ├─ Startup / OSS
   │  └─> NIVEL 3 (Professional)
   │      ADRs, specs, verify gates
   │
   ├─ Enterprise
   │  └─> NIVEL 4-5 (Enterprise/Advanced)
   │      Audit trails, governance
   │
   └─ Regulado (medical, finance)
      └─> NIVEL 6 (Maximum)
          EU AI Act compliance

Nivel 0: Ultra — Probar HCP por Primera Vez

Setup: 2 Minutos

proyecto/
└── .procontext/
    └── context.md  (1 archivo)

Contenido: context.md

# Contexto del Proyecto

## What
To-do app para aprender React

## Stack
- React 18
- Vite
- TypeScript

## Current Focus
Setup inicial + primer component

Caso de Uso

Escenario: Tutorial de React (1-2 días)
Developer: Estudiante aprendiendo
Resultado: IA sabe que usas React/TS (no confunde con Vue/JS)

Cuándo Subir de Nivel

🚦 Señales:

Proyecto dura >1 semana
Necesitas recordar decisiones entre sesiones
Alguien más se une al proyecto

Migración: +5 minutos (agregar session.md y memory/)

Nivel 1: Minimal — Side Projects

Setup: 10 Minutos

proyecto/
└── .procontext/
    ├── context.md
    ├── session.md
    └── memory/
        └── learnings.md

Contenido Nuevo vs Nivel 0

session.md (trabajo actual):

# Sesión 2026-05-02

## En Progreso
- [ ] Componente TodoList
- [ ] Hook useTodos

## Bloqueadores
Ninguno

memory/learnings.md (aprendizajes):

# Aprendizajes

## 2026-05-01: useEffect Dependencies
Aprendí que useEffect sin dependencies array se ejecuta en cada render.
Solución: Agregar [] para ejecutar solo una vez.

Caso de Uso

Escenario: Portfolio website (3 semanas)
Developer: Freelancer
Beneficio: Memoria entre sesiones (sabes qué hiciste ayer)

Cuándo Subir de Nivel

🚦 Señales:

Segunda persona se une
Necesitas documentar “por qué” de decisiones
Proyecto va a producción

Migración: +30 minutos (agregar decisions/, tasks/)

Nivel 2: Standard — Colaboración Básica

Setup: 30 Minutos

proyecto/
└── .procontext/
    ├── context.md
    ├── session.md
    ├── memory/
    │   ├── learnings.md
    │   └── decisions/        # 🆕 ADRs
    │       └── 0001-use-react.md
    ├── sessions/             # 🆕 Historial
    │   └── 2026-05-01.md
    └── tasks/                # 🆕 Task tracking
        └── TASK-001.md

Contenido Nuevo vs Nivel 1

decisions/0001-use-react.md (decisión arquitectónica):

# ADR-0001: Usar React en vez de Vue

**Fecha**: 2026-04-30  
**Status**: Accepted

## Context
Decidiendo framework para portfolio

## Decision
React 18 + TypeScript

## Rationale
- Team conoce React mejor que Vue
- Más ofertas laborales con React
- Ecosistema más maduro

## Consequences
- Curva aprendizaje TypeScript (acceptable)

Caso de Uso

Escenario: Open source library (2-3 meses)
Developers: 1 core + 5 contributors
Beneficio: Contributors entienden "por qué" decisiones (leen ADRs)

Cuándo Subir de Nivel

🚦 Señales:

Proyecto va a producción
Necesitas feature specs formales
Necesitas quality gates pre-deploy

Migración: +2 horas (agregar features/, verify/)

Nivel 3: Professional — Producción

Setup: 2 Horas

proyecto/
└── .procontext/
    ├── context.md
    ├── session.md
    ├── memory/
    │   └── learnings.md
    ├── sessions/
    ├── decisions/            # ADRs
    ├── features/             # 🆕 Feature specs
    │   └── FEAT-001-auth.md
    └── verify/               # 🆕 Quality gates
        └── VERIFY-001-auth.md

Contenido Nuevo vs Nivel 2

features/FEAT-001-auth.md (spec de feature):

# FEAT-001: User Authentication

**Status**: In Progress  
**Owner**: @alice

## Acceptance Criteria

Given: User with valid credentials  
When: POST /login  
Then:
  - Returns 200 + JWT token
  - Token expires in 15min
  - Refresh token in httpOnly cookie

## Verify
Before merging: Complete VERIFY-001-auth.md checklist

verify/VERIFY-001-auth.md (quality gate):

# VERIFY-001: Auth Security

## Checklist Pre-Deploy
- [ ] JWT secret is 256-bit random
- [ ] Tokens expire correctly
- [ ] httpOnly cookies (no XSS)
- [ ] Rate limiting on /login (5 attempts/min)
- [ ] Tests coverage ≥85%

Caso de Uso

Escenario: SaaS startup (6-12 meses)
Team: 3-5 developers
Beneficio: Features especificadas, quality gates automáticos
Resultado: -70% bugs en producción

Cuándo Subir de Nivel

🚦 Señales:

Necesitas audit trails (compliance)
Team >5 personas
Múltiples proyectos coordinados

Migración: +4 horas (agregar compliance/, capas explícitas)

Nivel 4-6: Enterprise/Advanced/Maximum

Nivel 4: Enterprise (Audit Trails)

.procontext/
├── knowledge/           # 🆕 Capa explícita
│   ├── context/
│   ├── memory/
│   └── decisions/
├── specs/               # 🆕 Capa explícita
│   ├── features/
│   └── verify/
├── execution/           # 🆕 Capa explícita
│   ├── sessions/
│   └── skills/
└── compliance/          # 🆕 Audit log
    └── audit-log.jsonl

Caso de uso: Fintech con SOC2, 10-20 developers

Nivel 5: Advanced (Multi-Proyecto)

.procontext/
├── [todo Level 4]
├── prompts/             # 🆕 Reusable prompts
├── scripts/             # 🆕 Automation
├── workflows/           # 🆕 EOD/EOW routines
└── research/            # 🆕 Research outputs

Caso de uso: Microservices ecosystem, 5-30 developers

Nivel 6: Maximum (EU AI Act)

.procontext/
├── [todo Level 5]
├── compliance-eu-ai/    # 🆕 EU AI Act compliance
│   ├── technical-documentation.md
│   ├── risk-assessment.md
│   └── post-market-monitoring.md
└── governance/          # 🆕 Multi-team policies
    └── approval-chains.yml

Caso de uso: Medical AI, autonomous vehicles (regulado)

Comparación Lado a Lado

Contenido por Nivel

Archivo/Carpeta	Nivel 0	Nivel 1	Nivel 2	Nivel 3	Nivel 4+
`context.md`	✅	✅	✅	✅	✅
`session.md`	❌	✅	✅	✅	✅
`memory/learnings.md`	❌	✅	✅	✅	✅
`sessions/` (historial)	❌	❌	✅	✅	✅
`decisions/` (ADRs)	❌	❌	✅	✅	✅
`tasks/`	❌	❌	✅	✅	✅
`features/` (specs)	❌	❌	❌	✅	✅
`verify/` (gates)	❌	❌	❌	✅	✅
Capas explícitas (knowledge/, specs/, execution/)	❌	❌	❌	❌	✅
`compliance/`	❌	❌	❌	❌	✅
`governance/`	❌	❌	❌	❌	✅ (Nivel 6)

Tiempo y ROI

Nivel	Setup Time	Files	Team Size	ROI (Típico)
0	2 min	1	1	5-10x
1	10 min	3-5	1	10-15x
2	30 min	5-8	1-2	15-20x
3	2 horas	8-12	2-5	20-50x
4	4 horas	10-15	3-20	30-60x
5	8 horas	15-25	5-30	40-80x
6	16 horas	25-40	5-50+	50-100x

Ejemplos Visuales

Nivel 0: Ultra

┌──────────────┐
│ context.md   │  "Proyecto React + TS"
└──────────────┘
       ↑
       │ (IA lee)
       │
┌──────────────┐
│   AI Agent   │  "Entiendo, usas React + TS"
└──────────────┘

Beneficio: IA tiene contexto básico (no genera código inconsistente)

Nivel 1: Minimal

┌──────────────┐
│ context.md   │  "Stack: React + TS"
└──────────────┘
┌──────────────┐
│ session.md   │  "Hoy: TodoList component"
└──────────────┘
┌──────────────┐
│ learnings.md │  "useEffect pitfalls"
└──────────────┘
       ↑
       │ (IA lee)
       │
┌──────────────┐
│   AI Agent   │  "Sé qué haces hoy + qué aprendiste ayer"
└──────────────┘

Beneficio: IA tiene memoria entre sesiones

Nivel 3: Professional

┌──────────────┐
│ context.md   │  "Stack overview"
└──────────────┘
┌──────────────┐
│ decisions/   │  "Por qué JWT (ADR-001)"
└──────────────┘
┌──────────────┐
│ features/    │  "FEAT-001: Auth spec"
└──────────────┘
┌──────────────┐
│ verify/      │  "VERIFY-001: Security checklist"
└──────────────┘
       ↑
       │ (IA lee según necesite)
       │
┌──────────────┐
│   AI Agent   │  "Implemento FEAT-001 según spec"
└──────────────┘
                "Valido contra VERIFY-001"

Beneficio: IA implementa con specs claras, valida automáticamente

Anti-Patterns: Qué NO Hacer

❌ Anti-Pattern 1: Saltar Niveles

❌ MAL: Nivel 0 → Nivel 6 directamente
  Resultado: Overwhelmed, abandonas HCP

✅ BIEN: Nivel 0 → 1 → 2 → 3 → 4 (gradual)
  Resultado: Adopción natural, ROI incremental

❌ Anti-Pattern 2: Nivel 6 para Side Project

❌ MAL: Side project (3 semanas) con Nivel 6
  Setup: 16 horas
  Proyecto: 40 horas
  Overhead: 40% (!!)

✅ BIEN: Side project con Nivel 1
  Setup: 10 minutos
  Proyecto: 40 horas
  Overhead: 0.4%

❌ Anti-Pattern 3: Nivel 0 en Producción

❌ MAL: SaaS en producción con Nivel 0 (solo context.md)
  Sin: ADRs, specs, verify gates
  Resultado: Bugs, decisiones perdidas, caos

✅ BIEN: SaaS en producción con Nivel 3
  Con: ADRs, feature specs, quality gates
  Resultado: Trazabilidad, 0 bugs olvidados

Migración Gradual: Path Recomendado

Para Proyectos Nuevos

Semana 1:    Nivel 0 (ultra)     → Prototipo rápido
Semana 2-4:  Nivel 1 (minimal)   → Side project serio
Mes 2-3:     Nivel 2 (standard)  → +Colaboradores
Mes 4-6:     Nivel 3 (professional) → Pre-producción
Mes 6+:      Nivel 3 o 4+        → Producción/enterprise

Para Proyectos Existentes

Día 1:       Añadir .procontext/context.md (Nivel 0)
Semana 1:    Añadir session.md + memory/ (Nivel 1)
Mes 1:       Añadir decisions/ + tasks/ (Nivel 2)
Mes 2:       Añadir features/ + verify/ (Nivel 3)
Opcional:    Nivel 4+ si necesitas (enterprise)

Matriz de Decisión Final

Si Tu Proyecto Es…	Usa Nivel	Por Qué
Tutorial (1-2 días)	0	No vale la pena más
Side project (1 mes)	1	Memoria básica suficiente
Freelance (2-3 meses)	2	+ADRs para decisiones
Producción (6+ meses)	3	+Specs y quality gates
Enterprise (10+ devs)	4-5	+Audit trails
Regulado (medical, etc.)	6	+EU AI Act compliance

Próximos Pasos

Empieza con el Quickstart de 10 minutos
Ve casos de uso reales
Lee sobre las capas
Explora patterns avanzados

HCP Templates — Del Más Simple al Más Completo
Adopción gradual, ROI desde día 1