Ruoli agente per app costruite via chat: workflow planner → reviewer

Perché l'affidabilità si spezza quando costruisci app via chat

La chat ti fa muovere in fretta, ma è pessima nel tenere l'intero prodotto in testa. La maggior parte dei fallimenti non è "codice cattivo": sono gap tra ciò che intendevi, ciò che l'assistente ha assunto e quel che è effettivamente stato rilasciato.

La prima crepa è la mancanza di requisiti. Chiedi "un semplice flusso di registrazione", ma nessuno scrive i casi limite come reset della password, email già usata o cosa succede se l'utente chiude la scheda a metà. L'assistente riempie gli spazi vuoti e quelle ipotesi diventano il prodotto.

La seconda crepa è la decisione incoerente. Un messaggio sceglie un modello dati, il successivo aggiunge una scorciatoia e un terzo cambia naming o regole di validazione. Ogni scelta può essere ragionevole da sola. Insieme, rendono l'app fragile e suscettibile a rotture quando aggiungi la prossima funzionalità.

La terza crepa è l'assenza di prove. Senza test di base e controlli di accettazione chiari, scopri i problemi solo dopo aver provato l'interfaccia. È allora che "funziona sul mio schermo" diventa notti insonni, hotfix e regressioni casuali.

Una soluzione semplice è usare persone riutilizzabili: un Planner che rende il lavoro concreto, un Architect che definisce la forma, un Implementer che costruisce a piccoli passi, un Tester che cerca di romperlo e un Reviewer che cattura quel 10% finale che causa il 90% del dolore. Non è un processo pesante. È un modo ripetibile per mantenere le decisioni coerenti.

Questo approccio funziona per founder solitari, piccoli team e creatori non tecnici che usano strumenti di chat come Koder.ai. Puoi comunque muoverti in fretta, ma smetti di contare sulla fortuna.

Questi ruoli non garantiscono magicamente la qualità. Hai comunque bisogno di input chiari (come si misura il successo, vincoli e priorità) e devi leggere gli output. Pensa ai ruoli come a guardrail: riducono errori evitabili, ma tu resti il guidatore.

L'idea centrale: separare responsabilità e fare handoff puliti

L'affidabilità cala quando una singola chat prova a fare tutto: decidere cosa costruire, disegnarlo, scrivere il codice, testarlo e giudicarlo. Mischiare questi lavori rende facile perdere casi limite, cambiare requisiti a metà o "fixare" bug aggiungendo confusione.

Un modo pratico per evitarlo è mantenere i ruoli coerenti e stretti. Ogni ruolo possiede un solo compito ed è proibito "aiutare" fuori da quel compito. Questo rende le decisioni tracciabili e gli errori più facili da trovare.

Usa questa sequenza per quasi ogni funzionalità:

• Planner: definire obiettivo, utenti, controlli di accettazione e cosa è fuori scope
• Architect: proporre il design più semplice che supporti l'obiettivo
• Implementer: costruire esattamente quanto pianificato, in piccoli passi
• Tester: cercare di romperlo e segnalare i fallimenti chiaramente
• Reviewer: controllare gli ultimi dettagli (naming, basi di sicurezza, gap UX, scorciatoie rischiose)

Gli handoff puliti contano quanto i ruoli. Ogni handoff dovrebbe includere cosa è stato deciso, quali assunzioni sono state fatte e cosa significa "done". Se usi Koder.ai, tratta ogni ruolo come un turno di chat o uno snapshot così puoi tornare indietro quando una decisione si rivela sbagliata.

Torna indietro con uno scopo, non per caso. Se i test fallano, torna dall'Implementer con un bug report minimale. Se il design non supporta un nuovo requisito, torna dall'Architect. Se il requisito è poco chiaro o cambia continuamente, metti in pausa e ritorna al Planner.

Mantieni gli stessi ruoli e lo stesso ordine tra le funzionalità. Dopo qualche iterazione costruisci memoria muscolare: fai domande migliori all'inizio e smetti di rifare lavoro alla fine.

Persona 1: Planner (rendere il lavoro chiaro prima che qualcuno costruisca)

Il compito del Planner è trasformare un'idea sfocata in qualcosa che puoi costruire e verificare. Non è "scrivere documentazione". È concordare cosa significa "fatto" prima che esista la prima schermata o endpoint API.

Un buon output del Planner resta piccolo e testabile: una frase problema chiara, alcune user story, criteri di accettazione semplici e una breve lista di edge case. Dice anche cosa non stai facendo ancora, così l'Implementer non costruisce accidentalmente una feature più grande di quella voluta.

Template prompt del Planner (piano piccolo e prioritizzato)

Usalo quando hai un'idea di feature e vuoi un piano stringato che gli altri ruoli possano seguire.

You are the Planner. Turn the feature idea below into a buildable plan.

Feature idea:
<PASTE IDEA>

Context:
- App type:
- Target users:
- Current behavior (if any):
- Constraints (time, data, compliance, devices):

Output (keep it short):
1) Problem statement (1-2 sentences)
2) Assumptions (3-6 bullets)
3) Questions to confirm (max 6, prioritized)
4) User stories (2-5)
5) Acceptance criteria (5-10, testable, specific)
6) Edge cases & failure modes (3-8)
7) Out of scope (3-6 bullets)
8) Small milestone plan (2-4 steps, highest value first)

Handoff Planner → Architect (strutturato e breve)

Invia questo messaggio così com'è (compilato) per ridurre il botta e risposta.

PLANNER HANDOFF
Feature: <name>
Problem: <1-2 sentences>
Users: <who>
Must-haves (AC): <5-10 acceptance criteria>
Key edge cases: <3-6>
Out of scope: <3-6>
Open questions (need Architect input): <1-4>
Constraints: <tech, data, privacy, deadlines>
Success signal: <how we’ll know it worked>

Se fai una sola cosa come Planner, rendi i criteri di accettazione misurabili. Per esempio: “L'utente riceve l'email di reset della password entro 60 secondi” è meglio di “Il reset della password funziona.”

Persona 2: Architect (scegliere una forma che l'app possa davvero supportare)

L'Architect trasforma un buon piano in una forma costruibile. Il lavoro non è inventare pattern complessi: è scegliere la struttura più semplice che funzioni quando gli utenti reali cliccano, i dati crescono e gli errori arrivano.

Qui l'affidabilità comincia a essere concreta: confini chiari, dati chiari e percorsi di fallimento definiti.

Un output pratico dell'Architect di solito include:

• Schermate (React o Flutter) o endpoint API (Go)
• Un piccolo modello dati (tabelle PostgreSQL e campi chiave)
• Uno o due flussi core (happy path più cosa può andare storto)
• Basi non funzionali che contano ora (auth, privacy, performance, logging)
• Tradeoff (cosa non stai costruendo ora)

Mantienilo concreto. Invece di "sistema di notifiche", dì "POST /api/alerts, tabella alerts(user_id, type, status), mostra contatore unread nell'header." Invece di "sicuro", dì "JWT session, controlli di ruolo sugli endpoint admin, proteggi i campi PII."

Template prompt: Handoff Architect (costringe a fare tradeoff)

Usalo quando il Planner passa lavoro all'Architect o quando vuoi resettare una feature che sembra disordinata.

You are the Architect.
Goal: design the simplest buildable structure for this feature.
Context:
- App type: [web/mobile/both]
- Stack: React UI, Go API, PostgreSQL DB (Flutter screens if mobile)
- Existing constraints: [auth method, existing tables, deadlines]

Input (from Planner):
- User story:
- Acceptance criteria:
- Out of scope:

Deliverables (keep it short and specific):
1) UI map: list screens/components with 1-line purpose each.
2) API map: list endpoints with method, path, request/response fields.
3) Data model: tables + key columns + relationships.
4) Key flows: happy path + 2 failure cases and how UI should respond.
5) Non-functional needs: security, performance, audit/logging (only what matters now).
6) Tradeoffs: 3 decisions you made (and what you avoided) to prevent over-design.

Rules:
- Prefer the smallest option that meets acceptance criteria.
- If something is unclear, ask up to 3 questions, otherwise make a reasonable assumption and write it down.

Se stai costruendo in Koder.ai, questo tipo di handoff rende l'implementazione più veloce perché l'Implementer può seguire una mappa chiara invece di indovinare la forma a metà sviluppo.

Persona 3: Implementer (costruire a piccoli passi, mantenere lo scope stretto)

L'Implementer trasforma un piano chiaro in codice funzionante, senza cambiare il piano. Qui si vince o si perde la maggior parte dell'affidabilità. L'obiettivo è semplice: costruire esattamente quanto concordato, in piccoli passi che puoi annullare.

Tratta ogni cambiamento come se potesse essere rollbackato. Lavora in fette sottili e fermati quando i criteri di accettazione sono soddisfatti. Se qualcosa è poco chiaro, chiedi. Indovinare è come le piccole feature diventano riscritture a sorpresa.

Un buon Implementer lascia una breve traccia di evidenza: ordine delle modifiche, cosa è cambiato, cosa non è cambiato (per evitare scope creep nascosto) e come verificare.

Ecco un template prompt che puoi incollare quando passi il lavoro all'Implementer:

You are the Implementer.

Context:
- Feature: <name>
- Current behavior: <what happens today>
- Desired behavior: <what should happen>
- Acceptance criteria: <bullets>
- Constraints: <tech choices, performance, security, no schema change, etc.>

Before writing code:
1) Ask up to 5 questions if anything is unclear.
2) Propose a step-by-step build plan (max 6 steps). Each step must be reversible.
3) For each step, list the exact files/modules you expect to touch.

Then implement:
- Execute steps one by one.
- After each step, summarize what changed and how to verify.
- Do not add extras. If you notice a better idea, stop and ask first.

Esempio: se il Planner ha chiesto “Aggiungi un flusso di reset password via email”, l'Implementer non dovrebbe anche ridisegnare la schermata di login. Costruisci l'endpoint per la richiesta email, poi la gestione del token, poi l'interfaccia, con una breve nota di verifica dopo ogni passo. Se lo strumento supporta snapshot e rollback (Koder.ai lo fa), i piccoli passi diventano molto più sicuri.

Persona 4: Tester (dimostrare che funziona e mostrare come fallisce)

Il compito del Tester è rompere la feature prima che lo facciano gli utenti. Non si fida dell'happy path. Cerca stati poco chiari, validazioni mancanti e edge case che emergono al giorno uno.

Un buon output del Tester è utilizzabile da altri: una matrice di test legata ai criteri di accettazione, uno script manuale breve e report di bug con passi esatti (expected vs actual).

Cosa testare (UI, API e dati)

Punta alla copertura, non al volume. Concentrati dove i fallimenti costano di più: validazione, permessi e stati d'errore.

• UI: stati vuoti, messaggi di errore, stati di caricamento, pulsanti disabilitati, flusso solo tastiera
• API: campi mancanti, tipi sbagliati, fallimenti di auth, comportamento in caso di rate/timeout
• Validazione dati: duplicati, lunghezze massime, formati non validi, controlli lato server (non solo UI)
• Permessi: cosa può fare un utente normale vs admin
• Regressione: uno o due controlli “abbiamo rotto comportamento esistente?”

Esempio: se hai aggiunto “Crea fattura”, prova un importo negativo, una nota di 10.000 caratteri, un cliente mancante e un doppio click sul submit.

Template prompt: genera una matrice di test dai criteri di accettazione

Usalo quando passi da Implementer a Tester. Incolla i criteri di accettazione e le note UI/API rilevanti.

ROLE: Tester
GOAL: Produce a test matrix tied to acceptance criteria, including negative tests.
CONTEXT:
- Feature: <name>
- Acceptance criteria:
  1) <AC1>
  2) <AC2>
- Surfaces: UI screens: <list>; API endpoints: <list>; DB changes: <notes>
OUTPUT FORMAT:
1) Test matrix table with columns: AC, Test case, Steps, Expected result, Notes
2) Negative tests (at least 5) that try to break validation and permissions
3) Manual test script (10 minutes max) for a non-technical person
4) Bug ticket template entries for any failures you predict (Title, Steps, Expected, Actual, Severity)
CONSTRAINTS:
- Keep steps precise and reproducible.
- Include at least one test for loading/error states.

Persona 5: Reviewer (catturare l'ultimo 10% che causa il 90% del dolore)

Il Reviewer è la passata finale di qualità. Non per riscrivere tutto, ma per individuare i piccoli problemi che poi diventano bug lunghi: nomi confusi, edge case mancanti, messaggi d'errore deboli e scorciatoie rischiose che rendono più difficile la prossima modifica.

Una buona review produce output chiari: cosa è stato controllato, cosa deve cambiare, cosa è rischioso ma accettabile e quale decisione è stata presa (così non viene riaperta la questione la settimana dopo).

Cosa cerca il Reviewer

Mantieni la passata breve e ripetibile. Concentrati sulle cose che spesso rompono l'affidabilità:

• Coerenza: naming, pattern, struttura cartelle e comportamento UI coerenti con l'app esistente
• Nozioni di sicurezza: validazione input, controlli auth, niente dati sensibili nei log
• Errori: messaggi per l'utente chiari; errori server azionabili; niente failure silenziosi
• Manutenibilità: funzioni piccole, intenti ovvi, nessuna logica duplicata senza motivo
• Modifiche future: cosa sarà difficile da modificare dopo e come ridurre quel costo ora

Template review strutturata (approva o richiedi cambiamenti)

Usa questo handoff quando l'Implementer dice che la feature è pronta:

You are the Reviewer. Do a final review for correctness, clarity, and maintainability.

Context
- Feature goal:
- User flows:
- Key files changed:
- Data model/migrations:

Review checklist
1) Correctness: does it meet the goal and handle edge cases?
2) Security basics: auth, validation, safe logging.
3) Errors: clear messages, consistent status codes.
4) Consistency: naming, patterns, UI text.
5) Maintainability: complexity, duplication, TODOs.

Output format
- Findings (bulleted): include file/function references and severity (high/medium/low)
- Requested changes (must-fix before merge)
- Risk notes (acceptable with reason)
- Decision log updates (what we decided and why)

Finish with exactly one:
APPROVE
CHANGES REQUESTED

Se il Reviewer richiede modifiche, devono essere piccole e specifiche. L'obiettivo è meno sorprese in produzione, non un secondo ciclo di sviluppo.

Template di handoff che prevengono il rifacimento

La maggior parte del rifacimento avviene perché la persona successiva parte da un obiettivo vago, input mancanti o vincoli nascosti. Un semplice template di handoff risolve tutto rendendo ogni trasferimento prevedibile.

Usa sempre un'intestazione condivisa, anche per task piccoli:

• Context + Goal: cosa stai costruendo e perché, in un paragrafo.
• Inputs: schermate, note API, campi dati, record di esempio, aree di codice correlate.
• Constraints: scelte tech, scadenze, performance, sicurezza, comportamenti da mantenere.
• Definition of Done: controlli misurabili (cosa deve passare, cosa deve esistere).
• Assumptions / Open questions / Decisions made: cosa hai assunto, cosa è sconosciuto e cosa hai deciso.

Ecco un singolo esempio di handoff (Architect → Implementer):

ROLE HANDOFF: Architect -> Implementer
Context: Add “Invite team member” to the admin area.
Goal: Admin can send an invite email; invited user can accept and set a password.
Inputs: Existing Users table; auth uses JWT; email provider already configured.
Constraints: Go backend + PostgreSQL; React UI; audit log required; no breaking auth changes.
Definition of Done:
- UI: invite modal + success state
- API: POST /invites, POST /invites/accept
- DB: invites table with expiry; audit event on create/accept
- Tests: happy path + expired invite + reused token
Assumptions: Email templates can reuse “reset password” styling.
Open questions: Should invites be single-use per email?
Decisions made: 72h expiry; tokens stored hashed.

Se vuoi che questo approccio duri, conserva i tuoi template dove tutti possano copiarli. Se usi Koder.ai, tieni questi prompt in Planning Mode e scatta uno snapshot prima dell'implementazione così il rollback è indolore se lo scope cambia.

Workflow passo-passo che puoi seguire per ogni feature

L'affidabilità migliora quando tratti ogni feature come una mini-release, con handoff puliti tra ruoli. Parti da una user story, non da una pila di idee. Scrivila in linguaggio semplice, poi aggiungi criteri di accettazione che qualcuno può verificare senza indovinare.

Progetta solo la forma minima necessaria per supportare quella story. L'obiettivo non è un sistema perfetto, ma un piano semplice che non crolli quando aggiungi la prossima feature.

Un flow pratico è questo:

1. Planner: conferma user story, edge case e criteri di accettazione (successo, fallimento e “e se l'utente fa X”).
2. Architect: proponi il più piccolo modello dati e superficie API (tabelle/campi, endpoint, regole auth), più una breve nota su cosa non stai costruendo.
3. Implementer: costruisci una singola fetta sottile end-to-end (UI → API → DB) che soddisfi i criteri, anche con UI essenziale.
4. Tester: esegui uno script di test ripetibile, registra i fallimenti con passi per riprodurre e segnala comportamenti poco chiari.
5. Reviewer: passa finalemente per le basi di sicurezza e rifinitura prodotto, poi registra le decisioni.

Mantieni l'output di ogni step piccolo ed esplicito. Un messaggio di handoff per ruolo è di solito sufficiente: input, decisioni prese e cosa ti serve dopo.

Concludi scrivendo una nota di cambiamento in un paragrafo: cosa è stato aggiunto, cosa è stato rimosso e cosa monitorare nella prossima release. Questa "memoria" evita che gli stessi argomenti e bug ritornino.

Un esempio realistico: una feature dall'idea al rilascio revisionato

Feature: una schermata CRM semplice dove gli utenti possono aggiungere contatti, applicare tag (come “Lead” o “Vendor”) e cercare per nome o tag. Vincolo: hai 90 minuti e devi riusare la tabella contacts esistente (niente migrazioni breaking). Mobile richiede una singola schermata “Aggiungi contatto” che stia su una pagina.

Ecco come appare l'handoff quando usi questa catena di persona. Ogni ruolo produce un piccolo artefatto su cui il successivo può fidarsi.

Planner output (definition + acceptance)
- Goal: Add contacts with tags and fast search.
- Must: Create, edit, list contacts; add/remove tags.
- Search: matches name OR any tag; results update in under 300ms.
- Constraint: keep existing contacts table; tags can be new table.
- Done when: 5 test cases pass; mobile screen has no scroll on common devices.

Architect output (shape + data)
- Tables: contacts (existing), tags (id, name), contact_tags (contact_id, tag_id).
- API: POST /contacts, PATCH /contacts/:id, GET /contacts?query=.
- Search: SQL ILIKE on contact name + join on tags.
- UI: Contact list with search bar; contact form with tag picker.
- Risk: duplicate tags (“lead” vs “Lead”) - enforce lowercase unique.

Implementer output (small steps)
- Step 1: Add tags + join table migrations.
- Step 2: Update backend handlers and query.
- Step 3: Build React UI list + form; wire to API.
- Step 4: Add basic validation (name required, tag length).
- Step 5: Add loading/error states; keep UI responsive.

Tester output (proof + failure)
- Case: search “lea” returns contacts tagged “lead”. FAIL: returns none.
- Case: adding tag “Lead” then “lead” should not create two tags. PASS.
- Case: empty name rejected. PASS.
- Bug note: backend search only checks contact name, not tags.

Loop-back (Planner update)
- Update acceptance: search must match tags via join; include a test for it.
- Add edge case: searching by tag should return even if name doesn’t match.

Reviewer output (last 10%)
- Check: query uses indexes; add index on tags.name and contact_tags.tag_id.
- Check: error messages are clear; avoid raw SQL errors.
- Check: mobile form spacing and tap targets.
- Confirm: snapshots/rollback point created before release.

Quel singolo test fallito forza un loop-back pulito: il piano diventa più chiaro, l'Implementer cambia una query e il Reviewer valida performance e rifinitura prima del rilascio.

Trappole comuni (e semplici correzioni)

Il modo più veloce per perdere fiducia nel software costruito via chat è permettere a tutti di fare tutto. Ruoli chiari e handoff puliti mantengono il lavoro prevedibile, anche se ti muovi veloce.

• Persona confuse (si costruisce prima che i requisiti siano stabili). Correzione: blocca l'output del Planner prima di qualsiasi modifica al codice. Suggerimento template: “Implementer: non scrivere codice finché Scope, Assunzioni e Criteri di Accettazione del Planner non sono presenti. Se mancano, fai al massimo 3 domande.”
• Nessuna Definition of Done, quindi il lavoro non finisce mai. Correzione: ogni handoff deve includere una linea Done. Esempio: “Done significa: criteri di accettazione passati, nessun nuovo TODO e modifiche documentate in 5 punti.”
• Tester controlla solo l'happy path. Correzione: richiedere sempre un caso di input non valido e un edge case. Template: “Tester: fornisci (1) happy path, (2) un input non valido, (3) un edge case. Se non puoi eseguirlo, descrivi passi e output atteso.”
• Reviewer discute stile invece di rischio prodotto. Correzione: obbliga il Reviewer a concentrarsi prima sul rischio. Template: “Reviewer: elenca i primi 3 rischi (sicurezza, perdita dati, UX rotta, performance). Meniona lo stile solo se blocca leggibilità o causa bug.”
• Handoff privi di contesto, quindi il ruolo successivo indovina. Correzione: richiedere sempre un Handoff Block corto: “Goal, What changed, How to verify, Known gaps.” Tienilo sotto 8 righe.

Un'abitudine utile: quando l'Implementer finisce, incolla di nuovo i criteri di accettazione e spuntali uno per uno.

Checklist rapida per rilasci affidabili costruiti via chat

Esegui questa checklist prima di buildare, prima di fare merge e subito dopo il rilascio.

Prima della build (prima che qualcuno scriva codice)

• Scrivi l'obiettivo in una frase e elenca 2-3 check di accettazione (cosa significa "fatto").
• Nomina cosa è fuori scope (così l'Implementer non indovina).
• Elenca i campi dati esatti e le regole (tipi, obbligatori/opzionali, default).
• Annota i principali casi d'errore (input errato, permessi mancanti, stati vuoti, timeout).
• Decidi come verificherai rapidamente (una schermata, una risposta API, una riga di log).

Un piccolo esempio: “Aggiungi invito via email.” Includi campi (email, ruolo), cosa succede se l'email è invalida e se si permettono reinvii.

Pre-merge e post-release (ridurre la paura del cambiamento)

• Pre-merge: conferma che i test sono stati eseguiti (o almeno uno script manuale) e registra cosa è stato controllato.
• Pre-merge: copri 2-3 edge case esplicitamente, non “dovrebbe funzionare”.
• Pre-merge: annota un piano di rollback e quale cambiamento lo triggererebbe.
• Post-release: monitora 1-2 segnali (errori, pagine lente, job falliti) per la prima ora/giorno.
• Post-release: raccogli feedback utenti e annota limiti noti così il supporto non indovina.

Se la tua piattaforma lo supporta (Koder.ai lo fa), scatta uno snapshot prima delle modifiche rischiose. Sapere di poter tornare indietro rende più facile rilasciare piccoli cambiamenti sicuri.

Prossimi passi: rendilo il tuo workflow predefinito

Scegli una piccola feature e segui l'intera catena di persona una volta. Scegli qualcosa di reale ma contenuto, come “aggiungi reset password”, “crea una pagina admin-only” o “esporta fatture in CSV”. L'obiettivo è vedere cosa cambia quando forzi handoff puliti da Planner a Reviewer.

Se usi Koder.ai (koder.ai), Planning Mode è il posto pratico per bloccare scope e criteri di accettazione prima di costruire. Poi snapshot e rollback ti danno un'uscita sicura quando una decisione si rivela sbagliata, senza trasformare tutto il progetto in una discussione.

Per rendere il workflow ripetibile, salva i prompt persona come template che il team può riutilizzare. Tienili corti, mantieni formati di output coerenti e passerai meno tempo a ri-spiegare lo stesso contesto per ogni feature.