Step di workflow

Gli step di workflow sono le singole unità di lavoro all’interno di una pipeline CodeCourier. Ogni step rappresenta un ruolo specifico che un agente IA svolge durante l’esecuzione del workflow. CodeCourier definisce dieci tipi di step, ciascuno progettato per uno scopo distinto nel ciclo di vita dello sviluppo software. Gli step vengono configurati tramite persona e assemblati in pipeline nel workflow builder.

Riferimento dei tipi di step

La tabella seguente riassume tutti i tipi di step disponibili e le loro caratteristiche principali.

type StepRole =
  | "designer"      // Primary implementation agent
  | "checker"       // Review and verdict agent
  | "optimizer"     // Code polish agent
  | "prompter"      // Prompt refinement agent
  | "investigator"  // Codebase research agent
  | "deep-dive"     // Deep analysis agent
  | "evaluator"     // Quality scoring agent
  | "judge"         // Multi-branch comparison agent
  | "answerer";     // Question-answering agent

Tipi di step

Designer

Il designer è l’agente di coding principale. Riceve il prompt del task (o il prompt affinato da uno step precedente) e implementa la soluzione. Gli step designer producono modifiche di codice, creano file, installano pacchetti ed eseguono qualsiasi lavoro di sviluppo necessario a soddisfare i requisiti.

• Strumento predefinito: Claude Code
• Modello predefinito: claude-opus-4-6
• Accetta input: Sì - riceve il prompt e il contesto dagli step precedenti
• Produce output: Sì - modifiche di codice e risultati di implementazione
• Può iterare: Sì - comunemente abbinato a un checker in un loop di iterazione

Il designer è il cavallo di battaglia della maggior parte dei workflow. In un workflow semplice, un singolo step designer può bastare. In pipeline più complesse, il designer lavora all’interno di un loop in cui un checker revisiona il suo output e lo rimanda per revisione se necessario.

Gli step designer includono un comportamento di auto-validazione integrato. Il system prompt istruisce il designer a eseguire la compilazione TypeScript (npx tsc --noEmit), il linting (npx next lint) e la validazione dello schema Convex prima di committare. Questo cattura errori comuni ancor prima che il checker revisioni il lavoro.

Checker

Il checker è un agente di revisione che valuta l’output dello step precedente. Produce un verdetto - una risposta strutturata con un booleano pass e una stringa feedback. Se il checker passa, la pipeline continua verso lo step successivo. Se fallisce, il loop riparte con il feedback del checker incorporato nel prompt del designer successivo.

• Strumento predefinito: Claude Code
• Modello predefinito: claude-sonnet-4-6
• Accetta input: Sì - revisiona l’output del designer
• Produce output: Sì - verdetto (pass/fail) e feedback
• Può iterare: Sì - sempre abbinato a un designer in un loop

Il system prompt del checker enfatizza il testing end-to-end. Di default, i checker sono istruiti a:

1. Rilevare e deployare eventuali modifiche di backend (Convex, database, ecc.).
2. Installare le dipendenze e avviare il dev server.
3. Eseguire test end-to-end usando un browser headless.
4. Verificare ogni requisito del prompt originale.
5. Produrre un verdetto strutturato basato su risultati di test reali.

Optimizer

L’optimizer viene eseguito dopo che un loop designer-checker passa. Il suo compito è ripulire e rifinire il codice senza cambiare la funzionalità. Gli step optimizer gestiscono tipicamente:

• La rimozione di codice morto e import inutilizzati.
• Il miglioramento della denominazione di variabili e funzioni.
• L’aggiunta o il miglioramento di documentazione e commenti.
• Il refactoring per leggibilità e manutenibilità.
• Il mantenimento di uno stile di codice coerente.

• Strumento predefinito: Claude Code
• Modello predefinito: claude-sonnet-4-6
• Accetta input: Sì - lavora sul codice approvato
• Produce output: Sì - modifiche di codice ripulite
• Può iterare: Tipicamente no - viene eseguito una volta dopo l’approvazione

Prompter

Il prompter è un agente che affina o espande una descrizione di task vaga in un prompt dettagliato e attuabile. Analizza la codebase, comprende la struttura del progetto e produce una specifica approfondita che gli step designer successivi possono implementare efficacemente.

• Strumento predefinito: Claude Code
• Modello predefinito: claude-opus-4-6
• Accetta input: Sì - riceve il prompt originale
• Produce output: Sì - prompt affinato/espanso
• Può iterare: Tipicamente no - viene eseguito una volta all’inizio

Il prompter è particolarmente utile quando le tue descrizioni di task sono di alto livello. Invece di « aggiungi l’autenticazione », il prompter potrebbe produrre una specifica di più paragrafi che copre quale provider di auth usare, quali pagine necessitano protezione, dove aggiungere i pulsanti di login e come gestire lo stato di sessione.

Investigator

L’investigator è un agente di ricerca che esplora la codebase per comprendere un problema prima che altri agenti agiscano su di esso. Gli step investigator sono utili per i workflow di debugging - l’investigator legge il codice, esegue test e produce un report che gli step successivi usano come contesto.

• Strumento predefinito: Claude Code
• Modello predefinito: claude-opus-4-6
• Accetta input: Sì - riceve la descrizione del problema
• Produce output: Sì - report di investigazione e risultati
• Può iterare: Tipicamente no - viene eseguito una volta prima degli step designer

Deep-Dive

Lo step deep-dive è un agente di analisi intensiva che esegue ricerche approfondite su issue complesse. Simile all’investigator ma progettato per problemi più difficili che richiedono di leggere molti file, tracciare percorsi di esecuzione e comprendere in profondità l’architettura del sistema.

• Strumento predefinito: Claude Code
• Modello predefinito: claude-opus-4-6
• Accetta input: Sì - riceve la issue o la domanda
• Produce output: Sì - report di analisi dettagliato
• Può iterare: No - viene eseguito una volta

Evaluator

Lo step evaluator valuta l’output attuale della pipeline rispetto a più dimensioni di qualità. Produce un oggetto qualityScores che quantifica quanto bene l’implementazione soddisfa i criteri di qualità definiti. L’evaluator è configurato separatamente tramite la pagina evaluator-setup, dove definisci il contesto che usa, gli skill che applica ed eventuali comandi o script di setup che esegue prima della valutazione.

• Identificatore del tipo di step: evaluator
• Strumento predefinito: Claude Code
• Modello predefinito: claude-opus-4-6
• Accetta input: Sì - valuta lo stato attuale della codebase
• Produce output: Sì - oggetto qualityScores
• Può iterare: Tipicamente no - viene eseguito una volta dopo l’approvazione del design

L’evaluator genera punteggi di qualità su cinque dimensioni:

qualityScores: {
  correctness: number,       // 0-100: Does implementation meet requirements?
  typeSafety: number,        // 0-100: Are TypeScript types correct and complete?
  codeStyle: number,         // 0-100: Does code follow project conventions?
  testCoverage: number,      // 0-100: Are changes covered by tests?
  completeness: number,      // 0-100: Is the implementation fully finished?
  composite: number,         // 0-100: Weighted average of all dimensions
  thresholdResult: boolean,  // True if composite meets the configured threshold
}

Il booleano thresholdResult indica se il punteggio composite soddisfa la soglia di qualità configurata sulla persona evaluator. Questo campo può essere usato dagli step a valle per decidere se procedere o innescare un ulteriore raffinamento. Anche il record complessivo del run porta un campo qualityScore di primo livello (il composite di tutti gli step evaluator) per filtraggio e analytics rapidi.

Judge

Lo step judge confronta gli output di branch parallele e determina quale sia migliore. Viene usato in scenari di valutazione multi-branch in cui due o più implementazioni sono state prodotte - ad esempio, eseguendo lo stesso workflow con modelli o istruzioni diversi - e serve una decisione finale su quale mantenere.

• Identificatore del tipo di step: judge
• Strumento predefinito: Claude Code
• Modello predefinito: claude-opus-4-6
• Accetta input: Sì - riceve gli output di più branch per il confronto
• Produce output: Sì - un verdetto che identifica la branch vincente e la motivazione
• Può iterare: No - viene eseguito una volta dopo il completamento di tutte le branch

Il judge è un tipo di step avanzato per i team che vogliono eseguire esperimenti A/B con le loro configurazioni di workflow. Anziché revisionare manualmente due implementazioni, l’agente judge le valuta rispetto ai requisiti originali e produce un confronto strutturato.

Answerer

Lo step answerer viene usato nelle answering session per rispondere a domande e assunzioni scoperte durante le sessioni di investigazione delle issue. Quando una sessione di issue fa emergere ambiguità o domande che richiedono un chiarimento umano o automatizzato, l’answerer fornisce risposte che permettono alla pipeline di continuare senza intervento manuale.

• Identificatore del tipo di step: answerer
• Strumento predefinito: Claude Code
• Modello predefinito: claude-sonnet-4-6
• Accetta input: Sì - riceve domande e assunzioni dalla sessione di issue
• Produce output: Sì - risposte strutturate che risolvono le ambiguità
• Può iterare: No - viene eseguito una volta per answering session

L’answerer si integra con il workflow di sessione di issue per chiudere il loop di feedback tra investigazione e implementazione. Viene usato più comunemente in pipeline che includono uno step investigator o deep-dive, dove la fase di investigazione può far emergere domande aperte che devono essere risolte prima che l’implementazione inizi.

Configurazione degli step

Ogni step di una pipeline è configurato tramite la sua persona. La persona definisce:

{
  // Role determines the step type and execution behavior
  type: "designer" | "checker" | "optimizer" |
        "prompter" | "investigator" | "deep-dive" |
        "evaluator" | "judge" | "answerer",

  // CLI tool override (falls back to workflow default)
  cliId: "claude",     // or "opencode", "codex", "pi"

  // Model override (falls back to workflow default)
  model: "claude-opus-4-6",

  // Thinking effort for this step
  thinkingEffort: "high",

  // Custom instructions appended to the step's system prompt
  instructions: "Focus on TypeScript type safety...",

  // Skills enabled for this persona
  selectedSkills: ["vitest-testing", "seo-integration"],

  // Whether to inject compiled learnings
  learningsEnabled: true,
}

Dettagli di esecuzione degli step

Record di run step

Ogni esecuzione di step crea un record nella tabella runSteps. Questo record traccia:

• runId - Riferimento al run genitore.
• sandboxId - La sandbox E2B usata per questo step.
• personaId - La persona che ha definito questo step.
• cliId - Lo strumento CLI usato (ad esempio, « claude »).
• modelId - Il modello IA usato (ad esempio, « claude-opus-4-6 »).
• iteration - A quale iterazione complessiva appartiene questo step.
• loopId - L’ID del gruppo di loop (se in un loop).
• loopIteration - L’iterazione all’interno del loop.
• role - Il tipo di step (designer, checker, evaluator, ecc.).
• status - pending, running, completed o failed.
• verdict - Verdetto del checker (pass/fail + feedback).
• qualityScores - Punteggi di qualità dell’evaluator (correctness, typeSafety, codeStyle, testCoverage, completeness, composite, thresholdResult). Popolato solo per gli step evaluator.
• startedAt / completedAt - Informazioni di timing.

Timeline degli step

La vista di dettaglio del run mostra una timeline visiva degli step che rappresenta ogni step come un nodo con il suo ruolo, status e durata. Cliccando su uno step si apre l’output della sua sandbox. La timeline rende facile tracciare il flusso di esecuzione, vedere quali iterazioni sono passate o fallite e identificare i colli di bottiglia.

Logica condizionale

Il sistema di workflow di CodeCourier usa un modello condizionale basato sui verdetti anziché una ramificazione if/else esplicita. Il verdetto pass/fail del checker è il punto di decisione principale:

• Pass - Continua verso il block successivo nella pipeline.
• Fail - Torna indietro e riprova (se entro i limiti di iterazione).
• Numero max di iterazioni raggiunto - Forza la continuazione indipendentemente dal verdetto.

Questo modello mantiene la configurazione del workflow semplice fornendo al contempo il loop di feedback necessario per il miglioramento iterativo della qualità.

Esecuzione parallela

All’interno di un singolo workflow run, gli step vengono eseguiti in sequenza - lo step 2 attende che lo step 1 si completi. Tuttavia, CodeCourier supporta l’esecuzione parallela a livello di run. Puoi avviare più run dello stesso workflow simultaneamente, ciascuno che lavora su un task diverso su una branch diversa. È così che funzionano le sprint chain - più sprint possono essere eseguiti in sequenza, ma gli step interni di ogni sprint sono sequenziali.