Claude Code in contesti reali — Azure DevOps

1. Cos'è Claude Code e perché esiste

Claude Code è un coding agent da terminale (con estensioni IDE) che vive nel tuo repo: legge i tuoi file, esegue comandi, lancia test, aggiorna il codice, apre PR. A differenza di un autocompletion tool, ragiona "a task", non "a token".

Le differenze rispetto a strumenti come Copilot standard sono tre:

• Loop agentico. Può iterare: scrivere, testare, correggere, ripetere.
• Long context. Legge decine di file rilevanti per un task, non solo quello aperto.
• Tool use esplicito. Ha permessi e confini chiari, non è un semplice chat layer.

Per Blulink, Claude Code ha senso come strumento per lavori a task: feature development, refactoring, debug di bug non banali, esplorazione di codice legacy, generazione di documentazione su moduli complessi.

2. Setup e prima sessione

Installazione

Claude Code è distribuito come pacchetto npm globale. Requisiti: Node.js LTS, un terminale moderno, accesso internet (via proxy aziendale se necessario).

npm install -g @anthropic-ai/claude-code

# verifica
claude --version

Autenticazione

Due vie principali:

• Account Anthropic diretto (via OAuth). Più semplice per pilot individuali.
• API key enterprise o integrazione via AWS Bedrock / GCP Vertex per scenari con DPA e data residency. La via corretta per il deploy aziendale Blulink.

Prima sessione

Entrare nella cartella del repo e avviare:

cd C:\Progetti\Blulink\mio-repo
claude

# Claude Code parte e mostra il prompt.
# Primo comando utile:
> analizza la struttura del repo e dimmi come è organizzato

In questa prima sessione l'agente legge il tree dei file, identifica stack, framework, test suite, pipeline. È il suo "onboarding" sul progetto.

3. Gestione del contesto e CLAUDE.md

Il singolo file più importante in un progetto con Claude Code è CLAUDE.md in root. È il posto dove codifichi il contesto persistente del progetto: tutto ciò che il modello deve sapere per essere utile senza doverglielo ripetere ogni volta.

Cosa mettere in CLAUDE.md

• Descrizione ad alto livello del progetto.
• Stack tecnologico (versioni comprese).
• Convenzioni di codice e nomi.
• Come eseguire build, test, linter.
• Struttura delle cartelle più importanti.
• Regole "dure": cosa non fare, cosa toccare solo con cautela.
• Lingua della documentazione (italiano per Blulink, quasi sempre).

# CLAUDE.md (esempio Blulink)

## Progetto
Microservizio di fatturazione B2B Blulink. Stack .NET 8, EF Core, xUnit.

## Build e test
- dotnet build
- dotnet test (tutti i test unitari devono passare)
- eseguire sempre i test prima di proporre un diff

## Convenzioni
- Lingua documentazione e commenti: italiano
- Naming classi: PascalCase; metodi: PascalCase; field privati: _camelCase
- Niente nuove dipendenze NuGet senza approvazione del tech lead

## Attenzione
- Le migration EF Core vanno in Migrations/ e vengono applicate solo dalla pipeline, mai a mano
- I file in src/Legacy sono in fase di decommissioning: non estendere, preferire refactoring

## Test
- Test unitari in test/*.Tests
- Test di integrazione in test/*.IntegrationTests (richiedono DB locale docker-compose up -d)

Contesto on-demand

Oltre al CLAUDE.md, il contesto di una singola sessione cresce man mano che l'agente legge file e esegue comandi. Il modello ha un budget di token: quando si avvicina al limite, è buona pratica avviare una nuova sessione per task non correlati, invece di "impilare" tutto nella stessa.

4. Pianificazione multi-step e plan mode

Plan mode

Claude Code ha un plan mode in cui l'agente pianifica le modifiche ma non le applica: produce una proposta di passi e la sottopone all'utente. L'utente approva, modifica, o rifiuta. Questa è la modalità di default per lavori "importanti".

Anatomia di un buon prompt per lavori a task

Devo implementare la validazione della PartitaIVA nella classe InvoiceValidator.

Contesto:
- la classe è in src/Validation/InvoiceValidator.cs
- le regole sono quelle italiane con check digit
- i test vanno in test/Validation.Tests/InvoiceValidatorTests.cs

Vincoli:
- niente nuove dipendenze
- firma pubblica dei metodi invariata
- copertura di test su: stringhe vuote, null, lunghezza sbagliata, check digit errato

Procedi in plan mode: analizza i file esistenti, proponi un piano,
poi aspettati la mia approvazione prima di scrivere.

Scomposizione multi-step

Per task grandi (feature cross-modulo, refactoring ampio), un buon pattern è chiedere esplicitamente: "dividimi questo lavoro in 5-8 passi piccoli e reversibili, ciascuno con un test che lo verifichi". Poi approvi uno step alla volta. È più lento all'apparenza, ma più veloce in pratica perché evita i rollback.

5. Tools, permessi e safety

Claude Code ha un insieme di tool predefiniti: leggere file, scrivere file, eseguire comandi shell, cercare nel codebase, gestire task list, chiamare tool esterni via MCP.

Permission model

Per default l'agente chiede conferma per operazioni potenzialmente distruttive: comandi shell, modifiche di file fuori dal repo, operazioni di rete. Per scenari di automazione esistono modalità con auto-approvazione di tool specifici (da usare con giudizio).

Le regole d'oro

• Lavora sempre su branch dedicate.
• Mai eseguire Claude Code in cartelle fuori repo (es. home, progetti non versionati).
• Leggi i diff proposti prima di committarli.
• I comandi distruttivi (git reset --hard, rm -rf, drop table) non devono mai essere auto-approvati.
• Evitare di passare segreti nei prompt: se serve l'accesso a un sistema, usare MCP server che legge credenziali dal secret manager.

6. MCP server e integrazioni

Il Model Context Protocol (MCP) è lo standard aperto che permette a un agente di collegarsi a tool esterni in modo uniforme. Un MCP server espone un set di tool e risorse; Claude Code può collegarcisi con una voce di configurazione.

Perché MCP conta

• Standard: lo stesso server funziona con Claude Code, Cursor, altri agent MCP-compatibili.
• Isolamento: il server vive in un processo separato, con le sue credenziali e i suoi confini.
• Ecosistema: esistono già MCP server per molte integrazioni comuni.

Configurazione tipica

// .mcp.json (versionato nel repo)
{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp-server"],
      "env": {
        "AZDO_ORG": "blulink",
        "AZDO_PAT": "${env:AZDO_PAT}"
      }
    },
    "filesystem-docs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Progetti/Blulink/docs"]
    }
  }
}

MCP server utili per Blulink

• Azure DevOps MCP — lettura/scrittura di work item, PR, pipeline.
• Filesystem MCP — accesso a cartelle specifiche fuori dal repo (es. cartella docs aziendale).
• Database MCP — interrogazione sicura di DB per analisi di dati in dev.
• HTTP/API MCP — accesso a API interne (staging only).

7. Subagents

Claude Code supporta subagents: configurazioni di agente specializzate che l'agente principale può invocare come se fossero tool di alto livello. Un subagent ha il suo system prompt, i suoi tool, il suo scope.

Esempi di subagent utili

• Explore — esplora il codebase per rispondere a domande, senza diritti di scrittura.
• Test Writer — scrive solo test, rispettando le convenzioni del progetto.
• Review — analizza un diff proposto e segnala problemi, senza modificare nulla.
• Doc Writer — genera documentazione in italiano rispettando il glossario aziendale.

Perché usarli

• Protezione del contesto principale. Lavori "di lettura" pesanti possono saturare il contesto. Un subagent li esegue in uno spazio proprio e restituisce solo il risultato.
• Specializzazione. Un subagent con prompt specifico è più affidabile di un agente generalista che fa tutto.
• Isolamento dei permessi. Il subagent "Review" non ha permessi di scrittura; non potrà mai committare per errore.

8. Integrazione con Azure DevOps

L'integrazione Blulink più naturale. Tre direttrici:

8.1 — Repos Git

Claude Code lavora con qualsiasi repo Git, quindi i repo Azure DevOps sono supportati nativamente. Il flusso tipico:

# clone del repo
git clone https://dev.azure.com/blulink/_git/mio-progetto
cd mio-progetto
git checkout -b feature/AB-1423-partita-iva

# avvio agente
claude

# lavoro a task con plan mode e test
# al termine:
git push --set-upstream origin feature/AB-1423-partita-iva
# Azure DevOps suggerirà automaticamente la creazione della PR

8.2 — Work items

Via MCP server Azure DevOps, l'agente può:

• Leggere un work item come fonte di specifica.
• Aggiornare lo stato, aggiungere commenti, linkare PR.
• Creare sub-task.

Un prompt utile:

Vai a leggere il work item AB-1423 via MCP.
Riassumine la specifica in 5 righe, identifica i file del repo
che andranno toccati, e proponi un piano di implementazione.
Aspetta la mia approvazione prima di scrivere codice.

8.3 — Pipeline

Per ogni task complesso, un agente può leggere lo YAML della pipeline per capire come il codice verrà eseguito in CI, rispettare gli stessi vincoli (linting, testing, packaging) e ridurre le sorprese al primo push.

Pattern consigliato per Blulink

1. Il tech lead crea il work item in Azure DevOps con specifica chiara.
2. Lo sviluppatore avvia Claude Code su una branch dedicata, punta al work item via MCP.
3. Plan mode: il piano viene discusso prima di toccare codice.
4. Implementazione step-by-step con test.
5. Push e apertura PR (manuale o con tool MCP).
6. Code review umana — eventualmente con review bot (modulo 6).

9. Code review assistita

Claude Code si può usare anche dall'altra parte della code review: un reviewer può avviare l'agente in read-only sulla branch della PR e chiedere un'analisi strutturata.

Sto facendo review di questa PR (branch feature/AB-1423-partita-iva).
Analizza il diff rispetto a main e dimmi:
- eventuali bug o edge case non coperti
- violazioni delle convenzioni di progetto (vedi CLAUDE.md)
- parti poco chiare che meriterebbero un commento di chiarimento
- test mancanti

Non modificare nulla. Voglio solo un report.

È un uso consultivo: aumenta l'attenzione del reviewer umano, non lo sostituisce.

10. Laboratorio pratico

Durante il corso, i partecipanti lavoreranno su casi concreti riutilizzabili. Esempi di laboratorio:

Lab 1 — Bootstrap di CLAUDE.md su un repo Blulink reale

Ciascun partecipante scrive un CLAUDE.md per un repo di sua proprietà, lo testa con una sessione di Claude Code, itera sulla qualità del risultato.

Lab 2 — Feature end-to-end in plan mode

Implementare una piccola feature con specifica chiara, dal work item Azure DevOps fino alla PR. Valutazione: pulizia del diff, test generati, qualità del piano proposto.

Lab 3 — Refactoring con caratterizzazione

Prendere un modulo legacy. Prima scrivere test di caratterizzazione con Claude Code, poi eseguire refactoring in step piccoli.

Lab 4 — MCP server Azure DevOps

Configurare MCP, leggere un work item, usarlo come input di un task, aggiornare lo stato a fine lavoro.

Lab 5 — Review assistita

Fare review di una PR di un altro partecipante usando Claude Code in read-only, confrontando i findings dell'agente con la review fatta "a mano".