Core Concepts

CodeCourier è costruito attorno a un piccolo insieme di concetti interconnessi. Capire come si relazionano tra loro è la chiave per usare la piattaforma in modo efficace. Questa pagina spiega ogni concetto, il suo ruolo nel sistema e come si collega a tutto il resto.

Progetti

Un progetto è l’unità organizzativa di livello più alto in CodeCourier. Ogni altra risorsa - sandbox, workflow, run, personas, contesti, asset, piani, issue, learning, task ricorrenti, sprint chain, membri del team e chiavi API - appartiene a esattamente un progetto.

Ogni progetto ha uno slug univoco che appare in tutti gli URL (ad es., /p/my-app/dashboard), un owner e metadati opzionali come un URL di repository GitHub e un logo di progetto. I progetti possono essere collegati a un repository GitHub, il che abilita la creazione automatica dei branch e la generazione di pull request dai run di workflow.

Impostazioni del progetto

Le impostazioni del progetto controllano i comportamenti predefiniti sull’intero progetto:

• System prompt della sandbox - Un’istruzione predefinita aggiunta a ogni sessione di sandbox del progetto
• Contenuto CLAUDE.md - Markdown scritto nella sandbox come file CLAUDE.md per gli strumenti CLI che lo supportano
• Configurazioni per tipo di sessione - Ogni tipo di sessione (learning, merging, issue, answering, evaluator, judge) ha la propria pagina di configurazione dedicata dove puoi legare un contesto, selezionare skill, command e script e impostare altri valori predefiniti a livello di sessione
• Variabili d’ambiente - Coppie chiave-valore iniettate negli ambienti di sandbox, con il supporto per marcare i valori sensibili come secret
• Configurazione Git - Nome ed e-mail dell’autore dei commit personalizzati per i commit generati dall’agente
• Impostazioni di learning e merging - Configura quale modello IA e quale template usare per l’estrazione dei learning e il merge dei branch

Ruoli del team

I progetti supportano tre ruoli:

• Owner - Accesso completo, inclusa l’eliminazione del progetto e la gestione dei membri
• Admin - Può gestire impostazioni, membri e tutte le risorse del progetto
• Member - Può creare e gestire le proprie risorse (sandbox, run, workflow) all’interno del progetto

I membri vengono invitati via e-mail e devono accettare l’invito prima di ottenere l’accesso. Ogni membro può configurare le proprie chiavi API, usate per il provisioning delle sandbox.

Sandbox

Una sandbox è una macchina virtuale Linux isolata fornita tramite E2B. Le sandbox sono l’ambiente di esecuzione in cui girano gli agenti di coding IA. Ogni sandbox è un sistema Linux completo con il proprio filesystem, il proprio stack di rete e il proprio spazio di processi.

Configurazione della sandbox

Ogni sandbox viene creata con un oggetto di configurazione che definisce:

• Template ID - Determina l’immagine di base e gli strumenti preinstallati. Template diversi supportano strumenti CLI diversi (Claude Code, OpenCode, Codex, Pi, ecc.)
• Timeout - Per quanto tempo la sandbox può girare prima della terminazione automatica, da 1 minuto a 4 ore
• Memoria- RAM allocata da 256 MB a 8 GB
• Numero di CPU - Numero di core CPU da 1 a 8
• Override di modello - Specifica modelli IA diversi per gli step di designer e checker
• Thinking effort - Livelli di thinking effort per modello (ad es., high, medium, low) che controllano quanto ragionamento il modello esegue prima di rispondere

Ciclo di vita della sandbox

Le sandbox progrediscono attraverso questi stati:

• Creating - L’API E2B sta fornendo la VM
• Running - La sandbox è attiva e l’agente è in esecuzione
• Paused - La sandbox è stata sospesa ma può essere ripresa
• Killed - La sandbox è stata terminata (per timeout, per azione dell’utente o al completamento)
• Error - La sandbox ha incontrato un errore fatale durante il provisioning o l’esecuzione

Workflow

Un workflow è un blueprint riutilizzabile che definisce come gli agenti IA devono elaborare un task. I workflow specificano il tipo di pipeline, la configurazione di sandbox predefinita e le istruzioni a livello di step.

Tipi di workflow

Single Designer

Il tipo più semplice. Un singolo agente riceve il prompt e lo esegue in un’unica passata. Ideale per task diretti dove non serve una review.

Designer & Checker

Il tipo più comune. Un designer agent scrive codice a partire dal prompt, poi un checker agent revisiona l’output rispetto a istruzioni configurabili. Se il checker rifiuta (il suo verdetto ha pass: false), il designer riceve il feedback e itera. Questo ciclo continua finché il checker non approva o non viene raggiunto il numero massimo di iterazioni.

Custom Pipeline

Definisci una sequenza arbitraria di tipi di step: designer, checker, optimizer, prompter, investigator, deep-dive, evaluator o judge. Ogni step può, in via opzionale, specificare il proprio strumento CLI, modello, thinking effort e istruzioni. Gli step possono essere raggruppati in loop con un numero massimo di iterazioni configurabile.

Persona Pipeline

Concatena personas denominate in una pipeline sequenziale. Ogni step referenzia una persona tramite il suo ID ed eredita la configurazione completa di quella persona. È il tipo più flessibile, che ti permette di comporre workflow multi-agente complessi a partire da definizioni di personas riutilizzabili.

Run

Un run è una singola esecuzione di un workflow (o una sessione di sandbox autonoma). I run memorizzano il prompt, la configurazione, lo stato, le informazioni sul branch GitHub, i dettagli della PR, il tracciamento dei costi, il punteggio di qualità, lo stato dei check CI e i riferimenti al workflow e al progetto a cui appartengono.

Ogni run contiene uno o più run step. Un run step rappresenta una singola invocazione di agente - una passata di designer, una review di checker, una valutazione di evaluator, ecc. Gli step tracciano il loro ruolo (designer, checker, optimizer, prompter, investigator, deep-dive, evaluator, judge o merge_agent), lo stato, la durata, la sandbox usata, i verdetti del checker e i punteggi di qualità individuali.

Personas

Una persona è una configurazione di agente IA riutilizzabile limitata a un progetto. Le personas ti permettono di definire comportamenti di agente standardizzati che possono essere referenziati attraverso i workflow e gli step di pipeline.

Ogni persona include:

• Tipo - Il ruolo che la persona ricopre. L’insieme completo dei tipi di persona è:
  • designer - Implementa feature e fix
  • checker - Revisiona e valida l’output
  • optimizer - Rifattorizza e migliora il codice esistente
  • prompter - Genera o affina i prompt per gli agenti a valle
  • investigator - Esplora le codebase e fa ricerca prima di apportare modifiche
  • planner - Produce piani strutturati e liste di issue
  • deep-dive - Esegue un’analisi approfondita con ragionamento esteso
  • reviewer - Si concentra su code review, leggibilità e manutenibilità
  • custom - Tipo senza vincoli per casi d’uso specializzati
• Strumento CLI - Quale client CLI usare nella sandbox (identificato da una stringa di ID strumento)
• Modello - Quale modello IA usare (ad es., claude-opus-4-6, claude-sonnet-4-6)
• Thinking effort - Quanto ragionamento il modello deve applicare
• Istruzioni - Istruzioni personalizzate a livello di sistema che plasmano il comportamento dell’agente
• Skill, command e script - I set di asset attivati per questa persona nella sandbox
• Learning - Se includere i learning compilati del progetto nel contesto dell’agente

Le personas vengono abilitate o disabilitate a livello di progetto. Le personas disabilitate non appaiono nella configurazione del workflow né nei selettori di step della persona pipeline.

Contesti

I contesti sono documenti riutilizzabili e versionati che definiscono il system prompt e il contenuto CLAUDE.md iniettati nelle sessioni di agente. A differenza del system prompt di sandbox globale (che si applica a ogni sandbox del progetto), i contesti sono limitati a specifici tipi di sessione - dandoti un controllo preciso su quali istruzioni riceve ogni classe di agente.

Limitazione per tipo di sessione

Ogni documento di contesto è legato a uno dei seguenti tipi di sessione:

• learning - Sessioni che estraggono e revisionano i learning dai run completati
• merging - Sessioni in cui un merge agent integra i branch
• issue - Sessioni di scoperta e scan delle issue
• answering - Answering session che risolvono le domande prodotte dalle sessioni di issue prima dell’implementazione
• evaluating - Sessioni di evaluator agent che valutano la qualità dell’output del run
• judging - Sessioni di judge agent che confrontano gli output tra branch paralleli

Versionamento dei contesti

Ogni documento di contesto è versionato. Quando aggiorni un contesto, la versione precedente viene conservata, così puoi tracciare come sono evolute le tue istruzioni e tornare indietro se una modifica degrada le prestazioni dell’agente. La versione attiva di un contesto è quella iniettata nelle nuove sessioni di quel tipo. I documenti di contesto sono accessibili a /p/[id]/context all’interno del tuo progetto.

Asset: Skill, Command e Script

Gli asset sono package versionati in modo indipendente e pubblicabili, che estendono le capacità dell’agente all’interno della sandbox. Gli asset vengono creati e gestiti a livello di progetto e possono essere collegati selettivamente a singole personas o a specifici tipi di sessione tramite le Session Configuration.

Skill

Gli skill sono package di conoscenza specialistica. A differenza di un singolo file di istruzioni, uno skill è composto da più file - ad esempio, uno skill Convex potrebbe includere un documento di riferimento dei pattern, un file di snippet di codice e un file di linee guida architetturali. Tutti i file di uno skill vengono scritti sul filesystem della sandbox all’avvio della sessione, così l’agente può leggerli, referenziarli e costruirci sopra.

Gli skill sono versionati in modo indipendente. Pubblicare una nuova versione di skill non influisce sulle sessioni in esecuzione - solo le nuove sessioni prendono i file aggiornati.

Command

I command sono alias di comandi shell disponibili per gli agenti all’interno della sandbox. Un command ha un nome, un’espressione shell e una descrizione opzionale. Ad esempio, un command run-tests potrebbe espandersi in npx vitest run --reporter=verbose, dando agli agenti un alias stabile e specifico del progetto indipendentemente da come è configurato il tuo test runner. I command vengono iniettati nell’ambiente della sandbox all’avvio della sessione.

Script

Gli script sono script shell o Python eseguibili che possono essere lanciati in punti specifici del ciclo di vita di un workflow - prima che l’agente parta, dopo che l’agente ha completato, o su richiesta. Gli script sono utili per pre-popolare la sandbox con dati dinamici, validare l’output dopo il completamento o eseguire step di post-elaborazione troppo procedurali per un agente.

Selezione degli asset per persona e tipo di sessione

Skill, command e script possono essere collegati a due livelli:

• Per persona - Quando una persona viene usata in uno step di pipeline, i suoi asset configurati vengono iniettati nella sandbox solo per quello step
• Per tipo di sessione - La pagina Session Configuration di ogni tipo di sessione (issue, learning, merging, answering, evaluating, judging) ti permette di selezionare quali asset sono disponibili per tutte le sessioni di quel tipo

Issue e Answering Session

Le sessioni di issue ti permettono di scansionare una codebase alla ricerca di problemi e opportunità di miglioramento. Una sessione di issue crea una sandbox che analizza il repository e genera una lista strutturata di issue, ciascuna con un titolo, una descrizione, una priorità (low, medium, high, critical) e un prompt suggerito per la risoluzione.

Answering Session

Quando una sessione di issue produce domande o ipotesi non risolte - ad esempio, “Questo dovrebbe usare il layer di cache esistente o bypassarlo?” - può essere avviata una answering session per lasciare che l’agente IA (o un collaboratore umano) risolva quelle domande prima che inizi l’implementazione. L’answering session riceve la lista delle domande aperte e produce risposte strutturate che vengono poi passate al run di implementazione. Questo impedisce agli agenti di fare ipotesi errate su requisiti ambigui.

Le singole issue possono essere eseguite creando un run con il prompt suggerito, o raggruppate in work chain che elaborano più issue in sequenza sullo stesso branch.

Sprint Chain

Le sprint chain sono un meccanismo di orchestrazione in batch per eseguire più run di workflow attraverso una serie di sprint pianificati. Si distinguono dalle work chain (che concatenano fix di issue su un singolo branch) in quanto ogni sprint di una sprint chain è un’unità di lavoro indipendente con il proprio branch e la propria pull request.

Struttura di una sprint chain

Una sprint chain traccia:

• Intervallo di sprint- Il numero totale di sprint definiti nella chain (ad es., “sprint da 1 a 8”)
• Indice di sprint corrente - Quale sprint è attualmente in esecuzione o è stato completato per ultimo
• Tracciamento PR per sprint - Ogni sprint registra il proprio URL di pull request, il nome del branch e lo stato della PR in modo indipendente
• Prompt di sprint - Ogni sprint della chain può avere il proprio prompt o ereditare quello predefinito della chain

Le sprint chain sono ben adatte per eseguire una roadmap di feature dove ogni feature necessita di review e merge indipendenti. La chain avanza attraverso gli sprint automaticamente o su approvazione manuale, a seconda della tua configurazione.

Task ricorrenti

I task ricorrenti ti permettono di pianificare qualsiasi workflow CodeCourier perché venga eseguito automaticamente a una cadenza ripetuta. È utile per build notturni, audit settimanali di qualità del codice, controlli quotidiani delle dipendenze o qualsiasi workflow che il tuo team vuole automatizzare senza avvio manuale.

Opzioni di frequenza

I valori di frequenza supportati sono:

• daily - Viene eseguito ogni giorno all’ora e al minuto configurati
• every_other_day - Viene eseguito a giorni alterni
• weekly - Viene eseguito una volta a settimana nel giorno configurato
• biweekly - Viene eseguito una volta ogni due settimane
• monthly - Viene eseguito una volta al mese nel giorno configurato

Fuso orario e pianificazione

I task ricorrenti memorizzano un fuso orario, un’ora e un minuto di esecuzione. La piattaforma li usa per calcolare il prossimo orario di run (nextRunAt) e avvia il run automaticamente quando arriva l’orario pianificato. Tutti gli orari pianificati sono memorizzati in UTC internamente ma possono essere configurati e visualizzati in qualsiasi fuso orario IANA.

Ruoli Evaluator e Judge

CodeCourier include due ruoli di agente specializzati per la valutazione della qualità, che vanno oltre il pattern di checker standard:

Evaluator

Un evaluator agent valuta la qualità dell’output di un run o di un run step attraverso le sei dimensioni di qualità (vedi Scoring di qualità più sotto). Gli evaluator sono utili nelle pipeline lunghe dove vuoi una passata di valutazione della qualità dedicata dopo l’implementazione e prima della review finale. L’output dell’evaluator è strutturato - produce punteggi numerici e un riepilogo, non un verdetto binario superato/fallito.

Judge

Un judge agent confronta gli output di branch paralleli o di più tentativi di run e seleziona il migliore. I judge sono utili quando esegui lo stesso prompt su più configurazioni simultaneamente (modelli diversi, personas diverse, set di skill diversi) e vuoi un arbitro oggettivo per decidere quale risultato far avanzare. Il judge riceve tutti gli output candidati e produce un confronto strutturato con un vincitore e una motivazione.

Scoring di qualità

CodeCourier traccia la qualità dell’output a livello di run step tramite un oggetto di punteggio di qualità strutturato. Questo dà ai team un segnale oggettivo e coerente su quanto bene ha performato ogni invocazione di agente - oltre al semplice “ha completato?”.

Dimensioni del punteggio

Ogni punteggio di qualità di run step include sei dimensioni, ciascuna valutata su una scala da 0 a 100:

• Correttezza - L’output implementa correttamente i requisiti?
• Type safety - I tipi TypeScript sono corretti, senza any impliciti né errori di tipo?
• Stile del codice - Il codice segue le convenzioni e le linee guida di stile del progetto?
• Copertura dei test - I test sono presenti, significativi e coprono il codice modificato?
• Completezza - L’agente ha affrontato tutte le parti del prompt?
• Composito - Un aggregato ponderato delle cinque dimensioni sopra

I singoli punteggi di run step vengono aggregati in un qualityScore complessivo sul record del run. Questo permette di filtrare e ordinare i run per qualità nelle viste di analytics e ti fa individuare quali configurazioni di workflow producono sistematicamente output di qualità più alta.

Check CI

I run tracciano lo stato dei check CI tramite un oggetto ciChecks che viene aggiornato man mano che la tua pipeline CI elabora il codice generato dall’agente. L’oggetto contiene:

• status - Stato CI complessivo: pending, running, passing, failing o skipped
• checks - Un array di risultati dei singoli check, ciascuno con un nome, uno stato e un URL di dettagli opzionale
• checkedAt - Timestamp dell’interrogazione più recente dello stato CI

I dati dei check CI appaiono nella pagina di dettaglio del run, così puoi valutare la qualità del codice senza passare all’interfaccia del tuo provider CI.

Learning

I learning sono il sistema di gestione della conoscenza in CodeCourier. Ogni volta che un agente IA commette un errore, scopre un pattern o incontra un requisito specifico del progetto, quella conoscenza può essere catturata come record di learning strutturato.

Struttura di un learning

Ogni learning contiene:

• Descrizione - Cosa è stato imparato
• Trigger - Quale situazione attiva questo learning
• Comportamento corretto - Cosa dovrebbe fare l’agente quando si verifica il trigger
• Severità - Critical, important o minor
• Categoria - Preference, pattern, gotcha, tool o architecture
• Confidenza - Un punteggio numerico che indica quanto è affidabile questo learning
• Sorgente - Se è stato creato da un agente durante un run o estratto da una sessione a posteriori

Ciclo di vita di un learning

I learning passano attraverso un processo di review in tre fasi:

1. Pending - Appena creato, in attesa di review umana
2. Approved - Verificato da un membro del team e incluso nelle sessioni future
3. Rejected - Scartato come errato o non utile

Versioni di learning

I learning approvati vengono compilati in documenti markdown versionati chiamati learning version. Ogni versione è limitata a un progetto e a un tipo di ruolo, contiene il markdown compilato e referenzia quali record di learning individuali sono inclusi. Quando viene fornita una nuova sandbox, la learning version attiva viene iniettata automaticamente nel contesto dell’agente.

Il modello dei dati in tempo reale

CodeCourier usa Convex come database e runtime backend. Questo significa che ogni query è una subscription reattiva: quando i dati cambiano sul server, ogni client connesso che sta leggendo quei dati si aggiorna istantaneamente, senza polling o refresh manuale richiesto.

Questa architettura ha implicazioni importanti per l’esperienza CodeCourier:

• Gli aggiornamenti dello stato del run (pending a running a completed) appaiono immediatamente nei browser di tutti i membri del team
• I messaggi della sandbox scorrono in tempo reale man mano che l’agente li produce
• I punteggi di qualità e lo stato dei check CI si aggiornano in tempo reale man mano che gli evaluator completano le loro valutazioni e le pipeline CI rendono conto
• Nuovi learning, modifiche ai workflow e aggiunte di membri del team si propagano istantaneamente
• I contatori del dashboard e le analytics si aggiornano in tempo reale senza refresh della pagina

Tutta la logica di business - autenticazione, autorizzazione, validazione e mutazioni dei dati - gira nelle Convex server function. Il frontend non parla mai direttamente al database; chiama query Convex (che si sottoscrivono in modo reattivo) e mutation (che modificano i dati tramite function lato server validate).

Come si collegano i concetti

Ecco come si relazionano tra loro i concetti principali:

• Un progetto contiene workflow, personas, contesti, asset, piani, issue, learning, task ricorrenti, sprint chain e membri del team
• Un workflow referenzia un progetto e definisce un blueprint per i run
• Una persona appartiene a un progetto e porta con sé il proprio set di asset (skill, command, script) e il proprio legame di contesto; può essere referenziata dagli step di workflow persona pipeline
• Un contesto appartiene a un progetto, è limitato a un tipo di sessione ed è iniettato automaticamente nelle sandbox di quel tipo
• Gli asset (skill, command, script) appartengono a un progetto e vengono selezionati per persona e per tipo di sessione
• Un run appartiene a un progetto, referenzia facoltativamente un workflow, crea una o più sandbox e traccia i punteggi di qualità e lo stato dei check CI
• Una sandbox appartiene a un run (o esiste in modo autonomo) e contiene messaggi
• Una sessione di issue appartiene a un progetto e produce issue che possono avviare run, work chain o answering session
• Una sprint chain appartiene a un progetto e orchestra una serie di run attraverso sprint pianificati, ciascuno con il proprio branch e la propria PR
• Un task ricorrente appartiene a un progetto e avvia run secondo una pianificazione configurabile
• I learning vengono estratti dalle sandbox, revisionati dai membri del team, compilati in versioni e iniettati nelle sandbox future

Prossimi passi