Documenti di contesto

I Documenti di contesto sono artefatti di conoscenza riutilizzabili che vengono versionati e iniettati automaticamente nelle sandbox come system prompt o come contenuto CLAUDE.md. Invece di incorporare la stessa panoramica architetturale o gli stessi standard di coding nelle istruzioni di ogni persona, la scrivi una volta come Contesto, la pubblichi e la colleghi ai session type o alle persona che ne hanno bisogno. Ogni volta che viene provisionata una sandbox corrispondente, la versione attiva di quel Contesto viene iniettata automaticamente.

I Contesti si trovano in /p/{projectId}/context e sono limitati a un singolo progetto. Un progetto può avere un numero qualsiasi di Contesti, ciascuno che copre un dominio di conoscenza diverso - uno per le convenzioni architetturali, uno per la documentazione API, uno per le regole di sicurezza.

Cosa sono i Contesti

Fondamentalmente un Contesto è un documento markdown denominato e versionato. Ogni record di Contesto memorizza:

• Nome - Un’etichetta leggibile (ad es., “Architettura del progetto”, “Standard di sicurezza”)
• Descrizione - Un riepilogo opzionale di cosa copre il Contesto e quando usarlo
• Contenuto - Il corpo markdown completo iniettato nelle sandbox
• Cronologia delle versioni - Una traccia di audit completa di ogni versione pubblicata

I Contesti sono progettati per il tipo di conoscenza persistente, a livello di progetto, che ogni agente di un dato tipo dovrebbe portare con sé. Alcuni esempi:

• Panoramiche architetturali complete che descrivono lo stack tecnologico, i confini dei servizi e il flusso dei dati
• Standard di coding e style guide che gli agenti devono seguire quando scrivono codice
• Contenuto CLAUDE.md che viene scritto nel filesystem della sandbox prima che l’agente venga eseguito
• Documentazione API specifica di dominio o pattern di integrazione che gli agenti devono consultare
• Checklist di sicurezza e requisiti di conformità per gli agenti che eseguono code review

Ciclo di vita delle versioni di Contesto

Ogni volta che modifichi il contenuto di un Contesto e pubblichi la modifica, viene creata una nuova versione. Le versioni hanno due stati:

Il ciclo di vita di una tipica modifica a un Contesto è:

1. Apri l’editor del Contesto e modifichi il contenuto markdown
2. Clicchi su Pubblica - questo crea una nuova versione con stato active
3. La versione precedentemente attiva viene impostata automaticamente su inactive
4. Tutte le future sandbox che referenziano questo Contesto ricevono la nuova versione attiva
5. La vecchia versione rimane nella cronologia delle versioni per scopi di audit e rollback

Binding ai Session Type

I Contesti possono essere collegati a session type specifici dalla pagina delle impostazioni del progetto. Quando viene creata una sessione di quel tipo, la versione attiva del Contesto collegato viene iniettata automaticamente. CodeCourier definisce sei session type, ciascuno corrispondente a una fase diversa della pipeline di workflow IA:

Ogni session type ha il proprio tab di setup nelle impostazioni del progetto dove puoi collegare esattamente un Contesto. Questo rende facile dare, ad esempio, all’agente evaluator un insieme di criteri di qualità diverso rispetto all’agente di scoperta issue.

Override di Contesto a livello persona

Oltre ai binding a livello di session type, singole persona possono collegarsi a un Contesto specifico dal proprio tab Contesto nella pagina di dettaglio della persona. Un binding a livello persona ha la precedenza sul default del session type - il che significa che quando una persona con un proprio binding di Contesto viene eseguita, usa il Contesto della persona invece del default del session type.

Questo meccanismo di override abilita un controllo granulare. Considera un progetto con due persona Designer - una per il lavoro frontend e una per il lavoro backend. Il Designer frontend è collegato a un Contesto “Architettura Frontend”, mentre il Designer backend è collegato a un Contesto “Architettura Backend”. Entrambi ereditano il default del session type come fallback se non è impostato alcun binding a livello persona.

Perché i Contesti sono importanti

Prima dei Contesti, i team dovevano copiare e incollare la conoscenza architetturale nelle istruzioni di ogni persona o mantenere file CLAUDE.md separati per workflow. Questo creava drift: agenti diversi avevano una comprensione sottilmente diversa della codebase perché le loro istruzioni venivano modificate in modo indipendente. I Contesti risolvono questo problema fornendo un’unica fonte di verità condivisa da tutti gli agenti rilevanti.

I vantaggi principali sono:

• Coerenza- Tutti gli agenti di un session type condividono la stessa conoscenza aggiornata. Quando l’architettura cambia, aggiorni un Contesto e tutte le future sessioni ricevono immediatamente la modifica.
• Controllo di versione - Le istruzioni degli agenti vengono versionate come il codice. Puoi vedere chi ha pubblicato quale versione, quando, e tornare a una versione precedente se una modifica causa regressioni.
• Separazione delle responsabilità - Le istruzioni di persona restano focalizzate sul comportamento specifico del ruolo. La conoscenza condivisa vive nei Contesti. Ognuno ha una collocazione chiara.
• Auditabilità - Quando un agente produce un output inatteso, puoi controllare la cronologia delle versioni per vedere esattamente quale versione del Contesto era attiva al momento di quella sessione.

Prossimi passi