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, Codex, GitHub Copilot, Gemini CLI, Cursor) sobre repos reales. Trata el contexto como un artefacto de primera clase: estructurado, versionado y revisado como el código.
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, sino su calidad.
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, antes del código.
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 Agent Skills
Mantener el contexto es un procedimiento que cualquier agente ejecuta, no una tarea que hay que recordar.
Un issue real
El cuerpo del issue es la spec.
Cada unidad de trabajo vive en el tracker con cinco secciones fijas. La sesión arranca leyendo eso, no reconstruyéndolo del código. Este es el #116 de sii, un CLI y servidor MCP para el SII de Chile que nació con CFD el día 0 y lleva 26 ADRs.
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.
Falla el PR si dos ADRs comparten slug y avisa si el código cambia sin tocar el estado. Llega a cualquier agente, incluido uno que no configuraste.
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 scripts/measure-session-cost.sh sobre el ejemplo node-express que el repo incluyó hasta julio de 2026. Corre el mismo script sobre tu repo.
Automatización
Los procedimientos son Agent Skills.
Una sola copia en .agents/skills/, el formato abierto que leen Claude Code, Codex, GitHub Copilot y Gemini CLI. Los rituales de sesión solo se ejecutan cuando tú los invocas, nunca por criterio del modelo.
/project-initBootstrapea el scaffold CFD en un repo existente./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./review-prRevisa el diff contra los AC, las convenciones y los ADRs. Antes de cerrar./session-closeAsegura que CURRENT_STATUS.md viaja junto al código.
En Codex se invocan como $session-start. Instálalos en todos tus agentes con npx skills add albertomarturelo/context-first-development.
CFD en tu setup
Los archivos y el loop son los mismos. Cambia dónde vive el estado y quién decide.
Encuentra tu caso. Se acumulan: un equipo con Codex y Claude en worktrees lee los cuatro.
Caso 1
Un desarrollador, un repo
- →Un issue por sesión. /issue-new obliga a descomponer hasta que quepa en una.
- →Lo que corriges va a CONVENTIONS.md; lo que decides se vuelve ADR antes del código. El agente nunca oye la misma corrección dos veces.
- →Revisa tu propio diff antes de cerrar, con el contexto aún cargado. Revisar después de cerrar es pagar una sesión nueva para reconstruirlo.
Caso 2
Un equipo en un repo
- →El estado se vuelve personal: CURRENT_STATUS.md sale de git. Compartido, choca en cada PR y te inyecta el trabajo a medias de todos.
- →El tracker es la foto compartida: asignados y estado del issue responden «quién hace qué».
- →Si revisa un compañero, el orden se invierte: cierras, y sus hallazgos abren tu siguiente sesión.
Caso 3
Loops paralelos en git worktrees
- →Un worktree aísla archivos, no decisiones. Lo que está en main al ramificar es compartido; lo que se decide dentro de un worktree es invisible para los demás hasta el merge.
- →Por eso se decide antes, y se para cuando aparece una decisión nueva. Rutas objetivo disjuntas; un ADR a medio camino aterriza en main como su propio PR y los demás hacen rebase.
- →Tú eres el cuello de botella a propósito: cada merge se revisa contra el main actual. Tantos loops como puedas revisar, normalmente dos o tres.
Caso 4
Varios agentes, una fuente
- →Nada que traducir. El índice y los procedimientos existen una vez; los symlinks le dan a cada agente la ruta que busca.
- →La CI es la garantía: los hooks ayudan dentro de Claude Code, pero los checks de CI sujetan el PR de cualquier agente a las mismas reglas.
Lo que cuesta, sin adornos
Es una disciplina, no una herramienta que trabaja mientras miras para otro lado.
- →Unos minutos por sesión en los rituales de inicio y cierre, y media hora para arrancar un repo existente.
- →Las decisiones se escriben antes del código. La primera semana se siente más lenta; la ganancia es la siguiente, cuando nada se vuelve a explicar.
- →Solo funciona si los docs siguen siendo verdad. Un ADR obsoleto engaña al agente con toda la confianza del mundo. Los hooks y la CI existen para evitarlo, pero alguien tiene que ejecutar el ritual.
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
# o instala solo los skills en todos tus agentes:
npx skills add albertomarturelo/context-first-development¿Sin ganas de clonar? El repo incluye un prompt de bootstrap zero-install: lo pegas en tu agente, genera el scaffold e incrusta las reglas en CLAUDE.md para que las sesiones futuras hereden el flujo completo.
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, Codex, GitHub Copilot, Gemini CLI o Cursor.
Código MIT · Prosa CC-BY-SA 4.0