Come dare a un agente di coding con IA una conoscenza affidabile del dominio

Un agente di coding generico può scrivere una risposta plausibile e perdere comunque il dettaglio decisivo del tuo stack: un’API cambiata di recente, un confine del repository da non superare o una convenzione che mantiene stabile la produzione. La soluzione non è sempre un prompt più lungo. È meglio fornire indicazioni di dominio brevi e riutilizzabili, insieme a una definizione di completamento verificabile.

1. Separa regole del progetto e procedure del dominio

Parti da due livelli. Il primo è un contratto breve del repository: cos’è il progetto, come è organizzato, quali comandi eseguono build e test, quali file sono fuori limite e cosa significa “finito”. La documentazione JetBrains sul comportamento degli agenti descrive file come AGENTS.md e CLAUDE.md come istruzioni che viaggiano con il repository e possono essere condivise tra strumenti.

Mantieni questo livello stabile e operativo. Deve rispondere a domande necessarie in ogni attività: dov’è la logica di dominio, come eseguo i controlli e cosa non devo modificare? Le regole di un solo flusso appartengono a una skill separata.

Il secondo livello è la conoscenza del dominio: una ricetta focalizzata per un compito ricorrente, come una migrazione della navigazione Android, una modifica allo schema o una checklist di rilascio. Una skill deve avere un trigger chiaro, pochi passi e validazione esplicita.

2. Scrivi una skill attorno a una lacuna

Una buona skill esiste perché il modello commette spesso lo stesso errore o riscopre sempre la stessa informazione. La filosofia Android Skills suggerisce di cercare lacune verificabili, soprattutto quando le API cambiano o l’architettura è personalizzata. Invita anche a usare fonti affidabili, non raccolte enormi di istruzioni non testate e potenzialmente dannose.

Ecco un esempio:

---
name: navigation-upgrade
description: Use when changing the app's Navigation 3 setup or upgrading its related APIs.
---

Before editing:
1. Inspect the current dependency versions and existing navigation tests.
2. Read the project's navigation conventions.
3. Confirm the target API in the approved platform documentation.

While editing:
- Make the smallest vertical change that satisfies the requested behavior.
- Do not replace the navigation architecture without approval.
- Preserve existing deep-link and back-stack behavior unless the task says otherwise.

Done means:
- The focused tests pass.
- The relevant build or lint command passes.
- The response names changed files, checks run, and unresolved risks.

L’esempio è volutamente stretto. Non incolla un manuale completo in ogni prompt: dice quando applicare la procedura, cosa controllare, quali limiti rispettare e come dimostrare il completamento. Sostituisci i controlli con i comandi e le convenzioni reali del tuo repository.

3. Fai ispezionare prima di agire

Gli agenti di coding combinano una richiesta con il contesto dell’ambiente, ragionano su di esso ed eseguono modifiche, test e build. È il flusso descritto in AWS Prescriptive Guidance. Le tue istruzioni devono rendere visibili queste fasi.

Una richiesta pratica ha quattro parti:

1. Contesto: funzione, directory rilevanti e vincoli.
2. Piano: elenco di file e controlli prima dell’editing.
3. Modifica: implementazione minima per i criteri di accettazione.
4. Prova: test, lint, build o controlli manuali esatti.

Così l’agente non parte da una sola frase e non compensa una scoperta tardiva dell’architettura con un’ampia riscrittura. L’ispezione fornisce il contesto su cui si basano le decisioni.

4. Dai un ciclo di feedback stretto

Le istruzioni di dominio spiegano come funziona il progetto, ma i controlli eseguibili dicono se la modifica funziona. La guida TDD attuale di VS Code separa red, con un test fallito, green, con il minimo codice, e refactor, mantenendo verdi le verifiche.

Non servono tre agenti sofisticati. Per una piccola attività chiedi prima un test fallito o di caratterizzazione. Poi implementa e chiudi con un test focalizzato e i normali quality gate. Se il check non passa, è informazione sul requisito o sull’ambiente, non qualcosa da nascondere in un riepilogo sicuro di sé.

5. Rivedi e ritira le istruzioni

Tratta una skill come infrastruttura ingegneristica versionata. Rivedila quando cambia il framework, l’agente ripete un errore o un controllo diventa rumoroso. La guida Android Skills considera le skill candidate alla deprecazione: i modelli migliorano e le nuove API creano nuove lacune.

Un ciclo leggero:

• Conserva un’attività di esempio che esercita la skill.
• Registra file attesi e comandi di validazione.
• Eseguila dopo ogni cambio della skill o del modello.
• Rimuovi le istruzioni non più necessarie.
• Mantieni opzionali e revisionabili le azioni sensibili.

L’obiettivo è rendere riproducibile il comportamento corretto: contratto del repository, procedura di dominio mirata e definizione eseguibile di completamento.