Configurazione delle persona

Dopo aver creato una persona, la pagina di dettaglio offre sette tab per configurare ogni aspetto del comportamento dell’agente: Configuration, Instructions, Context, Skills, Activity, Analytics e Related. Questa guida copre ogni tab in profondità, con best practice e raccomandazioni per ogni impostazione.

Tab Configuration

La tab Configuration controlla il comportamento runtime principale della persona: quale strumento usa, quale modello esegue e con quale profondità ragiona sui problemi.

Selezione dello strumento CLI

Lo strumento CLI determina quale agente di coding IA viene eseguito all’interno della sandbox. CodeCourier supporta più strumenti, ciascuno con i propri punti di forza:

• Claude Code (claude) - L’agente di coding di Anthropic. Ideale per la generazione di codice complesso, modifiche multi-file e task di reasoning profondo. Supporta thinking effort fino a “max”.
• OpenCode (opencode) - Alternativa open source con supporto per più provider di modelli. Adatto a team che necessitano di flessibilità nella scelta del modello.
• Codex (codex) - L’agente di coding di OpenAI. Ideale per task che beneficiano dei modelli GPT.

Quando cambi lo strumento CLI, il menu a tendina del modello si aggiorna automaticamente per mostrare solo i modelli disponibili per quello strumento. Se il modello attualmente selezionato non è disponibile sul nuovo strumento, torna al modello predefinito dello strumento.

Selezione del modello

Il modello determina l’LLM specifico che alimenta l’agente. I modelli disponibili dipendono dallo strumento CLI selezionato. Per Claude Code, le opzioni tipiche includono:

• claude-opus-4-6 - Massima capacità, ideale per task complessi. Costo e latenza maggiori.
• claude-sonnet-4-6 - Buon equilibrio tra qualità e velocità. Consigliato per i ruoli checker e prompter.

Scegli il modello in base al ruolo della persona. I designer, gli agenti deep-dive e gli optimizer traggono tipicamente beneficio dal modello più capace (Opus), mentre checker, reviewer e prompter funzionano bene con modelli più veloci (Sonnet) poiché i loro task sono più vincolati.

Thinking effort

Il thinking effort controlla quanto reasoning applica il modello prima di produrre l’output. Un effort più alto porta a risultati migliori su problemi complessi ma aumenta latenza e costo.

Iniezione dei learning

Quando abilitata, le sessioni della persona ricevono automaticamente i learning compilati attivi per il proprio tipo di ruolo. I learning sono conoscenze catturate dai run passati - pattern, insidie, preferenze e best practice che migliorano il comportamento dell’agente nel tempo.

Ogni versione di learning viene compilata per tipo di ruolo (designer, checker, ecc.), quindi una persona designer riceve learning specifici per designer mentre una persona checker riceve learning specifici per checker. Questo toggle ti permette di disabilitare l’iniezione per le persona che devono partire da zero senza contesto storico.

Toggle abilita/disabilita

Il toggle isEnabled controlla se la persona è attiva e selezionabile nelle configurazioni di persona pipeline. Disabilitare una persona la nasconde dal selettore di persona negli editor di workflow senza eliminarla. Questo è utile quando una persona è in fase di revisione e non deve essere usata in workflow di produzione finché non è pronta.

Tab Instructions

La tab Instructions fornisce un’area di testo libero per definire il comportamento a livello di sistema della persona. Queste istruzioni vengono iniettate nel contesto dell’agente all’inizio di ogni sessione e modellano il modo in cui affronta i task.

Scrivere istruzioni efficaci

Buone istruzioni di persona sono specifiche, azionabili e strutturate. Ecco pattern che funzionano bene:

## Role
You are a senior frontend engineer specializing in React 19
and Tailwind CSS v4.

## Standards
- Use functional components exclusively
- Extract reusable logic into custom hooks
- All components must have TypeScript interfaces for props
- Prefer server components where possible
- Use the project's existing design tokens from globals.css

## File Organization
- Components go in components/{feature}/
- Hooks go in hooks/
- Never create barrel (index.ts) files

## Testing
- Write unit tests for all utility functions
- Include at minimum one integration test per component
- Use Vitest and React Testing Library

Best practice per le istruzioni

• Sii esplicito su cosa NON fare - I vincoli sono importanti quanto le istruzioni. Di’ all’agente cosa evitare.
• Usa sezioni strutturate - Intestazioni ed elenchi numerati rendono le istruzioni più facili da seguire per il modello.
• Fai riferimento alle convenzioni di progetto - Menziona percorsi file specifici, pattern di naming e strumenti usati nella tua codebase.
• Mantieni il focus - Una persona per il checking non dovrebbe includere istruzioni di implementazione. Ogni persona ha un solo compito.
• Testa e itera - Esegui la persona in alcuni workflow, esamina l’output e affina le istruzioni in base a ciò che va storto.
• Completa, non duplicare il contesto - Se hai un documento Context associato che copre l’architettura, non ripetere quella stessa informazione nel campo Instructions. Lascia che ciascuno serva il proprio scopo.

Tab Context

La tab Context ti permette di associare un documento Context a questa persona. I documenti Context sono risorse markdown a livello di progetto - riepiloghi architetturali, standard di coding, guide di riferimento API, note di onboarding, o qualsiasi materiale di riferimento a cui un agente IA dovrebbe avere accesso durante la sua sessione.

Come funziona il binding di contesto

Quando un documento di contesto è associato a una persona, il markdown della versione attiva viene automaticamente anteposto alla configurazione della sandbox all’inizio di ogni sessione che usa questa persona. L’agente riceve il contenuto del contesto prima di ricevere le istruzioni proprie della persona, quindi il contesto funge da conoscenza di base fondamentale.

Per associare un contesto:

1. Naviga alla tab Context nella pagina di dettaglio della persona.
2. Clicca su Select Context per aprire il selettore di contesto.
3. Scegli dall’elenco dei contesti di progetto disponibili. Nell’elenco compaiono solo i contesti con una versione attiva.
4. Salva. Il binding viene memorizzato come contextId nel record della persona.

Quando usare il binding di contesto vs. le istruzioni

Tab Skills

La tab Skills dà a questa persona accesso a conoscenza di dominio pacchettizzata, shell command e script eseguibili. È organizzata in tre sotto-sezioni: Skills, Commands e Scripts.

Skills

Le skill sono insiemi curati di file di riferimento, best practice e documentazione API per tecnologie specifiche. La sezione Skills mostra tutte le skill abilitate nel progetto come griglia di checkbox. Ogni card di skill mostra nome, descrizione e numero di file della skill. Seleziona le skill rilevanti per il ruolo della persona:

• Un designer frontend potrebbe aver bisogno di: frontend-design, vitest-testing
• Un designer backend potrebbe aver bisogno di: convex-implementation, zod-validation
• Un checker potrebbe aver bisogno di: app-security, superpower-codereview
• Un reviewer potrebbe aver bisogno di: app-security, performance-optimization-addyosmani
• Un planner potrebbe aver bisogno di: superpower-debugging, convex-implementation

Commands

I command sono shell command o alias che vengono iniettati nell’ambiente sandbox all’avvio della sessione. Danno all’agente accesso a operazioni CLI specifiche del progetto, script di build personalizzati, o command di utilità senza richiedere che l’agente conosca la loro implementazione completa.

La sezione Commands mostra tutti i command definiti nel progetto come elenco di checkbox. Ogni voce di command mostra nome, alias e una breve descrizione di cosa fa. Seleziona i command a cui la persona ha bisogno di accedere durante le sue sessioni. Gli ID dei command selezionati vengono memorizzati in selectedCommands nel record della persona.

Esempi di casi d’uso per l’iniezione di command:

• Una persona designer che ha bisogno di npm run typecheck e npm run lint
• Una persona checker che ha bisogno di un command custom validate-schema

Scripts

Gli script sono file di script eseguibili che vengono iniettati nel filesystem della sandbox all’avvio della sessione. A differenza dei command (che sono tipicamente alias o one-liner), gli script sono programmi multi-step che l’agente può invocare per nome.

La sezione Scripts mostra tutti gli script definiti nel progetto. Ogni voce mostra nome, linguaggio (bash, python, node) e descrizione. Gli ID degli script selezionati vengono memorizzati in selectedScripts nel record della persona.

Tab Activity

La tab Activity mostra una tabella paginata di tutti i run step eseguiti da questa persona. Ogni riga include il run collegato, lo status dello step (completed/failed/running), il numero di iterazione e i timestamp. Questo ti dà una cronologia di come la persona ha performato attraverso i workflow run.

Usa il feed di attività per identificare pattern: se una persona fallisce costantemente su un particolare tipo di task, esamina i messaggi di errore per affinare le sue istruzioni. Se una persona richiede regolarmente molte iterazioni prima di superare un checker, considera di aumentare il suo thinking effort o arricchire le sue skill.

Tab Analytics

La tab Analytics fornisce visualizzazioni a serie temporali della performance della persona. Puoi filtrare per periodo (7 giorni, 30 giorni, 90 giorni) e granularità (giornaliera, settimanale, mensile). Vengono tracciate le seguenti metriche:

Il punteggio di qualità è particolarmente prezioso per verificare se le modifiche alle istruzioni stanno avendo un effetto positivo. Dopo aver affinato le istruzioni di una persona, controlla il trend del punteggio di qualità nella settimana successiva per confermare il miglioramento.

I dati sui costi vengono suddivisi per categoria di servizio usando i record di usage del progetto, dandoti visibilità su quale componente di ogni run (inferenza del modello, esecuzione sandbox, ecc.) è il principale driver di costo.

Tab Related Entities

La tab Related mostra le entità collegate a questa persona: i workflow che l’hanno usata, le issue collegate ai suoi run e le versioni di learning compilate per il suo tipo di ruolo. Questo fornisce un modo rapido per navigare da una persona a tutto il lavoro in cui è stata coinvolta nel progetto.

Versioning delle persona

Ogni volta che salvi modifiche alle istruzioni o alla configurazione di una persona, CodeCourier crea un nuovo record di versione invece di sovrascrivere quello esistente. La cronologia delle versioni è accessibile da un pannello Version History nella pagina di dettaglio della persona.

Comportamenti chiave del versioning:

• Il campo version si incrementa a ogni salvataggio (1, 2, 3, …).
• La versione più recente diventa automaticamente isLatest: true.
• Tutti i nuovi workflow run usano la versione più recente.
• Il campo parentPersonaId collega ogni versione al suo predecessore, formando una catena.
• Puoi promuovere qualsiasi versione precedente a latest dal pannello della cronologia versioni, creando un nuovo record di versione che rispecchia il contenuto promosso.

Prossimi passi