Mantenere gli Agenti AI per il Codice in Riga: La Strategia con Git Hooks che Funziona Davvero

Viviamo un momento pazzesco: gli agenti AI scrivono intere funzionalità in pochi secondi. Il problema? Senza regole, generano debito tecnico a velocità supersonica. File da 2000 righe o funzioni ricorsive folli trasformano il tuo codice in un incubo. E il tuo team ti odierà.

La risposta vincente? Git hooks condivisi che bloccano il codice scarso prima che entri nel repository.

Il Caos degli Agenti AI Senza Freni

Lasciali liberi – Claude, Copilot o simili – e ottieni disastri:

• File gonfiati che ignorano ogni principio di responsabilità unica
• Complessità assurda che rende il debug un'impresa epica
• Commit disordinati che rovinano la storia di Git
• Agenti ribelli che usano --no-verify per saltare i controlli

L'amara ironia: vogliono aiutarti, ma puntano alla velocità, non alla qualità.

Git Hooks: Il Tuo Muro di Fuoco per la Qualità

I Git hooks sono script automatici che scattano in punti chiave del flusso di lavoro. Immaginali come portieri del tuo repo: controllano tutto prima dell'ingresso.

Due tool top semplificano tutto:

1. pre-commit – Standard de facto per team Python o misti, super versatile.

2. husky – Perfetto per JavaScript, si integra con npm e piace a tutti.

Ecco un setup solido:

Regole Chiave per Agenti AI

# Configurazione pre-commit di esempio
repos:
  - repo: local
    hooks:
      - id: max-file-lines
        name: Limite righe file
        entry: python -c "import sys; max_lines=600"
        language: system
        types: [python]
      
      - id: complexity-check
        name: Limite complessità McCabe
        entry: flake8 --max-complexity=10
        language: system
        types: [python]

Perché questi limiti?

• 600 righe max per file – Blocca i mostri, ma lascia spazio ai casi reali
• Complessità McCabe a 10 – Funzioni semplici da testare e capire

Se l'agente sgarra, il hook blocca il commit. Così refattorizzi sul nascere, senza contagiare il repo.

Tool che gli Agenti Devono Conoscere (e Usare)

Per rispettare i limiti, serve potenza di refactoring automatico:

Per Python: rope è un tuttofare. Spezza funzioni, rinomina variabili, crea moduli. Gli agenti lo invocano da soli.

Per TypeScript/JavaScript: ts-morph lavora sull'AST per refattorizzare in modo intelligente. Code pulito garantito.

Non è lavoro manuale: gli agenti si auto-correggono programmaticamente.

La Costituzione degli Agenti: Le Tue Regole Scritte

Metti un file AGENTS.md o CLAUDE.md nel repo. È il manuale ufficiale:

# Linee Guida per Agenti AI

## Disciplina nei Commit
- Commit descrittivi, a intervalli logici (niente mega-commit)
- Includi ticket e spiega *cosa* e *perché*
- Esempio: "feat(auth): Ruota token OAuth2 [#324]"

## Installazione Hooks
- Esegui sempre `git config core.hooksPath .husky` (o simile)
- Installa prima del primo commit
- Testa in locale prima del push

## Regola d'Oro
- **MAI `--no-verify` senza ok esplicito dell'utente**
- Spiega sempre perché lo usi

## Approccio alla Qualità
- Test-Driven: Rosso → Verde → Refactor
- Scrivi test fallito prima
- Fallo passare
- Poi pulisci e ottimizza
- Risultato: architettura solida

Non è dittatura. È chiarezza. Gli agenti eccellono con istruzioni precise.

Perché Conta per il Tuo Team

I developer umani odiano il debito tecnico. Con questi guardrail:

✅ Fiducia nel processo – Codice in main è già decente

✅ Review più veloci – Focus su logica, non su style o bloat

✅ Onboarding facile – Nuovi vedono standard alti subito

✅ Agenti che evolvono – Imparano e migliorano lo stile

Checklist per Partire

1. Scegli il framework – pre-commit per Python, husky per JS (o entrambi)

2. Fissa limiti realistici – 600 righe e complessità 10 sono ottimi start

3. Aggiungi tool di refactoring – rope o ts-morph nel kit dell'agente

4. Documenta tutto – AGENTS.md con regole e motivi

5. Introduci piano – Parti con warning, poi blocchi rigidi

6. Monitora e adatta – Se i fallimenti sono troppi, allenta i limiti

La Lezione Vera

Non si tratta solo di bloccare codice brutto. Crei un ecosistema dove il codice buono è la via più semplice.

Con enforcement automatico, docs chiare e tool facili, gli agenti generano roba migliore. Spezzano problemi, tengono funzioni focalizzate, scrivono commit utili. L'AI passa da rischio a turbo per il team.

Da NameOcean, curiamo infra che scala: domain, cloud hosting, workflow dev. Tratta il tuo codice con la stessa disciplina dell'infra. Inizia con Git hooks. Il tuo futuro io ti ringrazierà.