Aider es un programador en pareja de IA basado en terminal. Lee los archivos que especificas, genera ediciones como diffs unificados y los aplica directamente a tu base de código. Cada cambio es revisable antes de integrarse. Ese flujo de trabajo diff-first se combina bien con el handoff de diseño con conciencia de tokens — puedes ver exactamente si el código generado utiliza spacing.16 del archivo de tokens o se ha desviado a un 16px codificado directamente.

Esta guía cubre el pipeline completo de Aider + figmascope: generar el bundle, cargarlo en una sesión de Aider, usar el modo Architect para el andamiaje inicial e iterar con prompts de edición específicos.

Requisitos previos

Instala Aider si aún no lo has hecho:

pip install aider-chat
# or
brew install aider

Aider admite múltiples backends de modelos. Los ejemplos aquí usan Claude Sonnet a través de la API de Anthropic, pero el flujo de trabajo es idéntico con OpenAI o modelos locales.

export ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY for GPT-4o

Paso 1: Generar el bundle

Ve a figmascope.dev, pega la URL de tu archivo Figma y haz clic en Export Agent Context. El exportador se ejecuta en tu navegador — tu token de acceso personal de Figma permanece en localStorage y nunca sale de tu máquina.

La descarga llega como context-bundle.zip.

Paso 2: Descomprimir en tu proyecto

unzip ~/Downloads/context-bundle.zip -d ./design/

ls design/
# CONTEXT.md  _meta.json  components/  screens/  strings.json  tokens.json

Paso 3: Lanzar Aider con los archivos del bundle en el ámbito

Pasa los archivos del bundle que necesitas en la línea de comandos. Aider los carga como contexto de lectura — el modelo puede referenciarlos pero no los editará a menos que uses explícitamente /add para promoverlos a archivos editables.

aider \
  --read design/CONTEXT.md \
  --read design/tokens.json \
  --read design/strings.json \
  design/screens/home.json \
  src/screens/HomeScreen.kt

El patrón: --read para archivos del bundle (solo contexto, no editables), argumentos posicionales para los archivos fuente que quieres que Aider modifique. Esto mantiene el bundle limpio — la maquinaria de diff de Aider no intentará editar tokens.json.

Si quieres que Aider cree un archivo nuevo en lugar de editar uno existente, simplemente nombra la ruta de destino que aún no existe. Aider la creará.

Paso 4: Añadir PNG de referencia

Aider puede incluir imágenes como contexto para modelos multimodales. Usa el comando /add después del lanzamiento:

/add design/screens/home.png

El PNG es un render 2× de Figma. Con un modelo multimodal (Claude Sonnet, GPT-4o), Aider lo incluye como referencia visual. Úsalo para comprobaciones de cordura durante la revisión — la especificación canónica es el JSON, no la imagen.

Paso 5: Modo Architect — andamiaje inicial

El comando /architect de Aider usa un modelo en dos pasos: un paso para planificar, otro para implementar. Este es el punto de partida correcto para una pantalla completa, donde quieres una estructura coherente antes de editar piezas individuales.

/architect Implement design/screens/home.json as a Jetpack Compose screen.

Context:
- Read CONTEXT.md for framework constraints and target conventions.
- All spacing, color, and radius values come from tokens.json.
  Map token keys directly: spacing.16 → 16.dp, color.7f5cfe → Color(0xFF7F5CFE).
- Use string keys from strings.json via stringResource() with the fallback field as the literal fallback.
- IR node kinds: stack(vertical)→Column, stack(horizontal)→Row, overlay→Box,
  absolute→Box+Modifier.offset, leaf(text)→Text, leaf(rect)→Box+Modifier.background.
- Do not hardcode any value that has a token equivalent.

Output to: src/screens/HomeScreen.kt

Aider genera primero un plan, te lo muestra, y luego produce el diff. Revisa el plan — si el mapeo de nodos parece incorrecto, corrígelo antes de que se ejecute el paso de implementación.

Paso 6: Editar archivos específicos con referencias de tokens

Una vez que el andamiaje está en su lugar, usa prompts de /edit específicos para corregir problemas concretos. Aquí es donde brilla el flujo de trabajo de diff de Aider — cada edición es un cambio pequeño y revisable en lugar de una regeneración completa.

The card component in HomeScreen.kt uses hardcoded 12dp for corner radius.
Check tokens.json for the correct radius token and replace it.

Aider produce un diff mínimo: una o dos líneas cambiadas, nada más tocado. Puedes ver exactamente qué se movió.

Para una auditoría de espaciado en todo el archivo:

Audit every .dp value in src/screens/HomeScreen.kt against the spacing tokens in design/tokens.json.
Produce a diff that replaces any hardcoded value with its token equivalent where one exists.
Leave a // TODO comment for any value that doesn't match a spacing token.

Paso 7: Revisar diffs contra la especificación

La vista de diff de Aider es la superficie de revisión. Antes de aceptar cualquier cambio, comprueba:

Si un diff parece incorrecto, recházalo con n en el prompt y dile a Aider qué corregir. El ciclo de retroalimentación corto — prompt, diff, aceptar/rechazar, refinar — significa que detectas la desviación inmediatamente en lugar de después de que llega un gran bloque de código.

Por qué el flujo de trabajo de diff de Aider se combina bien con el bundle

La desviación de tokens es visible en los diffs. Si una línea generada dice color = Color(0xFF7F5CFE) en lugar de color = tokens.colorPrimary, lo ves antes de que se fusione. No hay "compruébalo después" — la revisión ocurre en línea.

El refinamiento iterativo es barato. No estás regenerando la pantalla completa en cada cambio. Cada prompt de seguimiento produce un diff específico. El bundle proporciona el contexto estable; Aider proporciona la edición quirúrgica.

El bundle está controlado por versiones junto con el código. Cuando el diseño se actualiza, vuelve a exportar el bundle desde figmascope, compara el diff con la versión anterior y pídele a Aider que aplique solo los nodos modificados. El flujo de trabajo escala a través de múltiples iteraciones de diseño sin reimplementación completa.

Patrones comunes y errores a evitar

No añadas todas las pantallas a la vez. Pasa un JSON de pantalla a la vez. Más contexto no siempre es mejor — Aider (y el modelo subyacente) rinde mejor con contexto enfocado que con un volcado de cada pantalla del archivo.

Usa --read para el bundle, no argumentos posicionales. Si pasas tokens.json como argumento posicional, Aider podría intentar editarlo. Usa --read para marcarlo como contexto de solo lectura.

Revisa _meta.json antes del primer prompt. El array warnings lista rellenos y efectos que el exportador no pudo resolver completamente. Díselo a Aider por adelantado para que no aproxime silenciosamente:

cat design/_meta.json | python3 -c "import sys,json; w=json.load(sys.stdin).get('warnings',[]); print('\n'.join(w))"

Incluye cualquier advertencia en tu prompt de architect: "Omite el relleno del hero-background — degradado no soportado. Deja un comentario TODO."

Prefiere Aider para ediciones quirúrgicas y revisables — y usa Cursor o Claude Code cuando necesites contexto de sesión completa a través de muchos archivos. Los tres flujos de trabajo comienzan de la misma manera: la app principal de figmascope gestiona la exportación en tu navegador.