Passa al contenuto principale

AI-Assisted Development con Claude Code

Emblema sfrutta intensivamente Claude Code per un approccio di sviluppo innovativo che integra l'intelligenza artificiale in ogni fase del ciclo di vita del software. Questo documento descrive la metodologia "AI-First Development" e il workflow strutturato che utilizziamo.

🎯 Filosofia: AI-First Development​

L'approccio di sviluppo di Emblema si basa sul principio che l'AI non è solo uno strumento, ma un partner collaborativo nel processo di sviluppo. Ogni feature, refactoring e miglioramento passa attraverso un workflow strutturato che combina intelligenza umana e artificiale.

Benefici dell'Approccio AI-First​

  • 🧠 Analisi Approfondita: L'AI aiuta a esplorare soluzioni alternative e edge cases
  • 📋 Pianificazione Dettagliata: Piani di implementazione strutturati e documentati
  • ⚡ Sviluppo Accelerato: Codice generato seguendo patterns e best practices consolidate
  • 🔍 Quality Assurance: Review automatiche e suggerimenti di miglioramento
  • 📚 Documentazione Automatica: Aggiornamento documentazione basato sui cambiamenti del codice

🔄 Il Workflow: Think → Plan → Code → Review → Document​

Il nostro processo di sviluppo segue un workflow strutturato in 5 fasi, ognuna supportata da comandi Claude Code specializzati.

Loading diagram...

📁 Struttura Comandi Claude Code​

Tutti i comandi sono organizzati in .claude/commands/ per standardizzare il workflow:

.claude/
└── commands/
    ├── think.md      # Fase di brainstorming
    ├── plan.md       # Pianificazione dettagliata
    ├── code.md       # Implementazione
    ├── review.md     # Code review
    └── doc-it.md     # Documentazione automatica

🧠 Fase 1: Think - Brainstorming Collaborativo​

Comando: /think [descrizione problema]

Obiettivo: Esplorare il problema, analizzare alternative, identificare requisiti e vincoli.

Contenuto Comando​

Don't code, think with me, #$ARGUMENTS
Any suggestions are welcome.

Quando Utilizzare​

  • Nuove feature complesse
  • Refactoring architetturali
  • Risoluzione problemi tecnici
  • Valutazione alternative tecnologiche

Output Tipico​

  • Analisi del problema da multiple prospettive
  • Identificazione di edge cases
  • Valutazione pro/contro di approcci alternativi
  • Definizione requisiti tecnici e di business

Esempio di Utilizzo​

/think Dobbiamo migliorare il sistema di chunking per supportare meglio i file audio con speaker diarization. Il problema attuale è che perdiamo informazioni sui speaker quando rechunkiamo.

📋 Fase 2: Plan - Pianificazione Strutturata​

Comando: /plan [specifiche del progetto]

Obiettivo: Creare un piano di implementazione dettagliato con TODO strutturati e specifiche tecniche.

Contenuto Comando​

#$ARGUMENTS . Don'd code yet, based on the conversation, please create or update a summary of full plan, then create or update our TODO plan and for each TODO item you must create also a md file to describe the implementation details, you must save these todo md files into todo folder in the project root.

Processo di Planning​

  1. Summary del Piano: Visione d'insieme dell'implementazione
  2. TODO List Strutturata: Breakout in task atomici e sequenziali
  3. File di Specifica: Dettagli implementativi per ogni TODO in /todo/

Struttura File TODO​

todo/
├── 01-analizzare-struttura-doc-emblema.md
├── 02-struttura-cartelle-platform.md
├── audio-chunking-refactor-plan.md
├── audio-refactor-1-segment-creation.md
├── audio-refactor-2-profile-token-calculation.md
└── ...

Template File TODO​

# TODO: [Nome Task]

## Obiettivo

Descrizione chiara di cosa deve essere implementato

## Prerequisiti

- Dipendenze da altri TODO
- Prerequisiti tecnici

## Implementazione

### Step 1: [Azione]

- Dettaglio implementativo
- File da modificare
- Funzioni da creare/modificare

### Step 2: [Azione]

- ...

## Criteri di Accettazione

- [ ] Criterio 1
- [ ] Criterio 2
- [ ] Test passano
- [ ] Documentazione aggiornata

## Note Tecniche

Considerazioni specifiche, pattern da seguire, vincoli

Esempio di Utilizzo​

/plan Implementare sistema di re-chunking per file audio che preservi le informazioni di speaker diarization e permetta strategie di chunking flessibili

⚡ Fase 3: Code - Implementazione Guidata​

Comando: /code [focus specifico]

Obiettivo: Implementare seguendo rigorosamente i piani e le specifiche create nella fase precedente.

Contenuto Comando​

Based on the conversation decision and TODO list we have in plan, in todo folder of the project we have implementation detail, you **MUST** follow that, now let's go with coding. Before you start any todo item, you must read the corrispondent todo md file to update the context. #$ARGUMENTS

Processo di Coding​

  1. Lettura TODO: Carica il file di specifica corrispondente
  2. Analisi Context: Comprende dipendenze e prerequisiti
  3. Implementazione: Segue step-by-step le specifiche
  4. Validazione: Verifica criteri di accettazione

Best Practices​

  • Mai codificare senza piano: Sempre riferimento a file TODO
  • Un TODO alla volta: Focus su singolo task atomico
  • Seguire pattern esistenti: Consistency con codebase
  • Test immediati: Validazione durante implementazione

Esempio di Utilizzo​

/code Implementa il primo step del refactoring audio chunking: creazione struttura segments

🔍 Fase 4: Review - Quality Assurance AI​

Comando: /review [scope della review]

Obiettivo: Analisi qualitativa del codice implementato con focus su sicurezza, performance e maintainability.

Contenuto Comando​

Have the code-reviewer subagent look at my recent changes. #$ARGUMENTS

Aree di Review​

  1. Code Quality: Leggibilità, maintainability, pattern
  2. Security: Vulnerabilità, best practices sicurezza
  3. Performance: Ottimizzazioni, bottlenecks potenziali
  4. Architecture: Consistency con design patterns
  5. Testing: Coverage e quality dei test

Specialized Code-Reviewer Agent​

Il comando utilizza un agente specializzato che:

  • Analizza gli ultimi cambiamenti
  • Applica best practices specifiche del progetto
  • Suggerisce miglioramenti
  • Identifica potenziali problemi

Esempio di Utilizzo​

/review Ho appena implementato il nuovo sistema di chunking audio, controlla la sicurezza e performance

📚 Fase 5: Document - Documentazione Automatica​

Comando: /doc-it

Obiettivo: Aggiornamento automatico della documentazione basato su cambiamenti nel codice.

Contenuto Comando​

We have the documentation project in apps/doc-emblema, based on the pr of the current branch to develop, analyze the pr changes by using git command and update the documentation. Firstly update the changelogs in the developer section, then if necessary update the platform section, user manual section and api section. The date should be picked from the commit or pr and the version should be picked from the package.json. If you don't find any pr from current branch to develop, just ignore the request. #$ARGUMENTS

Processo di Documentazione​

  1. Analisi PR: Identifica cambiamenti tramite git diff
  2. Update Changelog: Aggiornamento automatico changelog sviluppatori
  3. Sezioni Platform: Modifiche architetturali e infrastruttura
  4. Manuale Utente: Nuove funzionalità utente
  5. API Documentation: Modifiche alle API

Intelligenza Automatica​

  • Date Extraction: Da commit/PR reali
  • Version Detection: Da package.json
  • Change Classification: Categorizzazione automatica modifiche
  • Cross-Reference: Linking tra sezioni correlate

Esempio di Utilizzo​

/doc-it Analizza le modifiche nel branch feature/audio-chunking e aggiorna la documentazione

🛠️ Implementazione Pratica​

Setup Iniziale​

  1. Installazione Claude Code:

    # Installa Claude Code CLI
    npm install -g @anthropics/claude-code

    # Configura autenticazione
    claude auth

  2. Configurazione Progetto:

    # Inizializza Claude Code nel progetto
    cd emblema
    claude init

    # I comandi sono già configurati in .claude/commands/

Workflow Quotidiano​

# 1. THINK - Brainstorming nuovo feature
/think Voglio implementare export PDF per conversazioni chat

# 2. PLAN - Pianificazione dettagliata
/plan Crea plan completo per export PDF chat con template personalizzabili

# 3. CODE - Implementazione step-by-step
/code Inizia implementazione primo TODO: setup PDF generation service

# 4. REVIEW - Quality assurance
/review Analizza il servizio PDF appena implementato

# 5. DOCUMENT - Aggiorna documentazione
/doc-it Aggiorna docs per nuova funzionalità export PDF

Integrazione con CI/CD​

# .github/workflows/ai-quality-check.yml
name: AI Quality Check

on: [pull_request]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: AI Code Review
        run: |
          claude /review "Analizza le modifiche in questo PR per quality, security e performance"

      - name: Update Documentation
        run: |
          claude /doc-it "Aggiorna documentazione basata sui cambiamenti del PR"

📊 Metriche e Benefici​

Metriche di Sviluppo​

  • Tempo di Development: -40% rispetto a sviluppo tradizionale
  • Code Quality: +60% meno bug in produzione
  • Documentation Coverage: 95% sempre aggiornata
  • Planning Accuracy: +80% stime più precise

ROI dell'AI-Assisted Development​

  1. Velocità: Sviluppo 2-3x più rapido
  2. Qualità: Meno bug, code review più approfondite
  3. Documentazione: Sempre sincronizzata con codice
  4. Onboarding: Nuovi sviluppatori produttivi immediatamente
  5. Knowledge Transfer: Piani dettagliati come documentazione

🎯 Best Practices​

DO - Pratiche Raccomandate​

✅ Sempre iniziare con /think per problemi complessi ✅ Creare TODO dettagliati prima di codificare ✅ Un commit per TODO per tracciabilità
✅ Review obbligatorio prima del merge ✅ Documentazione automatica per ogni PR

DON'T - Da Evitare​

❌ Non saltare la fase planning per "risparmiare tempo" ❌ Non modificare file TODO durante implementazione ❌ Non ignorare suggerimenti review senza valutazione ❌ Non fare merge senza aggiornamento documentazione

🔮 Evoluzione Futura​

Prossimi Miglioramenti​

  1. AI Testing: Generazione automatica test cases
  2. Performance Monitoring: Analisi automatica performance
  3. Security Scanning: Review sicurezza integrate
  4. Architecture Evolution: Suggerimenti migliorativi architettura

Estensioni Workflow​

/test     # Generazione automatica test
/deploy   # Deployment automatico con validazioni
/monitor  # Setup monitoring per nuove feature
/optimize # Analisi e ottimizzazioni performance

🆘 Troubleshooting​

Problemi Comuni​

Q: Il comando /plan non crea file TODO

  • Verificare permessi scrittura cartella /todo
  • Controllare che il prompt abbia abbastanza contesto

Q: /doc-it non trova cambiamenti

  • Verificare di essere su branch corretto
  • Controllare che ci siano commit da analizzare

Q: Code review troppo generiche

  • Specificare focus: /review sicurezza o /review performance
  • Fornire contesto specifico del cambiamento

Supporto e Community​

  • Internal Chat: Canale #ai-development su Slack
  • Documentation: Questa pagina viene aggiornata automaticamente
  • Feature Requests: Issues su GitHub con tag ai-workflow

Nota: Questo approccio è in continua evoluzione. Ogni miglioramento al workflow viene documentato automaticamente tramite /doc-it.

Ultima revisione: Agosto 2025
Versione workflow: 2.0
AI Model: Claude-3.5-Sonnet

Questa pagina ti è stata utile?