Cómo Trabajo y Cómo Creo Documentación de Contexto para la IA - 05/03/2026

Un hábito que ha transformado genuinamente la forma en que trabajo con herramientas de IA es escribir un archivo CONTEXT.md al inicio de cada proyecto. Toma unos 30 minutos al principio, pero rinde beneficios cada día. En lugar de re-explicar el stack del proyecto, las convenciones de estilo o el proceso de despliegue en cada conversación, apunto la IA al archivo—y las sugerencias que obtengo de vuelta son inmediatamente útiles. En este artículo quiero mostrarte cómo luce ese archivo, por qué funciona y cómo puedes adoptar la práctica en tu propio flujo de trabajo.

¿Qué Es un CONTEXT.md?

Un CONTEXT.md es un archivo markdown de texto plano que vive en la raíz de un repositorio. Su único propósito es darle a cualquier asistente de IA—o a un nuevo integrante del equipo, también—una instantánea confiable y actualizada del proyecto. Piénsalo como un README ligero enfocado en el cómo se hace el trabajo más que en el qué es el proyecto.

El archivo cubre cuatro áreas:

1. Resumen del proyecto — propósito, alcance actual y restricciones clave.
2. Decisiones técnicas — lenguaje, framework, patrones de arquitectura y el por qué detrás de cada uno.
3. Convenciones de código y estilo — nomenclatura, estructura de carpetas, reglas de linting, formato de mensajes de commit.
4. Flujo de trabajo — estrategia de ramas, proceso de revisión de PRs, pipeline de despliegue, gestión de secretos.

No es información nueva que tengas que inventar. Es el conocimiento que ya vive en tu cabeza o disperso en READMEs, páginas de wiki e hilos de Slack. Escribirlo en un solo lugar simplemente lo hace accesible.

Un Ejemplo Real

A continuación el CONTEXT.md que uso para Keppli Finance, una app de finanzas personales que estoy construyendo con Flutter y NestJS:

# Keppli Finance — Contexto para IA

## Resumen del Proyecto
Keppli Finance es una app de finanzas personales mobile-first que ayuda
a los usuarios a rastrear ingresos, gastos y metas de ahorro. La audiencia
objetivo son personas en Latinoamérica con acceso limitado a servicios
financieros tradicionales.

Enfoque actual: lanzamiento del MVP para Android e iOS.

## Stack Tecnológico
- **Mobile**: Flutter 3.x (Dart)
- **Backend**: NestJS + TypeScript
- **Base de datos**: PostgreSQL vía Supabase
- **Auth**: Supabase Auth (email + Google OAuth)
- **Storage**: Supabase Storage (recibos, imágenes de perfil)
- **Analytics**: PostHog + Sentry

## Decisiones de Arquitectura
- **Offline-first**: Todas las escrituras van primero a SharedPreferences;
  un servicio en segundo plano sincroniza con Supabase cuando se restaura
  la conectividad.
- **Patrón Repository**: El acceso a datos está abstraído detrás de clases
  repository para que la capa de UI nunca importe Supabase directamente.
- **Carpetas por feature**: El código está organizado por funcionalidad,
  no por tipo (`features/transactions/`, `features/goals/`, etc.).

## Convenciones de Código
- Dart: `snake_case` para archivos, `UpperCamelCase` para clases,
  `lowerCamelCase` para variables.
- TypeScript: ESLint + Prettier, comillas simples, sin punto y coma.
- Mensajes de commit: Conventional Commits (`feat:`, `fix:`, `chore:`, etc.).
- Los títulos de PR deben seguir el mismo formato de Conventional Commits.

## Flujo de Trabajo
- Rama principal: `main` (protegida, requiere 1 revisión + CI en verde).
- Ramas de feature: `feat/<descripción-corta>`.
- Los releases se etiquetan como `v<mayor>.<menor>.<parche>`.
- CI: GitHub Actions ejecuta lint, pruebas y build en cada PR.
- Despliegues: Vercel para el sitio de marketing; builds móviles con
  Codemagic.

Cuando pego esto en un chat o lo adjunto a un workspace de Copilot, la IA conoce inmediatamente el stack, los patrones en uso y el estilo que espero. No más sugerencias de usar Prisma en un proyecto que usa Supabase, ni código que ignore la restricción offline-first.

Cómo Lo Mantengo Actualizado

El mayor riesgo con cualquier documentación es que se aleje de la realidad. Mi regla es simple: actualiza el CONTEXT.md en el mismo commit que introduce un cambio significativo. Si cambio una librería, modifico la estrategia de ramas o agrego un nuevo servicio, el parche al CONTEXT.md es parte de ese mismo PR. Esto mantiene el archivo confiable.

También hago una revisión trimestral—usualmente al inicio de cada trimestre—donde leo el archivo de principio a fin y me pregunto si cada afirmación sigue siendo precisa. Raramente toma más de 15 minutos, y consistentemente aflora pequeñas inconsistencias que se han colado.

Beneficios que He Notado

Desde que empecé a usar esta práctica, varias cosas han cambiado notablemente:

Sugerencias de IA más Relevantes

Cuando la IA sabe que uso el patrón repository y carpetas por feature, estructura sus sugerencias de código en consecuencia. Paso mucho menos tiempo traduciendo mentalmente una respuesta “genérica” a algo que encaja en mi base de código.

Onboarding más Rápido

Cuando un colaborador se une a un proyecto, lo primero que le envío es el CONTEXT.md. Responde la mayoría de las preguntas “¿cómo hacen X aquí?” antes de que sean formuladas, lo que libera nuestra primera llamada para problemas reales.

Una Función de Claridad Forzada

Escribir el archivo me obliga a articular decisiones que he estado tomando inconscientemente. “¿Por qué estamos usando el patrón repository?” es una pregunta que tengo que responder por escrito. Ese proceso aflora supuestos que vale la pena examinar.

Estilo Consistente entre Sesiones

Los asistentes de IA no retienen memoria entre sesiones por defecto. El CONTEXT.md restaura esa memoria al instante. El resultado es que el código generado en la sesión 47 parece pertenecer junto al código generado en la sesión 3.

La Estructura que Recomiendo

Aquí hay una plantilla que puedes copiar y adaptar:

# <Nombre del Proyecto> — Contexto para IA

## Resumen del Proyecto
<Un párrafo: propósito, audiencia, alcance actual.>

## Stack Tecnológico
<Lista de lenguajes, frameworks, servicios y herramientas.>

## Decisiones de Arquitectura
<Patrones clave y las razones detrás de ellos.>

## Convenciones de Código
<Reglas de nomenclatura, estructura de archivos, config de linting,
formato de commits.>

## Flujo de Trabajo
<Ramas, proceso de PRs, pipeline de CI/CD, destinos de despliegue.>

## Fuera del Alcance
<Cosas que la IA no debe sugerir ni cambiar.>

La sección “Fuera del Alcance” se pasa por alto con frecuencia pero es sumamente útil. Es el lugar donde escribes cosas como “no migrar fuera de Supabase” o “no agregar componentes de clase—este proyecto usa solo componentes funcionales”. Previene que la IA sugiera con confianza una refactorización que no tienes intención de hacer.

Reflexiones Finales

El CONTEXT.md es una de esas prácticas que se sienten casi demasiado simples para funcionar—pero funcionan. Hace que las herramientas de IA sean genuinamente más útiles porque operan con el mismo entendimiento compartido que llevas en tu cabeza. Hace que el onboarding sea más fluido porque los nuevos integrantes tienen una referencia escrita en lugar de tener que descifrar la base de código leyéndola. Y hace tu propio pensamiento más claro porque tienes que escribir lo que realmente crees sobre el proyecto.

Si te llevas una sola cosa de este artículo: elige un proyecto en el que trabajas regularmente, crea un CONTEXT.md hoy, y úsalo en tu próxima sesión de IA. La diferencia en la calidad de las respuestas será inmediata.

Gracias por leer. Espero que esto te ayude a sacar más provecho de las herramientas de IA que ya usas cada día.