Persona integrate

CodeCourier definisce dieci tipi di persona integrate. Questi tipi non sono persona pre-create in sé, ma piuttosto definizioni di ruolo che ogni persona deve usare. Quando crei una nuova persona, le assegni uno di questi tipi, che ne determina l’icona, il colore, lo strumento e il modello predefiniti, e il suo ruolo all’interno delle persona pipeline.

I tipi integrati sono definiti nella configurazione degli step di workflow (convex/config/workflows.config.ts) e sono condivisi su tutta la piattaforma. Comprendere ogni tipo ti aiuta a creare persona ben adatte al loro ruolo nel processo di sviluppo.

Designer

Il Designer è l’agente di implementazione principale. Riceve un task prompt e scrive codice per realizzarlo. I designer lavorano direttamente nel filesystem della sandbox: creando file, installando pacchetti, configurando strumenti di build ed eseguendo il server di sviluppo.

Quando usarlo: Qualsiasi task che richiede scrittura o modifica di codice. Implementazione di feature, bug fix, modifiche di configurazione, scrittura di documentazione e script di migrazione. Se l’output è codice in un repository, una persona Designer è la scelta giusta.

Casi d’uso: Implementazione di componenti React, sviluppo di API REST, migrazioni di schema database, generazione di file di configurazione, setup di build pipeline.

Configurazione consigliata:Usa il modello più capace disponibile (Opus) per task complessi. Imposta il thinking effort su “high” per modifiche architetturali. Includi skill rilevanti per lo stack tecnologico (ad es., frontend-design per il lavoro UI, convex-implementation per il lavoro sul database). Associa un documento di contesto che copra l’architettura della tua codebase o gli standard di coding.

Checker

Il Checker è un agente di review basato su verdetto che valuta il lavoro svolto da uno step precedente (tipicamente un Designer). Legge le modifiche al codice, esegue opzionalmente test, e produce un verdetto strutturato: pass o fail con feedback dettagliato. Questo verdetto binario è ciò che distingue il Checker dal tipo Reviewer.

Quando un Checker restituisce un verdetto fail, il workflow può tornare allo step Designer per un’altra iterazione, creando un ciclo design-review automatizzato che migliora la qualità senza intervento umano.

Quando usarlo: Dopo qualsiasi step Designer in cui la garanzia di qualità conta. Code review, type checking, verifica dei test, audit di sicurezza e controlli di conformità.

Casi d’uso: Applicazione della type safety TypeScript, gate di copertura dei test, conformità alle policy di sicurezza, aderenza alla style guide, controlli del budget di performance.

Configurazione consigliata: Un modello più veloce (Sonnet) è spesso sufficiente poiché il compito del Checker è più focalizzato di quello del Designer. Le istruzioni devono definire criteri pass/fail espliciti - il checker non deve mai essere ambiguo riguardo al suo verdetto. Includi la skill app-security se la security review fa parte del controllo.

Optimizer

L’Optimizer è uno specialista del refactoring. Prende codice che già funziona e lo migliora: riducendo la duplicazione, migliorando le performance, aumentando la leggibilità e applicando le best practice. L’Optimizer non aggiunge nuove feature; migliora quelle esistenti.

Quando usarlo: Come step di post-elaborazione dopo che un Designer ha completato l’implementazione. Particolarmente prezioso per grandi modifiche al codice dove il Designer si è concentrato sul far funzionare le cose e l’Optimizer rifinisce il risultato.

Casi d’uso: Eliminazione di pattern di query N+1, riduzione dei re-render React, estrazione di hook riutilizzabili, normalizzazione della gestione degli errori, miglioramento della dimensione del bundle.

Configurazione consigliata: Usa Opus per la sua capacità di comprendere codebase complesse. Le istruzioni dovrebbero indicare esplicitamente cosa NON cambiare (API pubbliche, export) per evitare breaking change durante l’ottimizzazione. Includi la skill performance-optimization-addyosmani per lavoro focalizzato sulle performance.

Prompter

Il Prompter è un agente di prompt engineering. Prende una richiesta informale, potenzialmente vaga, dell’utente e la riscrive in una specifica chiara e strutturata con criteri di accettazione espliciti. Il prompt raffinato viene poi passato allo step successivo della pipeline.

Quando usarlo: Come primo step di una pipeline quando le richieste utente sono probabilmente sotto-specificate. Particolarmente prezioso per team in cui stakeholder non tecnici inviano richieste di feature che devono essere tradotte in specifiche tecniche.

Casi d’uso: Traduzione di requisiti di prodotto in spec tecniche, espansione di brevi descrizioni di task in guide di implementazione dettagliate, generazione di criteri di accettazione da user story.

Configurazione consigliata:Sonnet è di solito sufficiente per il raffinamento dei prompt. Le istruzioni dovrebbero specificare il formato di output (ad es., “includi sempre i criteri di accettazione come elenco numerato e identifica esplicitamente i file interessati”).

Investigator

L’Investigator è un agente di ricerca che analizza la codebase prima che inizi l’implementazione. Legge file, traccia dipendenze, mappa l’architettura e produce un riepilogo strutturato dei risultati. Questo contesto aiuta gli agenti successivi a prendere decisioni migliori.

Quando usarlo: Prima di uno step Designer su codebase non familiari, investigazioni di bug mirate, o quando il task richiede di capire come funziona un sottosistema specifico. L’Investigator si concentra su un’area particolare della codebase e ne riporta i risultati in modo conciso.

Casi d’uso: Comprendere un sottosistema di autenticazione prima di aggiungere un nuovo provider OAuth, tracciare un flusso di dati specifico prima di refattorizzarlo, identificare quali file saranno interessati da una modifica proposta.

Configurazione consigliata:Usa Opus per la sua comprensione superiore della codebase. Imposta il thinking effort su “high”. Le istruzioni dovrebbero specificare cosa investigare (ad es., “concentrati su query database e route API relative all’autenticazione”). Per un’analisi trasversale completa, preferisci invece il tipo Deep-Dive.

Planner

Il Planner è un agente di architettura che analizza le codebase e crea valutazioni strutturate. Esamina il repository, comprende i requisiti e scompone il lavoro in item azionabili. Ogni item ha un nome, una descrizione e un prompt dettagliato. Questo tipo alimenta la feature delle issue session di CodeCourier.

Quando usarlo: Per progetti complessi e multi-step che beneficiano di un’analisi preliminare. L’output del Planner può essere eseguito direttamente dal sistema di work chain di CodeCourier.

Casi d’uso: Scomposizione di una grande richiesta di feature in issue discrete, identificazione del debito tecnico nella codebase, produzione di un elenco prioritizzato di miglioramenti, generazione di backlog di issue per lo sprint planning.

Configurazione consigliata: Usa sempre Opus con thinking effort alto. Il Planner necessita della massima capacità di reasoning per scomporre efficacemente progetti complessi. Associa un documento di contesto architetturale per i migliori risultati.

Deep-Dive

Il Deep-Dive è un agente di analisi intensiva progettato per problemi complessi e multiforme che richiedono una comprensione completa della codebase. È simile all’Investigator ma opera con un ambito più ampio - invece di concentrarsi su un sottosistema, esplora problematiche trasversali, traccia le interazioni tra più sistemi e produce un report di analisi esaustivo.

Le sessioni Deep-Dive durano tipicamente più a lungo e con thinking effort più alto rispetto alle sessioni Investigator. L’output è più approfondito: non solo “ecco come funziona questo sottosistema”, ma “ecco come interagiscono tutti i sistemi rilevanti, dove i confini sono ambigui, come appare la superficie di rischio, e quali decisioni architetturali hanno portato allo stato attuale.”

Quando usarlo: Analisi architetturale prima di un refactor importante, investigazione di root-cause per un incidente di produzione complesso, comprendere una codebase legacy prima dell’onboarding di un nuovo team, o qualsiasi task di analisi in cui la profondità conta più della velocità.

Casi d’uso: Valutazione architetturale pre-migrazione, threat modeling di sicurezza su un’intera applicazione, analisi delle dipendenze prima dell’upgrade di una libreria importante, tracciamento di un flusso di dati che attraversa più servizi e database.

Configurazione consigliata: Usa sempre Opus con thinking effort max o xhigh. Prevedi un runtime sandbox più lungo (aumenta il timeout). Includi skill ampie: app-security, performance-optimization-addyosmani, superpower-debugging. Associa un documento di contesto che fornisca contesto architetturale a livello di progetto affinché l’agente possa concentrarsi sulla profondità piuttosto che sull’orientamento.

Reviewer

Il Reviewer è un agente di code review specializzato focalizzato su sicurezza, manutenibilità, design pattern e qualità del codice. È fondamentalmente diverso dal Checker in un aspetto critico: il Reviewer non produce verdetti pass/fail. Produce invece feedback di review dettagliato e sfumato - osservazioni, suggerimenti, preoccupazioni ed elogi - su cui uno sviluppatore umano o un agente successivo può agire.

Questo rende il Reviewer ideale per situazioni in cui un gate binario è troppo grezzo. Un Checker potrebbe respingere del codice per un problema minore che fallisce un criterio rigido; un Reviewer noterebbe lo stesso problema come una “preoccupazione minore” pur riconoscendo che l’implementazione è fondamentalmente solida.

Quando usarlo: Code review pre-merge che devono informare una decisione umana, review architetturale di un design proposto, security review che produce una valutazione del rischio invece di un blocco, o qualsiasi scenario di review in cui il feedback qualitativo è più prezioso di un verdetto binario.

Casi d’uso: Commenti di review su pull request, valutazione del rischio di sicurezza per una nuova superficie API, audit di conformità dei design pattern, review di accessibilità per una libreria di componenti UI.

Configurazione consigliata:Usa Opus per un reasoning sfumato. Imposta il thinking effort su “high”. Le istruzioni dovrebbero definire esplicitamente il formato di output (ad es., sezioni per Punti di forza, Preoccupazioni maggiori, Preoccupazioni minori, Suggerimenti). Includi le skill app-security e superpower-codereview. Il Reviewer non dovrebbe essere posizionato in un loop - il suo scopo è produrre una review completa unica, non un gate-loop.

Custom

Il tipo Custom è un tipo di persona libero per agenti che non rientrano in nessuna delle nove categorie standard. Non impone aspettative strutturali sul comportamento dell’agente - questo si comporta esattamente come dettano le sue istruzioni, skill, contesto, command e script. Il tipo Custom offre la massima flessibilità per ruoli specializzati e non standard.

Quando usarlo: Quando nessuno dei nove tipi integrati descrive accuratamente cosa fa la persona. Le persona Custom spesso ricoprono ruoli unici specifici al workflow di un progetto piuttosto che fasi di sviluppo generali.

Casi d’uso:

• Scrittore di documentazione - Genera o aggiorna JSDoc, file README, documentazione API e commenti inline nel codice.
• Generatore di changelog - Legge l’output di git diff e produce voci di changelog leggibili in un formato specificato.
• Assistente di migrazione - Applica sistematicamente un pattern di migrazione database o API specifico su più file.
• Auditor delle dipendenze - Scansiona package.json alla ricerca di dipendenze obsolete o vulnerabili e produce un piano di upgrade.
• Agente di localizzazione - Estrae stringhe hardcoded e popola i file di risorse i18n.
• Riassuntore di PR - Legge un git diff e scrive una descrizione strutturata della pull request.

Configurazione consigliata: Poiché il tipo Custom non ha un ruolo predefinito, la qualità della persona dipende quasi interamente dalla qualità delle sue istruzioni. Scrivi istruzioni altamente specifiche e strutturate che non lascino nulla di ambiguo. Scegli il modello in base alla complessità del task - semplici task di trasformazione testuale possono usare Sonnet, mentre task complessi di reasoning multi-file dovrebbero usare Opus.

Riepilogo della selezione dei tipi

Prossimi passi