Introduzione a Contextia

Gli agenti AI di coding sono potenti, ma hanno una limitazione fondamentale: operano senza una conoscenza strutturata del tuo progetto. Possono leggere file, cercare nel codice e provare a indovinare le convenzioni, ma non hanno un modo affidabile per capire perché il tuo sistema è progettato in un certo modo, quali contratti ne governano il comportamento, o quali decisioni vincolano le scelte implementative.

Contextia risolve questo problema fornendo un livello di contesto strutturato e deterministico per lo sviluppo software assistito dall’AI.

Il problema: gli agenti AI non hanno memoria architetturale

Quando chiedi a un agente AI di implementare una funzionalità, si trova di fronte a un problema di avvio a freddo. Non sa:

• Quali sono i contratti comportamentali del tuo sistema (specifiche)
• Quali decisioni architetturali sono state prese e perché (decisioni)
• Quali norme di coding segue il tuo team (norme)
• Cosa richiede il task corrente e quali specifiche coinvolge (task)

La maggior parte degli approcci a questo problema si basa sulla ricerca semantica o sulle pipeline RAG — incorporando la documentazione e sperando che i frammenti giusti emergano al momento della query. Questo è probabilistico. Funziona a volte. Fallisce silenziosamente quando non funziona.

Contextia adotta un approccio diverso: l’assemblaggio deterministico del contesto. Invece di cercare il contesto rilevante, lo dichiari. Le specifiche sono collegate alle decisioni. I task sono collegati alle specifiche. Le annotazioni nel codice rimandano alle specifiche. Quando un agente inizia un task, Contextia segue questi link espliciti e assembla esattamente il contesto che quel task richiede — niente embedding, niente punteggi di similarità, niente congetture.

Cos’è Contextia

Contextia è tre cose:

1. Un’architettura dell’informazione — un modo strutturato per organizzare la conoscenza del progetto in artefatti Markdown tipizzati con frontmatter YAML
2. Uno strumento CLI (contextia) — per gli umani, per avviare, mantenere e validare quell’architettura
3. Un server MCP (contextia-mcp) — per gli agenti AI, per interrogare e navigare quell’architettura direttamente tramite il Model Context Protocol

Tutti e tre operano sulla stessa directory .contextia/ nella root del progetto. Tutto è Markdown puro, versionato insieme al codice.

Il modello a due livelli

Contextia organizza la conoscenza del progetto in due livelli con cicli di vita diversi:

Conoscenza di sistema (duratura)

La conoscenza di sistema persiste tra un task e l’altro e si evolve lentamente. Rappresenta la comprensione accumulata del progetto:

• Identità — cos’è il progetto, il suo scopo, i suoi vincoli
• Specifiche — contratti comportamentali che definiscono cosa il sistema deve fare
• Decisioni — scelte architetturali con motivazioni, vincoli e alternative considerate
• Norme — convenzioni di coding, regole di stile e accordi del team

.contextia/system/
├── identity.md
├── specs/
│   ├── SPEC-001-user-authentication.md
│   ├── SPEC-002-payment-processing.md
│   └── SPEC-003-notification-service.md
├── rationale/
│   ├── DEC-001-database-choice.md
│   └── DEC-002-api-versioning.md
└── norms/
    ├── error-handling.md
    └── testing-conventions.md

Lavoro operativo (transitorio)

Il lavoro operativo ha un ciclo di vita legato a specifici elementi di lavoro. Viene creato, eseguito e infine archiviato:

• Task — ordini di lavoro che fanno riferimento a specifiche, tracciano lo stato e accumulano log di sessione
• Piani — piani di esecuzione passo-passo generati per un task
• Log di sessione — registrazioni con timestamp di ciò che un agente ha fatto durante una sessione di lavoro
• Proposte — modifiche alle specifiche suggerite da un agente, in attesa di revisione umana

.contextia/work/
├── tasks/
│   ├── TASK-042-add-email-verification.md
│   └── TASK-043-fix-rate-limiting-bug.md
└── active/
    └── TASK-042/
        ├── plan.md
        ├── session-2026-03-01.md
        └── proposals/
            └── SPEC-001-add-email-field.md

La separazione è intenzionale. Le specifiche sopravvivono ben oltre i task che le hanno create. Una decisione presa sei mesi fa vincola ancora l’implementazione di oggi. Il modello a due livelli assicura che la conoscenza duratura non venga mai mescolata con lo stato di lavoro transitorio.

La doppia interfaccia

Contextia fornisce due interfacce sulla stessa logica core:

CLI — per gli umani

La CLI è lo strumento principale per avviare e mantenere la tua architettura del contesto. La usi per inizializzare progetti, creare nuovi artefatti, validare l’integrità dei link e ispezionare la tracciabilità:

contextia init                    # Crea la directory .contextia/
contextia new spec                # Crea una nuova specifica da template
contextia find "authentication"   # Cerca tra tutti gli artefatti
contextia check                   # Valida link, schemi, copertura
contextia trace src/auth/         # Mostra la tracciabilità completa per un percorso

La CLI produce output colorato e leggibile per impostazione predefinita, con --format json e --format context rispettivamente per il consumo macchina e LLM.

Server MCP — per gli agenti AI

Il server MCP espone le stesse funzioni core come strumenti che gli agenti AI invocano direttamente tramite il Model Context Protocol. Niente copia-incolla, niente iniezione manuale di contesto:

• find_spec — cerca specifiche per titolo, tag o percorso
• load_context — assembla il contesto completo per un task (segue tutti i link)
• read_spec — carica una specifica alla profondità scelta (meta, sommario o completa)
• write_session_log — registra le azioni dell’agente per la continuità
• propose_spec_change — prepara una modifica alla specifica per la revisione umana
• check — valida l’architettura del contesto del progetto

Il server MCP eredita la directory di lavoro dal client (Claude Code, Cursor, VS Code) e scopre automaticamente la root del progetto risalendo l’albero delle directory alla ricerca di .contextia/config.yaml — esattamente come git trova .git/.

Nota

La CLI e il server MCP condividono la stessa libreria core. Non duplicano mai la logica. La CLI formatta l’output per la visualizzazione nel terminale; il server MCP formatta l’output per il consumo da parte dell’LLM. Entrambi invocano le stesse funzioni sottostanti.

Principi chiave

Contextia è costruita su un insieme di principi di design che la distinguono da altri approcci allo sviluppo assistito dall’AI:

Deterministico rispetto al probabilistico

L’assemblaggio del contesto segue link espliciti, non punteggi di similarità. Quando esegui contextia context TASK-042, risolve i riferimenti alle specifiche del task, segue i link alle decisioni di ogni specifica, include le norme applicabili e restituisce esattamente quell’insieme. Il risultato è lo stesso ogni volta, indipendentemente dalla qualità degli embedding o dalla dimensione dei frammenti.

Markdown rispetto a formati personalizzati

Ogni artefatto è un file Markdown con frontmatter YAML. Puoi leggerli e modificarli in qualsiasi editor di testo. Si visualizzano nativamente su GitHub. Le differenze sono chiare nelle pull request. Contextia aggiunge automazione e validazione sopra un formato che già conosci — non ti vincola mai.

Link espliciti rispetto alla ricerca semantica

Un task dichiara quali specifiche implementa. Una specifica dichiara quali decisioni la vincolano. Le annotazioni nel codice dichiarano quale specifica una funzione soddisfa. Questi link sono tipizzati, direzionali e verificabili. contextia check può dirti quando un link è rotto, quando una specifica non ha codice che la implementa, o quando il codice fa riferimento a una specifica che non esiste.

Specifiche separate dai task

I contratti comportamentali (specifiche) risiedono in system/ e persistono indipendentemente dagli ordini di lavoro (task) in work/. Una specifica può essere referenziata da dozzine di task nel corso della sua vita. Questa separazione assicura che la documentazione comportamentale del sistema non venga mai persa quando un task viene archiviato.

Revisione umana delle modifiche AI

Quando un agente AI che lavora su un task scopre che una specifica ha bisogno di essere modificata, non la modifica direttamente. Invece, scrive una proposta in work/active/{task}/proposals/. Un umano rivede e promuove la modifica. Questo preserva l’autorità umana sui contratti a livello di sistema.

Consiglio

Contextia non è un sostituto della documentazione, dei sistemi di tracciamento dei problemi o degli strumenti ADR. È un ponte strutturato tra quegli artefatti umani e gli agenti AI che hanno bisogno di comprenderli. Usalo insieme al tuo workflow esistente, non al suo posto.

Come si incastra tutto

Ecco il flusso per un task tipico:

1. Uno sviluppatore crea un task (contextia new task) che fa riferimento a una o più specifiche
2. Un agente AI riceve il task e invoca load_context tramite MCP per ottenere il contesto completo: il task, le specifiche collegate, le decisioni vincolanti e le norme applicabili
3. L’agente genera un piano e inizia l’implementazione, registrando le sue azioni tramite write_session_log
4. Se l’agente scopre che una specifica ha bisogno di essere aggiornata, invoca propose_spec_change per preparare una proposta
5. Lo sviluppatore rivede le proposte, promuove le modifiche approvate ed esegue contextia check per verificare che tutto sia coerente
6. Il task viene contrassegnato come completato. Le specifiche, le decisioni e le norme persistono per il task successivo

Questo ciclo mantiene l’agente AI informato, l’umano al controllo e la conoscenza del progetto in crescita con ogni task completato.

Prossimi passi

Pronto per iniziare? Vai alla guida all’installazione per configurare Contextia, poi segui il tutorial di avvio rapido per inizializzare il tuo primo progetto.