Context-First Development · CFD
Tu agente de IA tiene amnesia al empezar cada sesión. CFD es la cura.
Una metodología para ingenieros que trabajan con agentes de IA (Claude Code, Gemini CLI, Codex, Cursor, Aider) sobre repos reales. Trata el contexto como un artefacto de primera clase: estructurado, versionado y revisado como el código.
o adopta CFD en 60 segundos ↓El problema
Los modelos reinician cada sesión sin memoria de tus decisiones arquitectónicas. La consecuencia es que corriges más código generado por IA del que ahorrarías escribiéndolo a mano — porque no conoce el «porqué» que el código por sí solo no expresa.
El problema no es la capacidad de contexto — es la calidad del contexto.
El beneficio real
Adherencia, no tokens.
Casi todo el mundo vende ahorro de tokens. CFD apunta a algo más difícil de refutar: código que respeta tus convenciones al primer intento, decisiones que no se vuelven a litigar, correcciones que no se repiten. El ahorro de tokens es un efecto secundario bienvenido, no el titular.
Seis principios
Context Before Code
El contexto se resuelve al empezar la sesión, no sobre la marcha.
Single Source of Truth
Cada hecho vive en exactamente un archivo; todo lo demás lo referencia.
Hierarchical Context
CLAUDE.md es un índice (~100 líneas), no una enciclopedia.
Decisions as First-Class Citizens
Cada decisión relevante se convierte en un ADR con alternativas y motivo.
English as Context Language
Los tokenizadores comprimen el inglés ~20–40% mejor. Aplica al contexto que come la IA — no a lo que publicas.
Automation Through Slash Commands
Mantener el contexto es un comando, no una tarea que hay que recordar.
No es documentación — es mecanismo
La disciplina se hace cumplir sola.
Lo que separa a CFD de «escribe buenos docs y ya» es que el contexto se aplica por mecanismo, no por buena voluntad:
Inyecta el contexto automáticamente al arrancar y avisa si está obsoleto.
Bloquea commits que suben código sin actualizar CURRENT_STATUS.md.
Marca los PRs que cambian código sin tocar el estado del proyecto.
Medido, no afirmado
Números reproducibles.
tokens para orientar una sesión con CFD
tokens escaneando todo el repo sin CFD
menos contexto para arrancar
frescura de CURRENT_STATUS.md
Medido con un script reproducible sobre examples/node-express en el repo.
Automatización
Slash commands canónicos
/project:initBootstrapea el scaffold CFD en un repo nuevo./session:startCarga CLAUDE.md + CURRENT_STATUS.md + índice de decisiones./issue:newCrea un issue con plantilla fija y ADRs a precargar./issue:startArranca el trabajo con el contexto de la decisión ya cargado./session:closeAsegura que CURRENT_STATUS.md viaja junto al código.
- 1. /session:start — inicia sesión. Carga CLAUDE.md + CURRENT_STATUS.md + el índice de decisiones. El agente arranca orientado, sin escanear el repo. ✓ CLAUDE.md — índice (98 líneas). ✓ CURRENT_STATUS.md. ✓ decisions/_index.md — 11 ADRs. → ~824 tokens para orientarse
- 2. /issue:new — nuevo issue. Crea el issue con una plantilla fija y marca qué ADRs precargar antes de tocar una sola línea de código. Context · Target · ADRs to load. Acceptance criteria. Estimated sessions: 1. ✓ issue #42 creado
- 3. /issue:start — empieza issue. Arranca el trabajo con el contexto de la decisión ya cargado. Cero re-explicar la arquitectura. ↑ ADR-004, ADR-007 cargados. ↑ CONVENTIONS.md. ▶ listo para implementar
- 4. /review:pr — review del PR. Un agente independiente revisa el diff contra las convenciones y los ADRs, y devuelve un reporte de hallazgos con evidencia — no opiniones. ⚠ 3 hallazgos. • N+1 en getUser(). • null-check faltante en parse(). • no referencia ADR-005
- 5. corrige los hallazgos — corrige hallazgos. Le devuelves el reporte al agente. Con el contexto y los ADRs ya cargados, corrige cada hallazgo sin re-litigar decisiones. ✓ query N+1 → batch load. ✓ null-check añadido. ✓ ADR-005 referenciado. → 3/3 resueltos
- 6. /session:close — cierra sesión. Al cerrar, CURRENT_STATUS.md viaja junto al código en el mismo commit. El PR lleva el porqué, no solo el qué. ✓ CURRENT_STATUS.md actualizado. ✓ docs/ + código en 1 commit. → listo para mergear
Empieza
Adopta CFD en 60 segundos.
Clona las plantillas sobre tu repo, edita CLAUDE.md con la descripción de tu proyecto y arranca tu primera sesión.
git clone https://github.com/albertomarturelo/context-first-development.git /tmp/cfd
cp -r /tmp/cfd/templates/. .
# Edita CLAUDE.md con tu proyecto, luego:
> /session:start¿Sin ganas de clonar? El repo incluye un prompt de bootstrap zero-install: lo pegas en tu agente y genera el scaffold e incrusta las reglas en CLAUDE.md para que las sesiones futuras hereden el flujo.
Encaje
¿Para quién es?
- →Solo devs en repos no triviales (más de 100 archivos).
- →Equipos de 2 a 20 adoptando agentes en producción.
- →Tech leads evaluando desarrollo asistido por IA a escala.
No es para: scripts rápidos, código desechable o flujos de «vibe coding».
Contexto primero. Código después.
Open source, multi-modelo y sin dependencia de proveedor. Es Markdown plano: funciona igual con Claude Code, Gemini CLI, Codex, Cursor o Aider.