In questo articolo

📐 Cos'è il pattern staff-engineer

Un staff engineer non scrive tutto il codice. Guida la scoperta, stabilisce l'architettura, scompone il lavoro in atomic task, e orchestra agenti specializzati che eseguono con precisione. Ogni fase ha una gate—niente procede al livello seguente senza approval esplicita.

Il repo claude-code-staff-engineer incapsula questo come:

  • Hooks (management layer): Context initialization a session start, injection della employee handbook
  • Skills (employee handbook): Brainstorming, TDD Iron Law, debugging forensico, delegation, review
  • Agents (team roster): Implementer, spec reviewer, code quality reviewer, peer reviewer
  • Commands & sub-agents: Specialized workers per task, con isolation di context

🔧 Come si usa: Setup e Structure

La struttura del progetto mappa a funzioni vere di un team di ingegneria. Ogni cartella rappresenta un ruolo, un processo, o un ciclo di vita.

Quando una sessione inizia, un hook carica automaticamente la Employee Handbook. Questo file contiene il principio non negoziabile: il 1% Rule.

  • 1% Rule: Se pensi che c'è anche solo l'1% di possibilità che uno skill si applichi, DEVI invocarlo. Non è opzionale.
  • TDD Iron Law: Niente production code senza test failing FIRST. Se scrivi codice prima del test: DELETE, ripeti.
  • Explicit Approval Gates: Ogni fase ha sign-off umano. Non "nessuno ha obiettato" (implicit approval). "Ho revisionato, è OK" (explicit approval).

📋 La Pipeline di Fasi

Ogni progetto segue una pipeline rigida. Non ci sono scorciatoie, non ci sono "task piccoli che saltano review."

  • 1. Brainstorming & Design (discovery skill): Scope detection, proposte di 2–3 approcci con trade-off, niente codice finché design è approvato
  • 2. Spec Review (sub-agente reviewer): Agente fresco audita il design; cerca completeness, consistency, clarity
  • 3. Planning & Backlog Grooming (writing-plans skill): Break design in 2–5 minute tasks, file paths esatti, niente TBD
  • 4. Plan Review (sub-agente reviewer): Verifica che un engineer potrebbe seguire il plan senza rimanere bloccato
  • 5. Execution per Task (delegation skill): Dispatch sub-agente isolato, fresh context, zero session history
  • 6. Quality Gates—due review seriali: Spec Compliance (costruiamo la cosa giusta?) + Code Quality (la costruiamo bene?)
  • 7. TDD Iron Law (tdd-discipline skill): Red (test fails) → Green (minimal code) → Refactor. NO eccezioni.
  • 8. Verification & Sign-off (evidence-verification skill): Terminal output che lo prova, fresh run, deployment check

💡 Perché è interessante per PME e Dev Team

Il pattern risolve il problema centrale: ogni agente tende verso "ship it" senza discipline. Con questo framework, nessuna razionalizzazione è possibile.

  • Per i Team di Sviluppo: Nessuna razionalizzazione possibile. Review segregate (spec reviewer ≠ code reviewer ≠ implementer). TDD enforced come iron law. Isolation di context per sub-agenti.
  • Per le PME: Scala senza chaos. Hooks & skill onboarding automatico. Separation of concerns. Skills riusabili (brainstorming, TDD, debugging). Audit trail committato in git—compliance e accountability built-in.

🎯 Elementi chiave del pattern

Tre regole fondamentali che nessun agente può razionalizzare:

  • Il 1% Rule: Skill discovery PRIMA di qualsiasi azione. Anche una "semplice domanda" potrebbe beneficiare di uno skill.
  • TDD Iron Law: Niente production code senza test failing FIRST. Se scrivi codice prima del test: DELETE.
  • Explicit Approval Gates: Ogni fase ha sign-off umano esplicito. Non implicit approval.

📊 Model Selection per Task Complexity

Non tutti i compiti richiedono il best model. Lo skill subagent-driven-development insegna:

  • Mechanical tasks (funzioni isolate, spec chiaro): cheap/fast model
  • Integration tasks (coordinazione multi-file): standard model
  • Architecture/review tasks: best model disponibile

🚀 Casi d'Uso Reali

Caso 1: Feature Complessa in Startup

Una PME vuole aggiungere un sistema di payment con webhook, idempotency checks, conciliation async. Senza il pattern: razionalizzazione, test saltati, vulnerabilità. Con il pattern: brainstorming → design doc → plan dettagliato → spec review → isolation task execution → dual review → TDD verify → sign-off.

Tempo: +20% per il rigor, ma -80% debugging post-launch.

Caso 2: Refactoring Rischioso

Team vuole spostare 5k LOC da file monolitico a moduli. Con il pattern: brainstorming (goal: mantenibilità, testabilità) → design (dependency graph, module boundaries) → plan (atomic task: move file, update import, test, commit) × 5 → review step-by-step → zero runtime issues.

⚖️ Critiche e Limitazioni

Il pattern non è silver bullet:

  • Overhead iniziale: Per feature tiny, la pipeline è overkill. (Soluzione: skill check decida scalabilità.)
  • Token/cost: Sub-agenti, multiple reviewer rounds, TDD test output—consume più token. (Soluzione: model selection per task complexity.)
  • Human judgment: Sign-off gates richiedono umani nel loop. Non è "set it and forget it." (Soluzione: il punto è questo—garantisce human control.)

✅ Conclusione

Il pattern staff-engineer non è un'architettura tecnica. È una governance structure per agenti AI, replicando come team umani maturi operano:

Separate discovery (thing worth building?) from implementation (build it well?). Formalize review come parte del processo, non afterthought. Enforce TDD come iron law. Escalate blocchi, non force brute retry. Document design & plan in git, non solo conversation.

Per chi usa Claude Code per lavoro serio—feature production, PME governance, startup scaling—questo è il template che copia.

Domande frequenti su claude-code-staff-engineer

Il pattern staff-engineer è solo per grandi team?

No. È scalabile. Per feature piccole, alcuni passaggi della pipeline possono essere condensati o affidati a skill autom atici che decidono se saltare fasi. Per feature critiche o team distribuiti, tutti i 8 step sono obbligatori. L'idea è che il rigor sia proporzionale al rischio, non alla dimensione del team.

Come si bilancia il rigor con la velocità?

Il pattern aggiunge ~20% di tempo grazie al rigor, ma elimina -80% di debugging post-launch e di cicli di review manuali. È un trade-off consapevole: privilegia la qualità e la accountability del codice alla velocità grezza.

Posso usare il pattern anche senza Claude Code?

Il pattern è agnostico dal modello. È replicabile con Copilot, Cursor, Gemini o qualsiasi agente capace di usare skill e sub-agent. Il repo FareedKhan-dev/claude-code-staff-engineer è specificamente per Claude Code, ma la struttura (brainstorming, spec review, plan review, execution, dual review, TDD, verification) vale ovunque.

Parliamone

Se questo tema ti riguarda, scrivimi: confrontarsi su codice e AI è sempre tempo speso bene.