Las Capas de HCP — Explicado Prácticamente

Para: Entender cómo HCP organiza el conocimiento
Nivel: Intermedio
Prerequisito: Quickstart de 10 minutos

El Problema: “Tirar Todo a la IA”

Lo Que La Gente Hace (Sin Estructura)

# Opción A: Tirar toda la carpeta
$ cursor --add-folder ./mi-proyecto

# La IA lee:
- 500 archivos de código
- 1000 node_modules
- 200 tests
- 50 configs
- README, LICENSE, etc.

Resultado:
- ❌ Lento (procesa TODO)
- ❌ Caro (tokens desperdiciados)
- ❌ IA confundida (no sabe qué es importante)

Lo Que HCP Hace (Con Estructura)

# La IA lee SOLO lo necesario:
.procontext/
  ├── context.md       # ← "Esto es importante ahora"
  ├── session.md       # ← "Estoy trabajando en X"
  └── decisions/       # ← "Por qué decidimos Y"

Resultado:
- ✅ Rápido (lee 3-5 archivos)
- ✅ Económico (tokens enfocados)
- ✅ IA enfocada (sabe qué leer cuándo)

Analogía:

• Sin HCP = Dar un libro de 1000 páginas y decir “lee esto”
• Con HCP = Dar tabla de contenidos + capítulos relevantes

Las Tres Capas de HCP

HCP organiza información en 3 capas conceptuales:

1. KNOWLEDGE (Qué sabemos)
   ↓
2. SPECS (Qué queremos)
   ↓
3. EXECUTION (Cómo lo construimos)

Importante: Estas capas están implícitas en Nivel 1-3. Solo se hacen explícitas en Nivel 4+ (educativo/enterprise).

Capa 1: KNOWLEDGE — Qué Sabemos

Qué Va Aquí

Todo el conocimiento acumulado del proyecto:

• Stack tecnológico actual
• Decisiones arquitectónicas pasadas (ADRs)
• Aprendizajes de failures
• Vocabulario específico del dominio
• Memoria del proyecto

En La Práctica

Nivel 1-3 (estructura simple):

.procontext/
├── context.md           # ← Stack, constraints actuales
├── memory/
│   └── learnings.md     # ← Aprendizajes acumulados
└── decisions/
    └── 0001-*.md        # ← "Por qué decidimos X"

Nivel 4+ (estructura explícita):

.procontext/
└── knowledge/           # ← Capa explícita
    ├── context/
    │   └── current.md
    ├── memory/
    │   └── learnings.md
    └── decisions/
        └── 0001-*.md

Ejemplo Real: context.md

# Contexto del Proyecto

## Stack (KNOWLEDGE: Qué usamos)
- Backend: FastAPI (Python 3.11)
- Database: PostgreSQL 15
- Auth: JWT with refresh tokens

## Architecture Decisions (KNOWLEDGE: Por qué así)
- Ver decisions/0001-jwt-not-sessions.md
- Ver decisions/0002-postgresql-not-mongodb.md

## Domain Vocabulary (KNOWLEDGE: Glosario)
- "User" = Authenticated user (not guest)
- "Session" = JWT access token (15min TTL)
- "Account" = Billing entity (can have N users)

Cuándo la IA lee esto:

• Siempre (al inicio de cada chat)
• Es su “memoria a largo plazo”

Capa 2: SPECS — Qué Queremos

Qué Va Aquí

Especificaciones de lo que vamos a construir:

• Features specs (Gherkin/BDD)
• Acceptance criteria
• Architecture plans
• Quality gates (verify)

En La Práctica

Nivel 1-2 (no existe, trabajo ad-hoc):

❌ No hay specs formales

Nivel 3+ (specs estructuradas):

.procontext/
├── features/            # ← Qué queremos construir
│   └── FEAT-001-auth.md
└── verify/              # ← Cómo validamos que funciona
    └── VERIFY-001-auth.md

Nivel 4+ (capa explícita):

.procontext/
└── specs/               # ← Capa explícita
    ├── features/
    │   └── FEAT-001-auth.md
    ├── planning/
    │   └── architecture-2026-Q2.md
    └── verify/
        └── VERIFY-001-auth.md

Ejemplo Real: features/FEAT-001-auth.md

# FEAT-001: User Authentication

**Status**: Planning  
**Owner**: @dev-alice

## Acceptance Criteria (SPEC: Qué queremos)

### Scenario 1: Successful Login
Given: User with valid credentials  
When: POST /login with email + password  
Then:
  - Returns 200 OK
  - Body contains JWT access token (15min TTL)
  - Body contains refresh token (7d TTL)
  - httpOnly cookie set with refresh token

### Scenario 2: Invalid Credentials
Given: User with wrong password  
When: POST /login  
Then:
  - Returns 401 Unauthorized
  - No tokens returned

## Verify Gate
Before merging: See verify/VERIFY-001-auth.md

Cuándo la IA lee esto:

• Cuando trabajas en esa feature
• Le dices: “Implementa FEAT-001”
• IA lee spec, sabe exactamente qué hacer

Capa 3: EXECUTION — Cómo Lo Construimos

Qué Va Aquí

Todo relacionado con la ejecución del trabajo:

• Sessions (trabajo diario)
• Skills (procedures reusables)
• Prompts (templates de instrucciones)
• Scripts (automation)
• Generated code / snapshots

En La Práctica

Nivel 1-2 (básico):

.procontext/
├── session.md           # ← Trabajo actual
└── sessions/
    └── 2026-05-02.md    # ← Historial

Nivel 3 (+ structure):

.procontext/
├── session.md
├── sessions/
└── skills/              # ← Procedures reusables
    └── deploy-prod.md

Nivel 4+ (capa explícita):

.procontext/
└── execution/           # ← Capa explícita
    ├── sessions/
    │   └── 2026-05-02.md
    ├── skills/
    │   └── deploy-prod.md
    ├── snapshots/       # ← Contract snapshots (Pattern 9)
    │   └── 2026-05-02-auth-contract.md
    └── impl/            # ← Generated code
        └── auth-spike.py

Ejemplo Real: session.md

# Sesión 2026-05-02

## Focus (EXECUTION: En qué trabajo hoy)
Implementar FEAT-001 (User authentication)

## Progress
- [x] Created feature spec (FEAT-001-auth.md)
- [x] Designed JWT approach (15min access, 7d refresh)
- [ ] Implement POST /login endpoint
- [ ] Implement POST /refresh endpoint
- [ ] Write tests (target 85% coverage)

## Blockers
None

## Next
- Implement refresh token rotation
- Add rate limiting (Pattern: rate-limiter skill)

Cuándo la IA lee esto:

• Al inicio de cada chat (para saber “dónde quedamos”)
• Es tu “working memory”

Cómo Las Capas Trabajan Juntas

Flujo Completo: Feature Nueva

PASO 1: Research (KNOWLEDGE)
  → "¿Cómo hacemos auth actualmente?"
  → IA lee: knowledge/context.md, decisions/0001-jwt.md
  → Responde con stack actual, constraints

PASO 2: Plan (SPECS)
  → "Crea spec para login endpoint"
  → IA escribe: specs/features/FEAT-001-login.md
  → Define acceptance criteria

PASO 3: Implement (EXECUTION)
  → "Implementa FEAT-001"
  → IA lee: specs/features/FEAT-001-login.md
  → IA escribe: código en src/auth/login.py
  → IA actualiza: execution/session.md

PASO 4: Verify (SPECS ← EXECUTION)
  → "Verifica FEAT-001"
  → IA lee: specs/verify/VERIFY-001-login.md
  → IA ejecuta: tests, checks coverage
  → IA marca: verify checklist ✅

PASO 5: Capture (EXECUTION → KNOWLEDGE)
  → "Captura learnings de FEAT-001"
  → IA escribe: knowledge/memory/learnings.md
  → Nueva entrada: "JWT refresh rotation approach"

Resultado: Ciclo completo trazable, nada se pierde.

Niveles y Capas: Cuándo Se Hacen Explícitas

Nivel 0-3: Capas Implícitas

.procontext/
├── context.md           # ← KNOWLEDGE (implícito)
├── session.md           # ← EXECUTION (implícito)
├── decisions/           # ← KNOWLEDGE (implícito)
├── features/            # ← SPECS (implícito)
└── verify/              # ← SPECS (implícito)

Por qué: Simplicidad. Las capas existen conceptualmente, pero no hay carpetas knowledge/, specs/, execution/.

Cuándo usar: 99% de proyectos (freelance, startup, OSS)

Nivel 4+: Capas Explícitas

.procontext/
├── knowledge/           # ← KNOWLEDGE (explícito)
│   ├── context/
│   ├── memory/
│   └── decisions/
├── specs/               # ← SPECS (explícito)
│   ├── features/
│   ├── planning/
│   └── verify/
└── execution/           # ← EXECUTION (explícito)
    ├── sessions/
    ├── skills/
    └── snapshots/

Por qué: Claridad formal. Útil para:

• Enseñar HCP (educational)
• Compliance (audit trails necesitan estructura clara)
• Enterprise (múltiples equipos necesitan convención rígida)

Cuándo usar: 1% de proyectos (enterprise, regulado, educational)

Comparación: Nivel 3 vs Nivel 4

Mismo Contenido, Diferente Estructura

Nivel 3 (Implícito):

.procontext/
├── context.md                    # KNOWLEDGE
├── decisions/0001-jwt.md         # KNOWLEDGE
├── features/FEAT-001-auth.md     # SPECS
├── verify/VERIFY-001-auth.md     # SPECS
├── session.md                    # EXECUTION
└── sessions/2026-05-02.md        # EXECUTION

Nivel 4 (Explícito):

.procontext/
├── knowledge/
│   ├── context/current.md        # KNOWLEDGE
│   └── decisions/0001-jwt.md     # KNOWLEDGE
├── specs/
│   ├── features/FEAT-001-auth.md # SPECS
│   └── verify/VERIFY-001-auth.md # SPECS
└── execution/
    ├── session.md                # EXECUTION
    └── sessions/2026-05-02.md    # EXECUTION

Diferencia: Solo estructura de carpetas. El contenido es idéntico.

Recomendación: Usa Nivel 3 (implícito) unless necesites formalidad enterprise.

Mapeo a Conceptos Conocidos

Si Conoces KDD/SDD/SPDD

KNOWLEDGE (HCP) ≈ KDD (Knowledge-Driven Development)
  → Gestión del conocimiento estructurado del proyecto

SPECS (HCP) ≈ SDD (Specification-Driven Development)
  → Especificaciones formales antes de implementar

EXECUTION (HCP) ≈ SPDD (Structured Prompt-Driven Development)
  → Prompts como artefactos ejecutables, versionados

Importante: HCP no requiere que conozcas estos términos. Las capas son intuitivas:

• Knowledge = Qué sabemos
• Specs = Qué queremos
• Execution = Cómo lo hacemos

FAQ

P: ¿Debo crear las 3 carpetas (knowledge/, specs/, execution/)?

R: Solo si usas Nivel 4+. En Nivel 1-3:

• No creas carpetas de capas
• Las capas existen conceptualmente en tu mente
• Ejemplo: decisions/ es KNOWLEDGE (sin carpeta knowledge/)

P: ¿La IA sabe sobre las capas?

R: Sí, pero no necesita carpetas explícitas. La IA entiende:

• context.md = KNOWLEDGE (lee siempre)
• features/ = SPECS (lee cuando implementas feature)
• session.md = EXECUTION (lee para saber qué haces ahora)

P: ¿Qué pasa si mezclo las capas?

R: Nada grave. Ejemplo común:

• Pones learning en session.md (debería ir en memory/learnings.md)
• Funciona igual, solo menos organizado

HCP es permisivo. Mejora con el tiempo.

P: ¿Nivel 4 (capas explícitas) es mejor?

R: No. Es más formal, no mejor.

• Nivel 3: Más simple, funciona igual de bien
• Nivel 4: Más rígido, útil para enterprise/educational

99% de proyectos deberían usar Nivel 1-3.

Resumen Visual

┌─────────────────────────────────────┐
│        KNOWLEDGE (Qué sabemos)       │
│  context.md, decisions/, learnings   │
└─────────────────────────────────────┘
               ↓ (informa)
┌─────────────────────────────────────┐
│         SPECS (Qué queremos)         │
│     features/, verify/, planning     │
└─────────────────────────────────────┘
               ↓ (guía)
┌─────────────────────────────────────┐
│    EXECUTION (Cómo lo construimos)   │
│  session.md, sessions/, skills/      │
└─────────────────────────────────────┘
               ↓ (actualiza)
       (Ciclo: Capture → KNOWLEDGE)

Próximos Pasos

1. Quickstart de 10 minutos — Empieza con Nivel 1 (capas implícitas)
2. Casos de uso — Ve cómo otros usan las capas
3. Patterns avanzados — Profundiza en Patterns 9, 10, 11

HCP — Capas Simples, Máximo Impacto
Organización intuitiva para AI agents