HCP en 10 Minutos — Tutorial Visual Paso a Paso

Para: Developers que nunca usaron HCP
Tiempo: 10 minutos
Resultado: Tu primer proyecto con HCP funcionando

El Problema Que HCP Resuelve

Antes de HCP: Contexto Perdido

Lunes:
  Tú → AI: "Crea endpoint REST con PostgreSQL"
  AI: ✅ Genera código perfecto (PostgreSQL)

Martes (nueva sesión):
  Tú → AI: "Agrega autenticación"
  AI: 🤔 Genera código con MongoDB
       ↑
  ¿QUÉ PASÓ? La IA olvidó que usabas PostgreSQL

Resultado: Pasas 30% de tu tiempo corrigiendo inconsistencias.

Después de HCP: Contexto Persistente

Lunes:
  Tú → AI: "Crea endpoint REST"
  AI: [Lee .procontext/context.md]
      ✅ "Veo que usas PostgreSQL, FastAPI, Python 3.11"
      ✅ Genera código consistente

Martes (nueva sesión):
  Tú → AI: "Agrega autenticación"
  AI: [Lee .procontext/context.md]
      ✅ "Veo que usas PostgreSQL (no MongoDB)"
      ✅ Genera código consistente desde día 1

Resultado: La IA siempre tiene contexto. 0% tiempo perdido en inconsistencias.

Paso 1: Instalar HCP (2 minutos)

Opción A: Copiar Template Manualmente

# 1. Ve a tu proyecto
cd tu-proyecto/

# 2. Crea la carpeta .procontext
mkdir .procontext

# 3. Crea el archivo context.md
cat > .procontext/context.md <<'EOF'
# Contexto del Proyecto

## What
[Describe tu proyecto en 2-3 líneas]

## Stack
- **Backend**: [Framework/lenguaje]
- **Database**: [PostgreSQL/MySQL/MongoDB]
- **Frontend**: [React/Vue/etc]

## Current Focus
[En qué estás trabajando ahora]

## Constraints
- [Restricciones importantes que la IA debe respetar]
EOF

# 4. ¡Listo!

Opción B: Usar HCP Toolkit (cuando esté disponible)

npm install -g @haletheia/hcp-toolkit
hcp init
# Te hace preguntas, genera structure automáticamente

Paso 2: Configurar Tu Contexto (3 minutos)

Edita .procontext/context.md:

# Contexto del Proyecto

## What
Sistema de gestión de tareas (Todo app) con API REST y auth JWT.

## Stack
- **Backend**: FastAPI (Python 3.11)
- **Database**: PostgreSQL 15
- **Auth**: JWT (pyjwt)
- **Testing**: pytest

## Current Focus
Implementando autenticación de usuarios (login, signup, JWT tokens)

## Constraints
- NUNCA usar ORM completo (solo SQL builder o raw SQL)
- Tests coverage mínimo 80%
- API responses siempre JSON:API format
- NO usar async si no es necesario (KISS)

Por qué esto importa:

• La IA ahora sabe que usas FastAPI (no Flask, no Django)
• No te va a proponer MongoDB cuando usas PostgreSQL
• Respeta tus constraints (80% coverage, no ORM, etc.)

Paso 3: Probar Que Funciona (2 minutos)

En Cursor / Windsurf / Cline

Abre tu editor con IA y pregunta:

Tú: "Crea un endpoint POST /users para signup"

Antes (sin HCP):

# La IA podría generar:
from flask import Flask  # ¿Flask? Usas FastAPI!
import sqlite3  # ¿SQLite? Usas PostgreSQL!

app = Flask(__name__)
# ...código inconsistente

Después (con HCP):

# La IA genera:
from fastapi import FastAPI, HTTPException
import asyncpg  # ✅ PostgreSQL (correcto)

app = FastAPI()

@app.post("/users")
async def signup(user_data: UserCreate):
    # INSERT usando asyncpg (no ORM, como pediste)
    # ...código consistente con tu stack

Resultado: La IA respetó:

• ✅ FastAPI (no Flask)
• ✅ PostgreSQL (no SQLite)
• ✅ No ORM (como pediste en Constraints)

Paso 4: Trabajar con HCP (3 minutos)

Durante el Día

Trabaja normalmente. La IA lee .procontext/context.md automáticamente.

Tú: "Agrega logging al endpoint de signup"
AI: [Lee context.md]
    ✅ "Usando logging de Python estándar + formato estructurado"
    ✅ Genera código consistente

Tú: "Optimiza la query de login"
AI: [Lee context.md]
    ✅ "Usando asyncpg (no ORM, como especificaste)"
    ✅ Genera SQL optimizado

Al Final del Día (Opcional)

Si quieres recordar qué hiciste:

# Crea un archivo session.md
cat > .procontext/session.md <<'EOF'
# Sesión 2026-05-02

## Completado
- [x] Endpoint POST /users (signup)
- [x] Endpoint POST /login (JWT generation)
- [x] Tests para auth endpoints (coverage 85%)

## Bloqueadores
Ninguno

## Next
- [ ] Refresh tokens
- [ ] Email verification
EOF

Por qué: Mañana lees session.md y sabes exactamente dónde quedaste.

Visualización: Cómo Funciona HCP

Sin HCP (Contexto en Tu Cabeza)

┌─────────────┐
│  TU CABEZA  │  "Uso FastAPI, PostgreSQL, no ORM..."
└─────────────┘
       │
       ↓ (le dices a la IA cada vez)
┌─────────────┐
│     IA      │  Olvida entre sesiones
└─────────────┘
       │
       ↓
  💥 Inconsistencias

Con HCP (Contexto en Git)

┌──────────────────┐
│ .procontext/     │  ← Contexto versionado en Git
│  context.md      │     "FastAPI, PostgreSQL, no ORM"
└──────────────────┘
       ↑
       │ (la IA lee automáticamente)
       │
┌──────────────────┐
│      IA          │  ← Siempre tiene contexto
└──────────────────┘
       │
       ↓
  ✅ Código consistente siempre

Comparación: Con HCP vs Sin HCP

Siguientes Pasos

Si el Proyecto Dura >1 Semana

Migra a Nivel 1 (Minimal):

mkdir -p .procontext/memory
touch .procontext/session.md
touch .procontext/memory/learnings.md

Qué ganas:

• session.md: Tracking diario (qué hiciste hoy)
• memory/learnings.md: Aprendizajes acumulados

Tiempo: +5 minutos setup

Si el Proyecto Va a Producción

Migra a Nivel 3 (Professional):

mkdir -p .procontext/{decisions,features,verify}

Qué ganas:

• decisions/: ADRs (Architecture Decision Records)
• features/: Specs de features
• verify/: Quality gates pre-deploy

Tiempo: +2 horas setup (vale la pena)

Casos de Uso Reales

Caso 1: Freelancer (1 persona)

Proyecto: Todo app para cliente
Duración: 3 semanas
Template: Nivel 1 (Minimal)
Tiempo invertido HCP: 10 min setup
Tiempo ahorrado: ~8 horas (consistencia, no repetir contexto)
ROI: 48x

Caso 2: Startup (3 developers)

Proyecto: SaaS dashboard
Duración: 6 meses
Template: Nivel 3 (Professional)
Tiempo invertido HCP: 2h setup + 30min/semana
Tiempo ahorrado: ~40h/mes (onboarding, decisiones documentadas)
ROI: 20x

Caso 3: Open Source (10+ contributors)

Proyecto: Python ML library
Duración: 1+ año
Template: Nivel 3 (Professional)
Tiempo invertido HCP: 2h setup + 1h/mes
Tiempo ahorrado: ~60h/mes (contributors leen context, no preguntan)
ROI: 30x

FAQ

P: ¿Tengo que usar un IDE específico?

R: No. HCP funciona con:

• ✅ Cursor
• ✅ Windsurf
• ✅ Cline
• ✅ Aider
• ✅ Claude Projects
• ✅ ChatGPT Code Interpreter
• ✅ Cualquier AI agent que lea archivos

P: ¿Qué pasa si “tiro toda la carpeta al LLM”?

R: Eso funciona… pero:

• ❌ Procesamiento lento (lee TODO)
• ❌ Costos altos (tokens desperdiciados)
• ❌ No hay estructura (la IA no sabe qué es importante)

HCP es selectivo:

• ✅ La IA lee solo lo necesario (context.md, session.md)
• ✅ Rápido y económico
• ✅ Estructura clara (sabe qué leer cuándo)

P: ¿Esto reemplaza documentación?

R: No. HCP complementa documentación:

• README.md: Para humanos (usuarios finales)
• .procontext/: Para IA agents (developers trabajando con IA)

P: ¿Funciona con proyectos existentes?

R: ¡Sí! Solo:

1. Crea .procontext/context.md
2. Describe tu proyecto
3. Ya funciona

No necesitas migrar nada. HCP se añade sobre tu proyecto existente.

Resumen: 3 Archivos, Máximo Impacto

HCP Nivel 0 (lo mínimo):

tu-proyecto/
└── .procontext/
    └── context.md  (200-300 palabras)

Beneficio:

• ✅ IA siempre con contexto
• ✅ 0% inconsistencias
• ✅ -30% tiempo corrigiendo
• ✅ 2 minutos setup

Vale la pena: Absolutamente sí.

Próximo Paso

👉 Lee la guía completa de templates para saber cuándo usar cada nivel.

👉 Ve ejemplos reales de proyectos usando HCP.

👉 Únete a la comunidad y pregunta lo que sea.

HCP — Contexto como Código
La IA recuerda. Tú programas.