Il tuo primo progetto

Dopo l’accesso, arrivi alla schermata di selezione del progetto. Se sei già all’interno di un progetto, clicca sul nome del tuo progetto nell’header della sidebar per tornare al selettore di progetto. Clicca su New Project.

Fornisci le seguenti informazioni:

• Nome del progetto- Un nome leggibile per il tuo progetto, ad es., “E-commerce Backend” o “Design System”
• URL del repository GitHub - (Opzionale) L’URL HTTPS del repository su cui vuoi che gli agenti lavorino, ad es., https://github.com/your-org/your-repo. Questo abilita la creazione automatica dei branch e la generazione di PR.

Lo slug del progetto viene generato automaticamente dal nome. Ad esempio, “E-commerce Backend” diventa e-commerce-backend. Questo slug viene usato in tutti gli URL del progetto.

Clicca su Create Project. CodeCourier crea il record del progetto, ti imposta come owner, inizializza le impostazioni del progetto con i valori predefiniti e ti reindirizza al dashboard del progetto. Il dashboard mostra inizialmente contatori azzerati per sandbox, run, workflow e membri.

Clicca su New Context e seleziona il tipo di sessione issue. Scrivi il system prompt che l’agente di scan delle issue deve ricevere, includendo le priorità del tuo progetto, le aree di attenzione e qualsiasi pattern che deve cercare:

You are scanning a TypeScript/Next.js codebase for issues.
Focus on:
- Type safety violations and implicit any usage
- Missing error boundaries and unhandled promise rejections
- N+1 query patterns in data fetching
- Accessibility regressions in UI components
- Missing or inadequate test coverage

Prioritize issues that would affect production stability.
Generate specific, actionable titles and descriptions.

Salva il contesto. CodeCourier crea la versione 1 di questo documento e lo associa alle sessioni di issue del tuo progetto.

Crea un altro contesto per il tipo di sessione learning. Questo contesto istruisce l’agente di estrazione dei learning su come identificare e categorizzare i learning dai run completati:

You are extracting learnings from an AI agent's completed coding session.
Focus on:
- Mistakes the agent made that were corrected
- Project-specific patterns or conventions that emerged
- Tool usage gotchas specific to this codebase
- Architectural decisions with rationale

Categorize each learning as: preference, pattern, gotcha, tool, or architecture.
Only extract learnings that would be actionable in future sessions.

Ripeti per qualsiasi altro tipo di sessione che usi: merging, answering, evaluating e judging. Ogni tipo di contesto è indipendente; puoi aggiungerli man mano che introduci ogni capacità nel tuo workflow.

Clicca su New Skill. Dai allo skill un nome (ad es., “Project Conventions”) e aggiungi uno o più file. Ogni file ha un nome e un contenuto:

# Project Conventions

## TypeScript
- All files must use strict mode
- Never use `any` - use `unknown` and narrow it
- Prefer interface over type for object shapes

## Database (Convex)
- Never call .collect() on large tables
- Use paginate() for lists longer than 100 items
- Batch writes use ctx.scheduler.runAfter

## Testing
- All new functions need a Vitest unit test
- Integration tests go in __tests__/integration/
- Use MSW for HTTP mocking, never mock fetch directly

Salva lo skill. Ora è disponibile per essere collegato a personas e session configuration.

Crea command per le tue operazioni di agente più comuni. Ad esempio:

• Name: run-tests - Expression: npx vitest run --reporter=verbose
• Name: typecheck - Expression: npx tsc --noEmit
• Name: lint - Expression: npx eslint . --ext .ts,.tsx

I command danno agli agenti alias stabili e specifici del progetto che rimangono coerenti anche se la configurazione del tuo tooling cambia.

Gli script sono opzionali ma utili per l’automazione prima o dopo il run. Ad esempio, uno script pre-run potrebbe clonare il repository verso uno stato noto, oppure uno script post-run potrebbe eseguire un’ultima passata di lint e committare i problemi corretti automaticamente.

Vai in Issue Session in Project Settings. Qui puoi:

• Legare un contesto - Seleziona il contesto di issue che hai creato in precedenza. Questo documento di contesto verrà iniettato automaticamente in ogni sessione di scan delle issue.
• Selezionare skill- Scegli quali package di skill sono disponibili nelle sessioni di issue. Il tuo skill “Project Conventions” è una buona selezione predefinita.
• Selezionare command - Aggiungi i tuoi commandrun-tests e typecheck in modo che l’agente di scan possa validare i propri risultati.
• Impostare il prompt della sessione di issue - Un prompt di testo libero aggiuntivo anteposto al prompt di scoperta dell’utente.

Apri la scheda di configurazione Learning Session. Lega il tuo documento di contesto di learning e seleziona eventuali skill o command rilevanti per l’estrazione dei learning. L’agente di learning userà queste risorse quando analizza le sessioni completate.

Ripeti il processo di legame per le sessioni Merge, Answering, Evaluator e Judge man mano che adotti quelle capacità. Ogni tipo di sessione è pienamente indipendente - puoi configurarle in modo incrementale man mano che il tuo workflow matura.

Clicca su Members nella sidebar sotto la sezione Insights. Questa pagina mostra tutti i membri attuali e gli inviti in attesa.

Clicca su Invite Member. Inserisci l’indirizzo e-mail della persona che vuoi invitare e seleziona il suo ruolo:

• Admin - Può gestire tutte le risorse e le impostazioni del progetto, invitare altri membri
• Member - Può creare e gestire le proprie sandbox, run e workflow

L’invito viene creato immediatamente. La persona invitata vedrà un invito in attesa quando accede a CodeCourier. Una volta che accetta, il suo stato passa da “pending” a “accepted” e ottiene l’accesso a tutte le risorse del progetto in base al suo ruolo.

Dalla pagina dei membri puoi cambiare il ruolo di un membro o rimuoverlo dal progetto. L’owner del progetto non può essere rimosso ma può trasferire la proprietà rendendo owner un altro membro.

Clicca su Personas nella sidebar. Questa pagina mostra tutte le personas configurate per il progetto.

Clicca su New Persona e configurala:

• Name: “Senior Developer”
• Type: Designer
• Model: Scegli il tuo modello preferito (ad es., claude-sonnet-4-6 per la velocità o claude-opus-4-6 per la qualità)
• Thinking effort: Medium o High
• Instructions:

You are a senior full-stack developer. Follow these principles:
- Write clean, well-documented TypeScript code
- Prefer composition over inheritance
- Write tests for all new functions
- Use existing project patterns and conventions
- Keep changes focused and minimal

• Skills: Seleziona il tuo skill “Project Conventions” e qualsiasi altro skill rilevante
• Commands: Abilita run-tests, typecheck e lint
• Learnings: Abilita per includere i learning del progetto nel contesto

Crea una seconda persona per la code review:

• Name: “Code Reviewer”
• Type: Checker
• Model: Usa un modello potente per la review ( claude-opus-4-6 consigliato)
• Thinking effort: High
• Instructions:

You are a thorough code reviewer. Evaluate the changes against:
- Correctness: Does the code do what was asked?
- Type safety: Are there any TypeScript errors or any-typed values?
- Edge cases: Are error states and boundary conditions handled?
- Testing: Are tests present and meaningful?
- Style: Does the code follow project conventions?

Return pass: true only if ALL criteria are met.
If rejecting, provide specific, actionable feedback.

Valuta la creazione di personas aggiuntive per ruoli specifici:

• Investigator - Per task di ricerca che esplorano le codebase prima di apportare modifiche
• Planner - Per sessioni di issue e analisi della codebase con principi architetturali specifici
• Reviewer - Focalizzata su leggibilità, manutenibilità e accuratezza della code review
• Deep-dive - Per task di analisi approfondita che richiedono ragionamento esteso

Vai in Sandboxes nella sidebar e clicca su New Sandbox. Configura il sandbox template, il timeout e le risorse. Dagli un nome descrittivo come “Explore codebase” e fornisci un prompt iniziale.

Le sandbox autonome sono utili per task una tantum: indagare un bug, prototipare una soluzione o testare una modifica di configurazione prima di codificarla in un workflow.

Una volta che la sandbox è in esecuzione, puoi vedere lo stream di messaggi dell’agente in tempo reale. La pagina di dettaglio mostra l’intera cronologia della conversazione, lo stato della sandbox e qualsiasi stato di PR o di estrazione dei learning.

Vai in Workflows e crea un nuovo workflow Persona Pipeline:

• Name: “Full Review Pipeline”
• Type: Persona Pipeline
• Steps: Aggiungi la tua persona “Senior Developer” come primo step, poi la tua persona “Code Reviewer” come secondo step. Configura facoltativamente un loop tra loro con un numero massimo di iterazioni.
• Template: Seleziona il sandbox template corrispondente alla tua preferenza di strumento CLI
• Timeout: 30 minuti per step

Clicca su Run sul tuo nuovo workflow. Inserisci un prompt che descriva la feature o il fix che vuoi:

Add a reusable DateRangePicker component to
components/ui/date-range-picker.tsx. It should:

1. Accept startDate, endDate, and onChange props
2. Use the existing react-day-picker dependency
3. Support both controlled and uncontrolled modes
4. Include proper TypeScript types
5. Follow the existing shadcn/ui component patterns
6. Add a Storybook story file

Specifica un nome di branch (ad es., feat/date-range-picker) e conferma l’URL del repository GitHub se necessario. Clicca su Start Run.

Osserva l’avanzamento del run dalla pagina di dettaglio del run:

1. La persona designer riceve il tuo prompt, esplora il repository e implementa la feature
2. La persona checker revisiona l’implementazione rispetto ai tuoi criteri e approva o fornisce feedback
3. In caso di rifiuto, il designer itera con il feedback fino all’approvazione o al raggiungimento del numero massimo di iterazioni
4. I punteggi di qualità vengono registrati per ogni step - puoi vedere i punteggi di correttezza, type safety, stile del codice, copertura dei test e completezza nei dettagli dello step
5. Al completamento, CodeCourier crea una PR sul branch specificato

Vai in Issues nella sidebar e clicca su New Issue Session. Seleziona il branch che vuoi analizzare e fornisci un prompt di scoperta (o affidati al documento di contesto che hai configurato in precedenza). Avvia la sessione.

La sessione userà il contesto e gli asset di Issue Session che hai configurato in Project Settings. Al completamento, vedrai una lista di issue generate con titoli, descrizioni e priorità.

Alcune issue possono presentare domande aperte o ipotesi non risolte - ad esempio, “Questo cache miss è accettabile, o dovremmo pre-riscaldare la cache?” Quando vedi tali domande collegate a una issue, clicca su Start Answering Session.

L’Answering Session crea una sandbox usando il tuo contesto di Answering Session configurato. L’agente riceve le domande aperte e le elabora, producendo risposte strutturate che vengono ricollegate alla issue. Queste risposte vengono poi passate al run di implementazione, così la persona designer non deve tirare a indovinare.

Con le domande risolte, clicca su Run su una issue (o seleziona più issue e crea una work chain). Il run di implementazione riceve il prompt suggerito della issue più eventuali risposte dall’Answering Session.