Aider è un programmatore AI in coppia basato su terminale. Legge i file specificati, genera modifiche come diff unificati e le applica direttamente alla tua codebase. Ogni modifica è revisionabile prima di essere applicata. Quel flusso di lavoro diff-first si abbina bene alla consegna design consapevole dei token — puoi vedere esattamente se il codice generato usa spacing.16 dal file token o è derivato verso un 16px hardcodato.

Questa guida copre l'intera pipeline Aider + figmascope: generare il bundle, caricarlo in una sessione Aider, usare la modalità Architect per il primo scaffold e iterare con prompt di modifica mirati.

Prerequisiti

Installa Aider se non lo hai ancora:

pip install aider-chat
# oppure
brew install aider

Aider supporta più backend di modelli. Gli esempi qui usano Claude Sonnet via API Anthropic, ma il flusso di lavoro è identico con OpenAI o modelli locali.

export ANTHROPIC_API_KEY=sk-ant-...
# oppure OPENAI_API_KEY per GPT-4o

Passo 1: Genera il bundle

Vai su figmascope.dev, incolla l'URL del tuo file Figma e clicca su Export Agent Context. L'esportatore gira nel tuo browser — il tuo personal access token di Figma rimane in localStorage e non lascia mai il tuo computer.

Il download arriva come context-bundle.zip.

Passo 2: Decomprimi nel progetto

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

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

Passo 3: Avvia Aider con i file bundle nell'ambito

Passa i file bundle necessari dalla riga di comando. Aider li carica come contesto di lettura — il modello può farvi riferimento ma non li modificherà a meno che tu non usi esplicitamente /add per promuoverli a file modificabili.

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

Il pattern: --read per i file bundle (solo contesto, non modificabili), argomenti posizionali per i file sorgente che vuoi che Aider modifichi. Questo mantiene il bundle pulito — il meccanismo di diff di Aider non tenterà di modificare tokens.json.

Se vuoi che Aider crei un nuovo file anziché modificarne uno esistente, nomina semplicemente il percorso target che non esiste ancora. Aider lo creerà.

Passo 4: Aggiungi PNG di riferimento

Aider può includere immagini come contesto per modelli multimodali. Usa il comando /add dopo il lancio:

/add design/screens/home.png

Il PNG è un render 2× da Figma. Con un modello multimodale (Claude Sonnet, GPT-4o), Aider lo include come riferimento visivo. Usalo per controlli di sanità durante la revisione — la specifica canonica è il JSON, non l'immagine.

Passo 5: Modalità Architect — scaffold iniziale

Il comando /architect di Aider usa un modello a due fasi: un passaggio per pianificare, uno per implementare. Questo è il punto di partenza giusto per una schermata completa, dove vuoi una struttura coerente prima di modificare singole parti.

/architect Implementa design/screens/home.json come schermata Jetpack Compose.

Contesto:
- Leggi CONTEXT.md per i vincoli del framework e le convenzioni target.
- Tutti i valori di spaziatura, colore e raggio provengono da tokens.json.
  Mappa le chiavi token direttamente: spacing.16 → 16.dp, color.7f5cfe → Color(0xFF7F5CFE).
- Usa le chiavi stringa da strings.json via stringResource() con il campo fallback come fallback letterale.
- Tipi di nodi IR: stack(vertical)→Column, stack(horizontal)→Row, overlay→Box,
  absolute→Box+Modifier.offset, leaf(text)→Text, leaf(rect)→Box+Modifier.background.
- Non hardcodare alcun valore che abbia un equivalente token.

Output in: src/screens/HomeScreen.kt

Aider genera prima un piano, lo mostra, poi produce il diff. Rivedi il piano — se la mappatura dei nodi sembra sbagliata, correggila prima che venga eseguito il passaggio di implementazione.

Passo 6: Modifica file specifici con riferimenti ai token

Dopo che lo scaffold è pronto, usa prompt /edit mirati per risolvere problemi specifici. Qui brilla il flusso diff di Aider — ogni modifica è un cambiamento piccolo e revisionabile anziché una rigenerazione completa.

Il componente card in HomeScreen.kt usa 12dp hardcodato per il raggio degli angoli.
Controlla tokens.json per il token raggio corretto e sostituiscilo.

Aider produce un diff minimale: una o due righe cambiate, nient'altro toccato. Puoi vedere esattamente cosa è cambiato.

Per un audit della spaziatura sull'intero file:

Verifica ogni valore .dp in src/screens/HomeScreen.kt rispetto ai token di spaziatura in design/tokens.json.
Produci un diff che sostituisce ogni valore hardcodato con il suo equivalente token dove esiste.
Lascia un commento // TODO per qualsiasi valore che non corrisponda a un token di spaziatura.

Passo 7: Rivedi i diff rispetto alla specifica

La vista diff di Aider è la superficie di revisione. Prima di accettare qualsiasi modifica, verifica:

Se un diff sembra sbagliato, rifiutalo con n al prompt e di' ad Aider cosa correggere. Il ciclo di feedback breve — prompt, diff, accetta/rifiuta, raffina — significa che intercetti la deriva immediatamente anziché dopo che un grande blocco di codice è arrivato.

Perché il flusso diff di Aider si abbina bene al bundle

La deriva dei token è visibile nei diff. Se una riga generata dice color = Color(0xFF7F5CFE) invece di color = tokens.colorPrimary, lo vedi prima che venga unita. Non c'è "verificalo dopo" — la revisione avviene inline.

Il raffinamento iterativo è economico. Non stai rigenerando l'intera schermata ad ogni modifica. Ogni prompt successivo produce un diff mirato. Il bundle fornisce il contesto stabile; Aider fornisce la modifica chirurgica.

Il bundle è versionato insieme al codice. Quando il design si aggiorna, riesporta il bundle da figmascope, calcola il diff rispetto alla versione precedente e chiedi ad Aider di applicare solo i nodi modificati. Il flusso di lavoro scala su più iterazioni di design senza una reimplementazione completa.

Pattern comuni e insidie

Non aggiungere tutte le schermate insieme. Passa un JSON schermata alla volta. Più contesto non è sempre meglio — Aider (e il modello sottostante) performa meglio con contesto focalizzato che con un dump di ogni schermata del file.

Usa --read per il bundle, non argomenti posizionali. Se passi tokens.json come argomento posizionale, Aider potrebbe provare a modificarlo. Usa --read per marcarlo come contesto di sola lettura.

Controlla _meta.json prima del primo prompt. L'array warnings elenca riempimenti ed effetti che l'esportatore non è riuscito a risolvere completamente. Di' ad Aider di essi in anticipo così non approssima silenziosamente:

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

Includi eventuali avvisi nel prompt architect: "Salta il riempimento hero-background — gradiente non supportato. Lascia un commento TODO."

Preferisci Aider per modifiche chirurgiche e revisionabili — e usa Cursor o Claude Code quando hai bisogno di contesto su intera sessione su molti file. Tutti e tre i flussi di lavoro iniziano allo stesso modo: l'app figmascope principale gestisce l'esportazione nel tuo browser.