LV 0/13
non è magia, è contestoit's not magic, it's context

AI4DEV


Field manual per dev con agentiField manual for devs with agents

Tredici missioni, dal modello all'infrastruttura. Ogni missione chiude con cosa fare e cosa evitare. Clicca, scava, sperimenta.Thirteen missions, from the model to the infrastructure. Each one ends with what to do and what to avoid. Click, dig, experiment.

git commit prima di tutto!git commit before anything!
Premi startPress start

Scegli la missioneChoose your mission

01

La mappa del territorioMap of the territory

Tutto quello che si muove quando chiedi qualcosa a un agente. Clicca un componente per vedere cosa fa, cosa ci passa dentro e come non farsi male.

Everything that moves when you ask an agent for something. Click a component to see what it does, what flows through it and how not to get hurt.

Do BUFF

  • Passa sempre da un gateway (LiteLLM): un solo punto per chiavi, budget, alias di modello e fallback.
  • Traccia ogni chiamata (Langfuse): prompt, token, costo, latenza. Senza dati non c'è ottimizzazione.
  • Fai girare l'agente dentro una sandbox, con rete e filesystem limitati.
  • Usa alias di modello (coder-default) invece di nomi hardcoded nel codice e in CI.
  • Always go through a gateway (LiteLLM): one place for keys, budgets, model aliases and fallbacks.
  • Trace every call (Langfuse): prompt, tokens, cost, latency. No data, no optimisation.
  • Run the agent inside a sandbox, with limited network and filesystem.
  • Use model aliases (coder-default) instead of hardcoded names in code and CI.

Don't DEBUFF

  • Chiavi API dei provider sui laptop degli sviluppatori o nei repo.
  • Server MCP installati "perché c'erano" senza sapere che permessi hanno.
  • Mandare codice di un cliente a un provider senza aver verificato contratto e data retention.
  • Dare per scontato che il modello locale sia gratis: paghi in hardware, tempo e qualità.
  • Provider API keys on developer laptops or in repositories.
  • MCP servers installed "because they were there" without knowing what permissions they have.
  • Sending a client's code to a provider without checking the contract and data retention.
  • Assuming the local model is free: you pay in hardware, time and quality.
02

Cos'è un LLMWhat is an LLM

Una frase per iniziare, poi scava finché ti serve. Ogni strato aggiunge un livello di dettaglio.

One sentence to start, then dig as deep as you need. Each layer adds a level of detail.

SuperficieSurface LV 1

Un LLM è un programma che, dato un testo, prevede il pezzo di testo successivo. Ripetuto migliaia di volte, quel singolo trucco produce codice, spiegazioni e piani. Non "sa" cose come un database: ha imparato schemi statistici da enormi quantità di testo e codice.

An LLM is a program that, given some text, predicts the next piece of text. Repeated thousands of times, that single trick produces code, explanations and plans. It doesn't "know" things like a database does: it has learned statistical patterns from huge amounts of text and code.

PROFONDITÀDEPTH

Do BUFF

  • Tratta l'output come la PR di un collega bravo ma distratto: si rivede sempre.
  • Chiudi il cerchio con verifiche automatiche: compilazione, test, linter.
  • Dai al modello la documentazione delle librerie recenti invece di sperare che la conosca.
  • Treat the output like a PR from a skilled but distracted colleague: always review it.
  • Close the loop with automatic checks: compilation, tests, linters.
  • Give the model the docs of recent libraries instead of hoping it knows them.

Don't DEBUFF

  • Chiedere "sei sicuro?" come verifica: risponde in modo plausibile, non controlla.
  • Usare un LLM per calcoli esatti o dati che cambiano senza un tool.
  • Antropomorfizzare: "ha capito" e "si ricorda" sono scorciatoie, non fatti.
  • Asking "are you sure?" as verification: it answers plausibly, it doesn't check.
  • Using an LLM for exact calculations or changing data without a tool.
  • Anthropomorphising: "it understood" and "it remembers" are shortcuts, not facts.
03

Token e context windowTokens and context window

I modelli non leggono caratteri né parole: leggono token. Tutto si misura e si paga in token, e tutto deve stare nella finestra di contesto.

Models don't read characters or words: they read tokens. Everything is measured and paid in tokens, and everything must fit in the context window.

Tokenizer da campoField tokenizer

Scrivi qualcosa. È un'approssimazione didattica (i tokenizer reali usano BPE), ma l'ordine di grandezza è quello.

Type something. It's a teaching approximation (real tokenizers use BPE), but the order of magnitude is right.

carattericharacters0
token stimatiestimated tokens0
caratteri per tokenchars per token0

Regole di massimaRules of thumb

  • Inglese: circa 4 caratteri per token. Italiano e codice ne usano di più a parità di significato.
  • Paghi input (tutto ciò che mandi, a ogni turno) e output (tipicamente 3-5 volte più caro per token).
  • Il prompt caching rende molto più economico l'input ripetuto identico: prefissi stabili (system prompt, AGENTS.md) prima, parti variabili dopo.
  • Ogni turno di un agente rimanda tutta la conversazione. Un log da 20k token letto al turno 3 lo ripaghi a ogni turno successivo.
  • English: about 4 characters per token. Italian and code use more tokens for the same meaning.
  • You pay for input (everything you send, every turn) and output (typically 3-5 times more expensive per token).
  • Prompt caching makes identical repeated input much cheaper: stable prefixes (system prompt, AGENTS.md) first, variable parts after.
  • Every agent turn resends the whole conversation. A 20k-token log read at turn 3 is paid again on every following turn.

Cosa c'è dentro la finestra di contestoWhat's inside the context window

Esempio realistico di un agente di coding a metà sessione, su una finestra da 200k token. Clicca un blocco.

A realistic example of a coding agent mid-session, on a 200k-token window. Click a block.

Do BUFF

  • Controlla l'occupazione del contesto (/context in Claude Code, indicatore in OpenCode).
  • Leggi file per range e fai grep mirati invece di aprire file interi.
  • Fai filtrare l'output dei comandi: ./mvnw test -q, | tail -50.
  • Check context usage (/context in Claude Code, the indicator in OpenCode).
  • Read files by range and run targeted greps instead of opening whole files.
  • Filter command output: ./mvnw test -q, | tail -50.

Don't DEBUFF

  • Incollare stack trace e log interi "così ha tutto".
  • Confondere la dimensione della finestra con la memoria: finita la sessione, il contesto non esiste più.
  • Riempire la finestra fino al limite: la qualità cala molto prima.
  • Pasting entire stack traces and logs "so it has everything".
  • Confusing window size with memory: when the session ends, the context is gone.
  • Filling the window to the limit: quality drops well before that.
04

Open vs closed weight

La domanda non è "quale è migliore" ma chi tiene i pesi, e quindi chi paga cosa.

The question isn't "which is better" but who holds the weights, and therefore who pays for what.

Closed weight

I pesi restano al provider. Usi il modello solo via API o prodotto (Claude, GPT, Gemini).

Cosa paghi: per token, input e output separati, con sconti per cache e batch. Oppure abbonamento a posto utente.

Ottieni: i modelli più capaci, zero infrastruttura, aggiornamenti continui.

Rischi: dati che escono dal perimetro, modello che cambia o viene ritirato, costi variabili con l'uso, lock-in.

The weights stay with the provider. You use the model only via API or product (Claude, GPT, Gemini).

What you pay: per token, input and output priced separately, with discounts for caching and batch. Or a per-seat subscription.

You get: the most capable models, zero infrastructure, continuous updates.

Risks: data leaving your perimeter, models that change or get retired, usage-driven costs, lock-in.

Open weight

I pesi sono scaricabili (Llama, Qwen, Mistral, DeepSeek, gpt-oss). Li fai girare dove vuoi.

Cosa paghi: hardware (GPU, RAM), energia, operazioni. Oppure un host che lo serve per te, di nuovo a token, di solito meno caro.

Ottieni: controllo, privacy, costo prevedibile, versione congelata, fine-tuning possibile.

Rischi: qualità inferiore sui compiti agentici lunghi, licenze con clausole d'uso, il lavoro di gestione è tuo.

The weights are downloadable (Llama, Qwen, Mistral, DeepSeek, gpt-oss). You run them wherever you want.

What you pay: hardware (GPU, RAM), energy, operations. Or a host that serves it for you, again per token, usually cheaper.

You get: control, privacy, predictable cost, a frozen version, fine-tuning is possible.

Risks: lower quality on long agentic tasks, licences with usage clauses, the operations work is yours.

Trappola classica: open weight non è open sourceClassic trap: open weight is not open source

Hai i pesi, ma quasi mai i dati di training né il codice per riprodurli. E la licenza può limitare l'uso commerciale o imporre condizioni. Leggila prima di metterlo in produzione.

You get the weights, but almost never the training data or the code to reproduce them. And the licence may restrict commercial use or impose conditions. Read it before going to production.

Do BUFF

  • Scegli per compito: closed per agenti lunghi e refactoring, open per classificazione, estrazione, dati riservati.
  • Calcola il costo totale: token × volume contro hardware + persone + tempo.
  • Metti entrambi dietro lo stesso gateway, così cambiare modello è una riga di config.
  • Choose per task: closed for long agents and refactoring, open for classification, extraction, confidential data.
  • Compute the total cost: tokens × volume versus hardware + people + time.
  • Put both behind the same gateway, so switching model is one line of config.

Don't DEBUFF

  • Scegliere un modello open "per risparmiare" senza misurare la qualità sul tuo caso.
  • Ignorare la licenza perché "è su Hugging Face".
  • Dare per scontato che "closed" significhi che i tuoi dati vengono usati per il training: verifica il contratto, spesso non è così via API.
  • Choosing an open model "to save money" without measuring quality on your use case.
  • Ignoring the licence because "it's on Hugging Face".
  • Assuming "closed" means your data is used for training: check the contract, via API it often isn't.
05

Un modello sul tuo laptopA model on your laptop

Ollama scarica, quantizza e serve modelli open weight con un'API locale. Cinque comandi e sei operativo.

Ollama downloads, quantises and serves open-weight models through a local API. Five commands and you're up and running.

~/tinder4dogs

    

    

      
Scegliere la tagliaPicking the size

      
    
        
  • Regola rapida: un modello da 7-8B quantizzato a 4 bit occupa circa 5 GB, uno da 14B circa 9 GB, uno da 32B circa 20 GB. Serve quella RAM (o VRAM) libera, più spazio per il contesto.
    • 
        
  • Il contesto di default di Ollama è piccolo. Per lavorare su codice alzalo: OLLAMA_CONTEXT_LENGTH=32768 ollama serve.
    • 
        
  • Espone un'API compatibile OpenAI su http://localhost:11434/v1: la puoi collegare a LiteLLM, Spring AI, OpenCode.
    • 
        
  • Su Mac con Apple Silicon la memoria unificata aiuta molto. Su laptop senza GPU, aspettati pochi token al secondo.
    • 
      

      
    
        
  • Quick rule: a 7-8B model quantised to 4 bits takes about 5 GB, a 14B about 9 GB, a 32B about 20 GB. You need that much free RAM (or VRAM), plus room for the context.
    • 
        
  • Ollama's default context is small. For coding work, raise it: OLLAMA_CONTEXT_LENGTH=32768 ollama serve.
    • 
        
  • It exposes an OpenAI-compatible API at http://localhost:11434/v1: plug it into LiteLLM, Spring AI, OpenCode.
    • 
        
  • On Apple Silicon Macs unified memory helps a lot. On laptops without a GPU, expect a few tokens per second.
    • 
      

    

  

  

    
application.yml (Spring AI)

    
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5-coder:7b
          temperature: 0.2

  

  

    
Do BUFF

      
  • Usalo per dati che non possono uscire, prototipi offline, test di integrazione deterministici.
  • Fissa il tag del modello (qwen2.5-coder:7b, non latest).
  • Confronta sullo stesso set di prompt prima di sostituire un modello cloud.

      
  • Use it for data that can't leave, offline prototypes, deterministic integration tests.
  • Pin the model tag (qwen2.5-coder:7b, not latest).
  • Compare on the same prompt set before replacing a cloud model.

    

    
Don't DEBUFF

      
  • Aspettarti che un 7B guidi un agente su un task di 40 passi come un modello di frontiera.
  • Esporre la porta 11434 sulla rete: non ha autenticazione.
  • Dimenticare il contesto di default: tagliato in silenzio, l'agente "dimentica" metà del file.

      
  • Expecting a 7B to drive a 40-step agent task like a frontier model.
  • Exposing port 11434 on the network: there's no authentication.
  • Forgetting the default context: silently truncated, the agent "forgets" half the file.

    

  







  
06
Context engineering

  
Il prompt è una frase, il contesto è tutto il loadout. Il lavoro è mettere dentro il minimo indispensabile, al momento giusto.

  
The prompt is a sentence, the context is the whole loadout. The job is to put in the bare minimum, at the right time.

  

    
Prepara il loadoutBuild the loadout

    
Task: "Aggiungi il filtro per età all'endpoint /matches". Scegli cosa mettere nel contesto, poi verifica. La linea rossa è il 60%: oltre, la qualità inizia a calare.

    
Task: "Add the age filter to the /matches endpoint". Pick what goes into the context, then check. The red line is 60%: beyond it, quality starts dropping.

    

    
0k / 200k

    

      
      
    

    

  

  

    

      
Come si componeHow it's composed

      
    
        
  • Stabile (sempre): system prompt, AGENTS.md, descrizioni di tool e skill. Breve e in cache.
    • 
        
  • Just-in-time (quando serve): file letti dall'agente, skill caricate, risultati MCP. Lascia che l'agente li cerchi invece di precaricarli.
    • 
        
  • Di lavoro (che cresce): conversazione, output dei tool, tentativi falliti. È qui che si accumula il rumore.
    • 
        
  • Esterno (fuori finestra): spec, note, piani su file. L'agente li rilegge quando servono.
    • 
      

      
    
        
  • Stable (always): system prompt, AGENTS.md, tool and skill descriptions. Short and cached.
    • 
        
  • Just-in-time (when needed): files the agent reads, loaded skills, MCP results. Let the agent find them instead of preloading.
    • 
        
  • Working (growing): conversation, tool output, failed attempts. This is where noise piles up.
    • 
        
  • External (outside the window): specs, notes, plans on file. The agent rereads them when needed.
    • 
      

    

    

      
Compact: cos'è e quandoCompact: what and when

      

        
/compact fa riassumere la conversazione al modello e riparte da quel riassunto. Libera spazio, ma perde dettagli: è una compressione con perdita.

        
    
          
  • Usalo a un confine naturale: fase di ricerca finita, ora si implementa. Puoi guidarlo: /compact mantieni le decisioni sul filtro età e i file toccati.
    • 
          
  • Usa /clear (o una nuova sessione) quando cambi task: meglio di un compact.
    • 
          
  • Non aspettare l'auto-compact al limite: arriva quando la qualità è già calata.
    • 
          
  • Prima di compattare, fai scrivere lo stato su file (NOTES.md, la spec): sopravvive a qualunque riassunto.
    • 
        

      

      

        
/compact asks the model to summarise the conversation and restarts from that summary. It frees space, but loses detail: it's lossy compression.

        
    
          
  • Use it at a natural boundary: research is done, now we implement. You can steer it: /compact keep the age-filter decisions and the files touched.
    • 
          
  • Use /clear (or a new session) when you switch task: better than a compact.
    • 
          
  • Don't wait for auto-compact at the limit: it kicks in when quality has already dropped.
    • 
          
  • Before compacting, have the state written to a file (NOTES.md, the spec): it survives any summary.
    • 
        

      

    

  

  

    
Do BUFF

      
  • Una sessione = un task. Sessione nuova per il task nuovo.
  • Indica i file di partenza (@src/.../MatchService.kt) invece di "guarda il progetto".
  • Delega l'esplorazione rumorosa a un sub-agent: torna solo la conclusione.
  • Persisti piani e decisioni su file, non nella chat.

      
  • One session = one task. New session for the new task.
  • Point to the starting files (@src/.../MatchService.kt) instead of "look at the project".
  • Delegate noisy exploration to a sub-agent: only the conclusion comes back.
  • Persist plans and decisions in files, not in the chat.

    

    
Don't DEBUFF

      
  • Insistere nella stessa sessione dopo tre tentativi falliti: il contesto è inquinato, ricomincia con quello che hai imparato.
  • Abilitare tutti i server MCP sempre: ogni tool definito costa token a ogni turno.
  • Mettere segreti nel contesto, anche "solo per un attimo".

      
  • Pushing on in the same session after three failed attempts: the context is polluted, restart with what you learned.
  • Enabling every MCP server all the time: each defined tool costs tokens on every turn.
  • Putting secrets in the context, even "just for a moment".

    

  







  
07
L'arsenaleThe arsenal

  
Sette strumenti che si somigliano ma non sono intercambiabili. La domanda giusta: chi lo attiva, quando, e quanto contesto costa?

  
Seven tools that look alike but aren't interchangeable. The right question: who triggers it, when, and how much context does it cost?

  

  

    

      

        
Test sul campo: cosa usi?Field test: what do you use?

        
      

      

        
scenario1 / 7

        
colpi criticicritical hits0

      

    

    

    

    

    
  

  

    
Do BUFF

      
  • Ciò che deve succedere sempre va in un hook, non in un'istruzione.
  • Le procedure lunghe e occasionali vanno in skill: costano solo la descrizione finché non servono.
  • Promuovi a command un prompt che ti ritrovi a riscrivere per la terza volta.

      
  • What must always happen goes in a hook, not in an instruction.
  • Long, occasional procedures go in skills: they only cost their description until needed.
  • Promote to a command any prompt you find yourself rewriting for the third time.

    

    
Don't DEBUFF

      
  • Scrivere "esegui SEMPRE ktlint" in AGENTS.md e sperare: è una richiesta, non una garanzia.
  • Creare sub-agent per tutto: ogni passaggio perde contesto e aggiunge latenza.
  • Scrivere un server MCP per qualcosa che una CLI già fa (gh, psql).

      
  • Writing "ALWAYS run ktlint" in AGENTS.md and hoping: it's a request, not a guarantee.
  • Creating sub-agents for everything: every hand-off loses context and adds latency.
  • Writing an MCP server for something a CLI already does (gh, psql).

    

  







  
08
AGENTS.md su tre livelliAGENTS.md on three levels

  
Il file di istruzioni viene caricato all'inizio di ogni sessione e occupa contesto per tutta la durata. Tienilo corto: ogni riga deve cambiare il comportamento dell'agente, altrimenti va tolta.

  
The instruction file is loaded at the start of every session and takes up context for its whole duration. Keep it short: every line must change the agent's behaviour, otherwise remove it.

  

    

      
~/.config/opencode/AGENTS.md   (o ~/.claude/CLAUDE.md)(or ~/.claude/CLAUDE.md)
tinder4dogs/
├── AGENTS.md
├── CLAUDE.md          → contiene solo @AGENTS.md→ only contains @AGENTS.md
├── pom.xml
├── matching/
│   ├── AGENTS.md
│   └── src/...
└── notifications/
    └── src/...

      
clicca i file evidenziaticlick the highlighted files

    

    

      
Cosa NON ci va, a nessun livelloWhat does NOT go in, at any level

      
    
        
  • Segreti, token, URL interni sensibili.
    • 
        
  • Regole che il linter o il compilatore già impongono.
    • 
        
  • Consigli generici ("scrivi codice pulito", "sii preciso").
    • 
        
  • L'albero completo dei file o documentazione lunga: metti un link al file, l'agente lo legge se serve.
    • 
        
  • Informazioni che cambiano spesso: diventano false in silenzio.
    • 
      

      
    
        
  • Secrets, tokens, sensitive internal URLs.
    • 
        
  • Rules the linter or compiler already enforces.
    • 
        
  • Generic advice ("write clean code", "be precise").
    • 
        
  • The full file tree or long docs: link to the file, the agent reads it if needed.
    • 
        
  • Information that changes often: it silently becomes false.
    • 
      

    

  

  

    
Home (personale)Home (personal)
~/.config/opencode/AGENTS.md · ~/.claude/CLAUDE.md

      
  • Lingua e stile di risposta che preferisci.
  • Il tuo workflow: "proponi un piano prima di modifiche su più file".
  • Strumenti della tua macchina (mise, gh).
  • Mai regole del progetto: i colleghi non le vedono.

      
  • Your preferred language and response style.
  • Your workflow: "propose a plan before multi-file changes".
  • Tools on your machine (mise, gh).
  • Never project rules: your colleagues can't see them.

    

    
Progetto (team)Project (team)
./AGENTS.md (versionatoversioned)

      
  • Comandi esatti: build, test, lint, avvio (./mvnw verify).
  • Mappa dell'architettura in 5-10 righe e dove vivono le cose.
  • Convenzioni non ovvie (Result invece di eccezioni, niente !!).
  • Definition of done e cose da non toccare (migration già applicate).

      
  • Exact commands: build, test, lint, run (./mvnw verify).
  • A 5-10 line architecture map and where things live.
  • Non-obvious conventions (Result instead of exceptions, no !!).
  • Definition of done and things not to touch (already-applied migrations).

    

    
Sotto-moduloSub-module
./matching/AGENTS.md

      
  • Comandi solo del modulo (./mvnw -pl matching test).
  • Vincoli locali: algoritmo di scoring, invarianti di dominio.
  • Dipendenze ammesse e confini con gli altri moduli.
  • Viene caricato quando l'agente lavora lì: niente ripetizioni del root.

      
  • Module-only commands (./mvnw -pl matching test).
  • Local constraints: scoring algorithm, domain invariants.
  • Allowed dependencies and boundaries with other modules.
  • Loaded when the agent works there: don't repeat the root file.

    

  

  

    
Do BUFF

      
  • Tieni il file di progetto sotto le ~150 righe e versionalo come il codice.
  • Usa AGENTS.md come fonte unica; per Claude Code un CLAUDE.md con @AGENTS.md.
  • Aggiungi una regola quando vedi l'agente sbagliare due volte la stessa cosa.

      
  • Keep the project file under ~150 lines and version it like code.
  • Use AGENTS.md as the single source; for Claude Code a CLAUDE.md containing @AGENTS.md.
  • Add a rule when you see the agent get the same thing wrong twice.

    

    
Don't DEBUFF

      
  • Farlo generare all'agente e committarlo senza rileggerlo.
  • Scrivere in maiuscolo per "insistere": se una regola è critica, diventa un hook o un test.
  • Duplicare le stesse regole su tre livelli.

      
  • Having the agent generate it and committing without rereading it.
  • Writing in CAPS to "insist": if a rule is critical, make it a hook or a test.
  • Duplicating the same rules across three levels.

    

  







  
09
L'agent loopThe agent loop

  
Un agente è un LLM in un ciclo: pensa, agisce con un tool, osserva il risultato, ricomincia finché il task è chiuso o qualcosa lo ferma.

  
An agent is an LLM in a loop: think, act with a tool, observe the result, repeat until the task is done or something stops it.

  

    
    

      

      

        
AgentLoop.kt

        
while (turns++ < maxTurns) {
  val reply = llm.call(context, tools)
  if (reply.toolCalls.isEmpty()) return reply.text  // done
  for (call in reply.toolCalls) {
    if (!permissions.allows(call)) askHuman(call)
    context += sandbox.run(call)  // observe
  }
}

      

    

  

  

    
Do BUFF

      
  • Dai all'agente un modo per verificarsi da solo: test, build, uno screenshot. È il moltiplicatore più grande.
  • Definisci il "finito": criteri di accettazione chiari chiudono il loop.
  • Interrompi presto (Esc) quando vedi che va nella direzione sbagliata.

      
  • Give the agent a way to check itself: tests, a build, a screenshot. It's the biggest multiplier.
  • Define "done": clear acceptance criteria close the loop.
  • Interrupt early (Esc) when you see it heading the wrong way.

    

    
Don't DEBUFF

      
  • Lasciarlo girare senza limite di turni o budget.
  • Accettare "ho sistemato" senza un risultato di tool che lo dimostri.
  • Rispondere a un fallimento con "riprova": aggiungi l'informazione che mancava.

      
  • Letting it run without a turn or budget limit.
  • Accepting "I fixed it" without a tool result that proves it.
  • Answering a failure with "try again": add the information that was missing.

    

  







  
10
Permessi vs sandboxPermissions vs sandbox

  
I permessi sono il badge: cosa l'agente può chiedere di fare. La sandbox sono i muri: cosa può toccare davvero, anche se il badge è sbagliato.

  
Permissions are the badge: what the agent may ask to do. The sandbox is the walls: what it can actually touch, even if the badge is wrong.

  

    

      
Permessi (harness)Permissions (harness)

      
    
        
  • Regole allow / ask / deny per tool e comandi: Bash(./mvnw test) sì, Bash(rm -rf *) no, lettura di .env negata.
    • 
        
  • Applicati dall'agente stesso. Se una regola è scritta male o un comando consentito fa più del previsto, non c'è seconda linea.
    • 
        
  • Proteggono dagli errori, non da un attacco (prompt injection in un README, in una issue, in una pagina web).
    • 
      

      
    
        
  • Allow / ask / deny rules per tool and command: Bash(./mvnw test) yes, Bash(rm -rf *) no, reading .env denied.
    • 
        
  • Enforced by the agent harness itself. If a rule is badly written or an allowed command does more than expected, there's no second line.
    • 
        
  • They protect against mistakes, not against an attack (prompt injection in a README, an issue, a web page).
    • 
      

    

    

      
Sandbox (sistema operativo)Sandbox (operating system)

      
    
        
  • Isolamento a livello OS o container: filesystem limitato alla cartella di progetto, rete solo verso domini consentiti.
    • 
        
  • Vale per tutto ciò che l'agente lancia, compresi script e dipendenze. Nel corso usiamo nono, indipendente dal vendor.
    • 
        
  • Riduce il raggio d'esplosione: anche il peggior comando resta dentro i muri.
    • 
      

      
    
        
  • OS or container-level isolation: filesystem limited to the project folder, network only to allowed domains.
    • 
        
  • Applies to everything the agent launches, including scripts and dependencies. In the course we use nono, which is vendor-neutral.
    • 
        
  • Shrinks the blast radius: even the worst command stays inside the walls.
    • 
      

    

  

  

    
Sandbox OFF
Sandbox ON

    
Permessi strettiTight permissions

    
Lento e fragileSlow and fragileMille richieste di conferma, e quando dici "sì a tutto" per stanchezza sei scoperto.A thousand confirmation prompts, and when you say "yes to all" out of fatigue you're exposed.

    
Massima sicurezzaMaximum safetyPer codice di clienti, dati sensibili, ambienti condivisi.For client code, sensitive data, shared environments.

    
Permessi larghiLoose permissions

    
Game over--dangerously-skip-permissions sul laptop con le chiavi di produzione. Mai.--dangerously-skip-permissions on the laptop with production keys. Never.

    
Autonomia sicuraSafe autonomyL'agente lavora senza interruzioni, i muri limitano i danni. Il punto ideale per task lunghi.The agent works without interruptions, the walls limit the damage. The sweet spot for long tasks.

  

  

    
Do BUFF

      
  • Prima la sandbox, poi allarga i permessi: è la combinazione che ti dà autonomia.
  • Nega esplicitamente la lettura di .env, ~/.ssh, ~/.aws.
  • Versiona le regole di permesso del progetto insieme al codice.

      
  • Sandbox first, then loosen permissions: that's the combination that gives you autonomy.
  • Explicitly deny reading .env, ~/.ssh, ~/.aws.
  • Version the project's permission rules together with the code.

    

    
Don't DEBUFF

      
  • Approvare in automatico ogni richiesta: la fatica da conferma è un rischio reale.
  • Credere che una regola "deny" su curl blocchi l'uscita dei dati: esistono cento altri modi senza sandbox di rete.
  • Dare all'agente credenziali con più privilegi di quelli che daresti a un junior al primo giorno.

      
  • Auto-approving every request: confirmation fatigue is a real risk.
  • Believing a "deny" rule on curl stops data exfiltration: without a network sandbox there are a hundred other ways.
  • Giving the agent credentials with more privileges than you'd give a junior on day one.

    

  







  
11
Reti di sicurezzaSafety nets

  
Tre scudi, in ordine. Il primo evita l'errore, il secondo lo annulla in un secondo, il terzo ti salva quasi sempre. Prova gli incidenti qui sotto per vedere chi para il colpo.

  
Three shields, in order. The first prevents the mistake, the second undoes it in a second, the third saves you almost always. Try the incidents below to see which one blocks the hit.

  

    
Simulatore di incidentiIncident simulator

    
Scegli cosa è successo: gli scudi che ti salvano si illuminano, quelli inutili si spengono.

    
Pick what happened: the shields that save you light up, the useless ones go dark.

    

    

  

  

    

      
Plan
prima di toccare il codicebefore touching the code

      
L'agente legge e propone un piano senza modificare nulla. Tu correggi il piano, che costa poco, invece del codice, che costa tanto.

      
The agent reads and proposes a plan without changing anything. You fix the plan, which is cheap, instead of the code, which is expensive.

      
Shift+Tab plan mode (Claude Code)Tab plan agent (OpenCode)

    

    

      
Checkpoint
durante la sessioneduring the session

      
Ogni modifica ai file è un punto di ripristino. Annulli codice e conversazione insieme e riprovi con un'altra istruzione.

      
Every file edit is a restore point. You undo code and conversation together and retry with a different instruction.

      
/undo /redo (OpenCode)EscEsc / /rewind (Claude Code)

      
Non annullano gli effetti dei comandi shell (migration, rm, chiamate esterne).

      
They don't undo the effects of shell commands (migrations, rm, external calls).

    

    

      
Git
sempre, fuori dall'agentealways, outside the agent

      
La rete che sopravvive a crash, sessioni chiuse e compact sbagliati. Commit piccoli e frequenti, un branch per task.

      
The net that survives crashes, closed sessions and bad compacts. Small, frequent commits, one branch per task.

      
git switch -c feat/agegit diffgit add -pgit restore .

    

  

  

    
Do BUFF

      
  • Albero di lavoro pulito prima di avviare l'agente: commit o stash.
  • Plan mode per tutto ciò che tocca più di due o tre file.
  • Rivedi il diff completo prima del commit, non il riassunto dell'agente.

      
  • Clean working tree before starting the agent: commit or stash.
  • Plan mode for anything touching more than two or three files.
  • Review the full diff before committing, not the agent's summary.

    

    
Don't DEBUFF

      
  • Usare i checkpoint al posto di git.
  • Lasciare che l'agente faccia push --force o reset --hard senza chiedere.
  • Accumulare due ore di modifiche non committate "tanto c'è l'undo".

      
  • Using checkpoints instead of git.
  • Letting the agent push --force or reset --hard without asking.
  • Piling up two hours of uncommitted changes "because undo exists".

    

  







  
12
Agenti in paralleloParallel agents

  
Due agenti nella stessa cartella si pestano i piedi. Un git worktree dà a ciascuno la sua copia di lavoro, sullo stesso repository.

  
Two agents in the same folder step on each other's toes. A git worktree gives each one its own working copy, on the same repository.

  
    main
    
    
    
    
    
    
    
    ../t4d-age · feat/age-filter
    ../t4d-notif · feat/notifications
    agente Aagent A
    agente Bagent B
    review + merge (tu)review + merge (you)
  
  

    

      
terminal

      
      

    

    

      
Cosa il worktree NON isolaWhat a worktree does NOT isolate

      
    
        
  • Database: stesso Postgres, stesse tabelle. Usa schemi o container diversi per worktree.
    • 
        
  • Porte: due Spring Boot su 8080 non partono. Assegna SERVER_PORT per worktree.
    • 
        
  • Container Docker con lo stesso nome, cache condivise, servizi esterni.
    • 
        
  • Il tuo tempo di review: tre agenti in parallelo producono tre diff da leggere.
    • 
      

      
    
        
  • Database: same Postgres, same tables. Use different schemas or containers per worktree.
    • 
        
  • Ports: two Spring Boot apps on 8080 won't both start. Assign SERVER_PORT per worktree.
    • 
        
  • Docker containers with the same name, shared caches, external services.
    • 
        
  • Your review time: three agents in parallel produce three diffs to read.
    • 
      

    

  

  

    
Do BUFF

      
  • Parallelizza task indipendenti che toccano file diversi.
  • Parti da un main aggiornato e fai rebase spesso.
  • Inizia con due agenti, sali solo se la review regge.

      
  • Parallelise independent tasks that touch different files.
  • Start from an up-to-date main and rebase often.
  • Start with two agents, scale up only if review keeps up.

    

    
Don't DEBUFF

      
  • Mandare due agenti sullo stesso file "per vedere chi fa meglio" senza prevedere il merge.
  • Usare il parallelismo per compiti con dipendenze: il secondo lavora su codice che non esiste ancora.
  • Lasciare worktree orfani: git worktree prune.

      
  • Sending two agents to the same file "to see who does better" without planning the merge.
  • Parallelising dependent tasks: the second one works on code that doesn't exist yet.
  • Leaving orphaned worktrees: git worktree prune.

    

  







  
13
Spec driven development

  
Il vibe coding funziona per un prototipo. Per il codice che resta, la spec è il contratto tra te, il team e l'agente. Clicca le fasi.

  
Vibe coding works for a prototype. For code that stays, the spec is the contract between you, the team and the agent. Click the stages.

  

  

    

    

      
specs/004-age-filter/spec.md

      
## Problema
Gli utenti ricevono match con cani di età
incompatibile (cuccioli con cani anziani).

## User story
Come proprietario voglio filtrare i match per
fascia d'età per evitare incontri sbilanciati.

## Criteri di accettazione
- GIVEN filtro 1-5 anni WHEN GET /matches
  THEN nessun cane fuori fascia
- GIVEN nessun filtro THEN comportamento invariato

## Fuori scope
Filtro per taglia, ordinamento per distanza.

      
## Problem
Users get matches with dogs of an incompatible
age (puppies paired with senior dogs).

## User story
As an owner I want to filter matches by age
range to avoid unbalanced meetings.

## Acceptance criteria
- GIVEN filter 1-5 years WHEN GET /matches
  THEN no dog outside the range
- GIVEN no filter THEN behaviour unchanged

## Out of scope
Size filter, sorting by distance.

    

  

  

    
Do BUFF

      
  • Approva ogni fase prima della successiva: spec, piano, task.
  • Scrivi criteri di accettazione verificabili: diventano test.
  • Se il codice devia dalla spec, aggiorna prima la spec (regola del drift).
  • Strumenti del corso: OpenSpec, cc-sdd (/kiro), WellForge.

      
  • Approve each stage before the next: spec, plan, tasks.
  • Write verifiable acceptance criteria: they become tests.
  • If the code drifts from the spec, update the spec first (the drift rule).
  • Course tools: OpenSpec, cc-sdd (/kiro), WellForge.

    

    
Don't DEBUFF

      
  • Far scrivere la spec all'agente e approvarla senza leggerla.
  • Spec da 15 pagine per un bugfix: la cerimonia va proporzionata al rischio.
  • Lasciare la spec a marcire dopo il merge: una spec falsa è peggio di nessuna.

      
  • Having the agent write the spec and approving it without reading it.
  • A 15-page spec for a bugfix: ceremony must match the risk.
  • Letting the spec rot after the merge: a false spec is worse than none.