HCP — Casos de Uso Reales

Para: Saber exactamente cómo usar HCP según tu situación
Formato: Escenarios reales + solución HCP

Tabla de Contenidos

1. Freelancer / Solo Developer
2. Startup / Small Team
3. Open Source Maintainer
4. Enterprise / Large Team
5. Estudiante / Learning
6. Consultor / Agency

Freelancer / Solo Developer

Tu Situación

• Trabajas solo
• Múltiples proyectos cliente simultáneos
• Switching constante entre proyectos
• No tienes tiempo para documentar “bonito”

El Problema Sin HCP

Lunes: Trabajas en proyecto A (FastAPI + PostgreSQL)
Martes: Cliente B te pide cambio urgente (Django + MySQL)
Miércoles: Vuelves a proyecto A
  
  Tú: "¿Qué estaba haciendo? ¿Cuál era el stack?"
  AI: "No tengo contexto... ¿usabas Flask?"
  Tú: 😤 Pierdes 30 minutos recordando

La Solución HCP

Template: Nivel 1 (Minimal)

proyecto-cliente-a/
└── .procontext/
    ├── context.md       # Stack: FastAPI, PostgreSQL
    ├── session.md       # "Working on: Payment integration"
    └── memory/
        └── learnings.md # "Cliente prefiere X approach"

proyecto-cliente-b/
└── .procontext/
    ├── context.md       # Stack: Django, MySQL
    ├── session.md       # "Working on: User auth bug"
    └── memory/
        └── learnings.md # "Cliente B's business rules"

Tiempo setup: 10 min por proyecto
Tiempo ahorrado: 2-3h/semana (no re-contextualizas)
ROI: 12-18x

Workflow Diario

# Mañana: Cambias a proyecto A
cd proyecto-a
cat .procontext/session.md  # Lees dónde quedaste
# Trabajas con AI (ya tiene contexto automáticamente)

# Tarde: Cliente B llama urgente
cd proyecto-b
cat .procontext/session.md  # Instantáneo context switch
# AI ya sabe el stack, constraints, todo

Lo que más valoras: “Cambio de proyecto en 30 segundos, no 30 minutos”

Startup / Small Team

Tu Situación

• 3-5 developers
• Proyecto único (SaaS)
• Pre-seed o seed stage
• Iterando rápido, muchos cambios

El Problema Sin HCP

Developer A: "¿Por qué usamos JWT y no sessions?"
Developer B: "Creo que fue por X razón... o Y?"
  
  → Decisión en Slack (perdida)
  → Re-debate cada 2 meses
  → Onboarding nuevo dev: 3-7 días

La Solución HCP

Template: Nivel 3 (Professional)

saas-dashboard/
└── .procontext/
    ├── context.md           # Stack overview
    ├── decisions/
    │   ├── 0001-use-jwt.md      # ← Decisión documentada
    │   ├── 0002-postgresql.md
    │   └── 0003-monolith-first.md
    ├── features/
    │   ├── FEAT-001-user-auth.md
    │   └── FEAT-002-billing.md
    └── verify/
        └── VERIFY-001-security.md

Tiempo setup: 2 horas (one-time)
Tiempo ahorrado: 10-15h/mes (no re-debates, onboarding instant)
ROI: 50-75x

Beneficios Específicos

1. Decisiones Documentadas

# decisions/0001-use-jwt-not-sessions.md

**Status**: Accepted  
**Date**: 2026-04-15  
**Deciders**: Team (3/3)

## Context
Decidiendo entre JWT tokens vs server-side sessions.

## Decision
JWT tokens stored in httpOnly cookies.

## Rationale
- ✅ Stateless (scaling horizontal fácil)
- ✅ Mobile-friendly (JSON response)
- ❌ Cons: Invalidation manual (acceptable para MVP)

## Consequences
- Refresh tokens cada 15 min
- Logout = client-side (token expires)

Resultado: Nuevo dev lee ADR, entiende “por qué” en 2 minutos.

2. Onboarding Instantáneo

Antes:

Día 1-2: Setup local
Día 3-5: "¿Por qué esto así?" (preguntas)
Día 6-7: Primer commit pequeño

Con HCP:

Día 1: Setup local + lee .procontext/ (2h)
Día 2: Primer commit productivo

Ahorro: 5 días → 1 día

3. Feature Specs

# features/FEAT-002-stripe-billing.md

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

## Acceptance Criteria

Given: User has valid credit card  
When: User subscribes to Pro plan  
Then:
  - Stripe creates subscription
  - Database records subscription_id
  - User.plan = "pro"
  - Email confirmation sent

## Verify Gate
See: verify/VERIFY-002-billing.md

Resultado: AI agent sabe exactamente qué implementar, 0 ambigüedad.

Open Source Maintainer

Tu Situación

• Proyecto con 10-100 contributors
• Pull requests constantes
• Necesitas explicar decisiones arquitectónicas
• Contributors nuevos todo el tiempo

El Problema Sin HCP

Contributor: "¿Por qué no usamos async everywhere?"
Maintainer: "Explicado en issue #234... o #567... no recuerdo"
  
  → Decisión en 5 lugares diferentes
  → Contributor confundido
  → PR rechazado (frustración)

La Solución HCP

Template: Nivel 3 (Professional)

python-ml-library/
└── .procontext/
    ├── context.md
    ├── decisions/
    │   ├── 0001-pure-python-no-cython.md  # ← "Aquí está el por qué"
    │   ├── 0002-no-async-default.md
    │   └── 0003-numpy-1.x-only.md
    └── CONTRIBUTING.md  # ← Links a .procontext/

Tiempo setup: 2 horas
Tiempo ahorrado: 5-10h/mes (no re-explicas decisiones)
ROI: 20-40x

Ejemplo Real: Python ML Library

# decisions/0002-no-async-default.md

**Status**: Accepted  
**Date**: 2025-11-20

## Context
Contributors proponen hacer toda la API async.

## Decision
API stays sync by default. Async optional via `.async` suffix.

## Rationale
- ✅ 80% users: Jupyter notebooks (sync preferred)
- ✅ Complexity: sync API más simple
- ❌ Con async: Pollution de `await` everywhere

## Examples
```python
# ✅ Default (sync)
result = model.predict(data)

# ✅ Optional async
result = await model.async_predict(data)

Consequences

• Contributors: Read this before proposing async changes
• PRs making API async-only will be rejected

**Resultado**: 
- Contributor lee ADR antes de PR
- Entiende "por qué" en 3 minutos
- 0 frustración, 0 PR rechazado por malentendido

---

## Enterprise / Large Team

### Tu Situación

- 20-50+ developers
- Múltiples equipos/squads
- Compliance requirements (SOC2, GDPR, etc.)
- Audit trails necesarios

### El Problema Sin HCP

Compliance auditor: “¿Quién decidió usar X approach para PII?” Team lead: “Creo que fue en Q2… busco en Confluence…”

→ 3 horas buscando decisión → Decisión no encontrada (perdida) → Re-análisis completo (2 semanas trabajo)

### La Solución HCP

**Template**: Nivel 6 (Maximum)

enterprise-crm/ └── .procontext/ ├── spec.yml # HCP metadata ├── knowledge/ │ ├── context/ │ ├── decisions/ # ADRs con compliance tags │ └── discovery/ ├── specs/ │ ├── features/ │ └── verify/ ├── compliance/ # ← Audit trails │ ├── audit-log.jsonl │ ├── approvals/ │ └── gdpr/ └── governance/ # ← Multi-team policies ├── raci-matrix.yml └── approval-chains.yml

**Tiempo setup**: 8-16 horas (one-time)  
**Tiempo ahorrado**: 40-80h/mes (audit trails automáticos)  
**ROI**: 50-100x

### Beneficios Específicos

#### 1. Audit Log Automático

```json
// compliance/audit-log.jsonl
{"timestamp": "2026-05-02T14:30:00Z", "event": "decision", "id": "ADR-0042", "author": "john@company.com", "type": "architecture", "tags": ["pii", "gdpr"]}
{"timestamp": "2026-05-02T15:45:00Z", "event": "approval", "decision": "ADR-0042", "approver": "compliance@company.com", "status": "approved"}

Resultado: Auditor exporta logs, listo para compliance review.

2. Approval Chains

# governance/approval-chains.yml
decisions:
  architecture:
    minor: [tech_lead]
    major: [tech_lead, architect]
    critical: [tech_lead, architect, cto]
  
  pii_data:
    any: [tech_lead, dpo, legal]  # ← Data Protection Officer required

Resultado: ADR con PII no puede mergearse sin DPO approval.

Estudiante / Learning

Tu Situación

• Aprendiendo a programar
• Proyectos educativos (coursework, portfolio)
• Experimentas mucho (prueba/error)

El Problema Sin HCP

Semana 1: Proyecto React con class components
Semana 4: Vuelves al proyecto
  
  Tú: "¿Por qué usé class components? ¿Debería migrar a hooks?"
  → No recuerdas el "por qué"
  → Re-investigas (1-2 horas perdidas)

La Solución HCP

Template: Nivel 1 (Minimal)

portfolio-website/
└── .procontext/
    ├── context.md
    ├── session.md
    └── memory/
        └── learnings.md  # ← Tu "notebook" de aprendizajes

Tiempo setup: 10 minutos
Valor: Aprendizajes capturados para siempre

Ejemplo: memory/learnings.md

# Aprendizajes - Portfolio Website

## 2026-04-10: React Hooks vs Class Components

**Contexto**: Decidiendo qué usar para mi portfolio.

**Aprendido**:
- Hooks (useState, useEffect) → Modern approach
- Class components → Legacy, pero OK para aprender lifecycle

**Decisión**: Usé class components primero para entender lifecycle,
luego migré a hooks (refactor fue excelente práctica).

**Aplicación**: Próximo proyecto directo con hooks.

---

## 2026-04-15: CSS-in-JS vs Tailwind

**Contexto**: Styling approach para components.

**Probado**:
- styled-components (CSS-in-JS): Flexible pero verbose
- Tailwind: Rápido, consistente, curva aprendizaje OK

**Decisión**: Tailwind para portfolio (velocidad > flexibilidad).

**Aprendido**: Tailwind @apply para DRY en utilities.

**Aplicación**: Usar Tailwind en próximos 2-3 proyectos para dominar.

Resultado:

• En 6 meses tienes “notebook” de 30+ aprendizajes
• Portafolio para entrevistas: “Mira mi proceso de aprendizaje”
• Nunca vuelves a olvidar “por qué” decidiste X

Consultor / Agency

Tu Situación

• 5-15 proyectos cliente simultáneos
• Team de 3-10 developers rotando entre proyectos
• Contratos cortos (3-6 meses)
• Handoff constante al cliente

El Problema Sin HCP

Developer A (Enero-Febrero): Trabaja en Proyecto X
Developer B (Marzo-Abril): Continúa Proyecto X
  
  Developer B: "¿Por qué esto así? ¿Dónde está la doc?"
  Developer A: "Está en... uh... Notion? O Slack?"
  
  → 2 días onboarding (desperdicio)
  → Cliente paga por re-contextualization

La Solución HCP

Template: Nivel 3 (Professional)

cliente-fintech/
└── .procontext/
    ├── context.md              # Stack, constraints del cliente
    ├── decisions/
    │   ├── 0001-client-requested-java.md  # ← Cliente pidió Java
    │   └── 0002-aws-not-gcp.md            # ← Cliente tiene AWS
    ├── features/
    │   └── FEAT-handoff-checklist.md      # ← Para handoff final
    └── memory/
        └── client-preferences.md          # ← Business rules del cliente

Tiempo setup: 2 horas por proyecto
Tiempo ahorrado: 5-10h por handoff/rotation
ROI: 20-40x

Beneficio: Handoff Perfecto

# features/FEAT-HANDOFF-CLIENT.md

## Handoff Checklist (Final entrega a cliente)

### Código
- [x] Deployed a production
- [x] All tests passing (coverage 85%)
- [x] No secrets in repo

### Documentación
- [x] README.md actualizado
- [x] .procontext/ completo (context, decisions, learnings)
- [x] API docs generadas

### Conocimiento Transferido
- [x] ADRs explain "por qué" de decisiones críticas
- [x] memory/learnings.md tiene business rules del cliente
- [x] sessions/ contiene historial de desarrollo

### Próximos Pasos (para cliente)
- Ver .procontext/decisions/ para entender arquitectura
- Próximas features sugeridas en backlog.md

Resultado:

• Cliente recibe proyecto + “manual de operaciones”
• Próximo team del cliente onboards en 1 día (no 1 semana)
• Cliente feliz → Re-contratación fácil

Comparación Rápida

Próximos Pasos

1. Lee la guía de templates para decidir tu nivel
2. Sigue el tutorial de 10 minutos para empezar
3. Ve ejemplos reales de proyectos con HCP

HCP — Para Cada Tipo de Developer
Encuentra tu caso de uso