Creare persona
Guida passo passo per creare persona IA in CodeCourier, inclusi tutti e dieci i tipi di persona, i campi, il binding di contesto e la configurazione iniziale.
Creare una persona in CodeCourier richiede solo pochi click dalla dashboard. Una volta creata, la persona può essere usata in qualsiasi persona pipeline all’interno del progetto. Questa guida illustra il processo di creazione, spiega ogni campo e fornisce raccomandazioni per ottenere i migliori risultati dalle tue configurazioni di persona.
Creare una persona dall’UI
Naviga alla pagina Personas
Dalla dashboard del tuo progetto, trova la voce Personas nella navigazione laterale. Se non la vedi, potresti dover scorrere o accedervi dal menu di navigazione. La pagina delle persona si trova all’indirizzo /p/{projectId}/personas.
Apri la finestra di dialogo Create
Clicca sul pulsante + Create nell’angolo in alto a destra dell’header di pagina. Questo apre una finestra di dialogo in cui inserisci i dettagli base della persona. Se non hai ancora nessuna persona, la pagina mostra uno stato vuoto con un pulsante di creazione ben visibile.
Inserisci un nome
Dai alla tua persona un nome descrittivo che ne rifletta lo scopo. I buoni nomi comunicano ruolo e specializzazione a colpo d’occhio:
Frontend Designer- un designer focalizzato sull’implementazione UIStrict Code Reviewer- un reviewer con feedback dettagliatoSecurity Checker- un checker che applica gli standard di sicurezzaPerformance Optimizer- un optimizer focalizzato sull’efficienza runtimeArchitecture Planner- un planner per task di progettazione di sistema
I nomi devono essere non vuoti e vengono validati all’invio. Possono essere modificati in seguito dalla pagina di dettaglio della persona.
Seleziona un tipo
Scegli il tipo di persona dal menu a tendina. CodeCourier definisce i seguenti tipi, ciascuno corrispondente a un ruolo specifico nella pipeline di workflow:
- Designer - Agente principale di coding e implementazione
- Checker - Code review con verdetto pass/fail e feedback
- Optimizer - Agente di miglioramento del codice e refactoring
- Prompter - Agente di prompt engineering e specifica
- Investigator - Agente di analisi della codebase e ricerca
- Planner - Agente di architettura e analisi delle issue
- Deep-Dive - Agente di analisi intensiva multi-sistema
- Reviewer - Code review qualitativo senza verdetto pass/fail
- Custom - Tipo libero per ruoli specializzati o non standard
Il tipo determina l’icona della persona e il suo comportamento predefinito all’interno delle persona pipeline. La selezione predefinita è designer.
Aggiungi una descrizione (opzionale)
Il campo descrizione è opzionale ma consigliato. Usalo per documentare lo scopo della persona, la sua specializzazione, o eventuali convenzioni che deve seguire. Questo aiuta i membri del team a capire a cosa serve la persona quando la selezionano nelle configurazioni di workflow.
Invia il form
Clicca su Create per salvare la persona. In caso di successo, vieni automaticamente reindirizzato alla pagina di dettaglio della persona dove puoi configurare impostazioni avanzate come selezione del modello, istruzioni, skill, command, script e binding di contesto.
Avvio rapido
Riferimento dei campi della persona
La finestra di dialogo di creazione cattura i campi essenziali. La configurazione completa è disponibile nella pagina di dettaglio della persona dopo la creazione. Ecco un riferimento completo di tutti i campi:
Campi principali (impostati alla creazione)
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
name | string | Sì | Nome visualizzato della persona. Deve essere non vuoto. |
type | enum | Sì | Tipo di ruolo: designer, checker, optimizer, prompter, investigator, planner, deep-dive, reviewer o custom. |
description | string | No | Descrizione leggibile dello scopo della persona. |
Campi di configurazione (impostati nella pagina di dettaglio)
| Campo | Tipo | Predefinito | Descrizione |
|---|---|---|---|
cliId | string | Predefinito del progetto | Quale strumento CLI usare (ad es., claude, opencode, codex). |
model | string | Predefinito dello strumento | Modello LLM specifico (ad es., claude-opus-4-6, claude-sonnet-4-6). |
thinkingEffort | string | none | Profondità di reasoning: none, low, medium, high, xhigh o max. |
instructions | string | Vuoto | Istruzioni di sistema personalizzate per l’agente. |
contextId | ID | Nessuno | Associa un documento Context a questa persona. Il markdown della versione attiva del contesto viene iniettato nella sandbox insieme alle istruzioni della persona. |
selectedSkills | string[] | Vuoto | Array di ID di skill da rendere disponibili durante le sessioni. |
selectedCommands | string[] | Vuoto | Array di ID di command da iniettare nella sandbox come alias o command di shell. |
selectedScripts | string[] | Vuoto | Array di ID di script da iniettare nella sandbox come script eseguibili. |
learningsEnabled | boolean | true | Se i learning compilati vengono iniettati nelle sessioni. |
isEnabled | boolean | true | Se la persona è attiva e selezionabile nelle pipeline. |
Campi di versioning (gestiti automaticamente)
| Campo | Tipo | Descrizione |
|---|---|---|
version | number | Numero di versione incrementale monotono. Inizia da 1 alla creazione. |
isLatest | boolean | True sulla versione attiva corrente. Solo una versione per persona è latest in ogni momento. |
parentPersonaId | ID | Punta al record di versione precedente. Null sulla prima versione. |
Versioning e modifica
isLatest e tutti i futuri workflow run la usano. Le versioni precedenti vengono conservate e sono visibili nella cronologia delle versioni.Binding di contesto
I documenti Context sono risorse markdown riutilizzabili - documentazione, guide di riferimento, note architetturali, o qualsiasi altro materiale di riferimento - che mantieni separatamente dalle istruzioni della persona. Quando associ un documento di contesto a una persona tramite il campo contextId, il markdown della versione attiva del contesto viene automaticamente anteposto alla configurazione della sandbox insieme alle istruzioni della persona stessa.
Questo è particolarmente potente per condividere contesto tra più persona senza duplicare contenuti. Ad esempio, un documento di contesto “Codebase Architecture” potrebbe essere associato contemporaneamente alle tue persona designer, reviewer e deep-dive. Quando aggiorni il documento di architettura, tutte e tre le persona recepiscono la modifica al prossimo run.
Per associare un contesto, naviga alla tab Context nella pagina di dettaglio della persona e seleziona un documento di contesto dal menu a tendina. Solo i documenti di contesto attivi sono elencati.
Creare persona tramite API
Le persona possono anche essere create programmaticamente tramite la mutation Convex. Questo è utile per automatizzare la configurazione delle persona o costruire tooling personalizzato:
import { api } from "@/convex/_generated/api";
import { useMutation } from "convex/react";
// In a React component:
const createPersona = useMutation(api.personas.create);
const personaId = await createPersona({
projectId: "your-project-id",
name: "Frontend Designer",
type: "designer",
description: "Specialized in React and Tailwind CSS",
model: "claude-opus-4-6",
instructions: "Follow the project's component patterns...",
contextId: "context-id-for-architecture-doc",
selectedSkills: ["frontend-design", "vitest-testing"],
selectedCommands: ["lint-check", "type-check"],
selectedScripts: ["run-tests"],
isEnabled: true,
});Validazione
ConvexError da parte della mutation. Fai sempre il trim dell’input utente prima di inviarlo.Duplicare persona esistenti
Se vuoi creare una persona simile a una esistente, usa l’azione Duplicate dalla lista delle persona. Questo crea una copia con “(copy)” aggiunto al nome e impostazioni identiche - incluso lo stesso binding di contesto, skill, command e script. Puoi poi rinominarla e modificare solo i campi che devono cambiare. La duplicazione è spesso più veloce che creare da zero quando hai bisogno di più persona con configurazioni simili.
Operazioni bulk
La pagina di elenco delle persona supporta la selezione multipla tramite checkbox. Seleziona più persona e usa la barra delle azioni bulk per eliminarle tutte insieme. L’eliminazione bulk usa il soft delete, il che significa che le persona vengono spostate nel cestino e possono essere ripristinate se necessario.