DEV Community: Omar Baruzzo

Audit je fotografija, test suite je navika

Omar Baruzzo — Tue, 27 Oct 2026 11:19:56 +0000

Ukratko: audit pokriva jedan commit. Unit, fork i invariant testovi u CI-ju drže sljedeći commit pouzdanim.

Audit smart contracta pregledava jednu verziju koda, u jednom trenutku, a pregledavaju ga ljudi koji ga nisu napisali. To je vrijedan posao i to je ujedno fotografija. Ne govori ništa o sljedećem commitu, a kod će ih imati mnogo.

Što audit ne pokriva

Nakon isporuke reporta kod se i dalje mijenja. Digne se dependency, prilagodi se fee parametar, doda se funkcija za jednog klijenta, deployment skripta se izmijeni u zadnji čas. Nijednu od tih promjena ne opisuje dokument star tri mjeseca. Audit ostaje istinit za verziju koju je pregledao, a o verziji koja je stvarno deployana govori sve manje sa svakom promjenom od tada. To je obični život svakog codebasea i zato jedan datiran izvještaj ne može biti jedini dokaz da se ugovor ponaša kako treba. Pitanje koje revizor treba postaviti nije postoji li audit, nego koliki dio deployanog koda on još opisuje.

Tri vrste testova koje nose audit dalje

Unit testovi provjeravaju svaku funkciju zasebno i čine osnovu. Fork testovi pokreću ugovore nad kopijom stvarnog stanja chaina, pa se integracija s već deployanim protokolima provjerava, a ne pretpostavlja. Invariant testovi izriču svojstva koja moraju vrijediti što god se dogodilo: zbroj balansa jednak je ukupnoj ponudi, nitko ne može podići više nego što je uplatio, pauzirani ugovor ne prima transfere. Fuzzer zatim generira nizove poziva koji ta svojstva pokušavaju slomiti, uključujući nizove na koje nitko iz tima nije pomislio. Alati poput Foundryja i Hardhata podržavaju sva tri stila.

Testovi i za ono što nije logika ugovora

Mnogi incidenti u produkciji dolaze iz deploya i upgradea, a ne iz logike koju je audit pročitao. U suite stavite deployment skripte, argumente constructora i initializera te upgrade put. Sve pokrećite u continuous integrationu na svaku promjenu, tako da invariant koji pada zaustavi release jednako kao što bi to učinio neuspjeli unit test u bilo kojem drugom projektu.

Kako iskoristiti auditora

Tražite od auditora da svaki finding preda kao reprodukciju i pretvorite ga u test koji pada prije nego ga popravite. Finding koji postane test ne vraća se neprimijećen. Pitajte i koje je invariante pretpostavio dok je čitao kod te ih zapišite kao testove. Nastaje suite koji bilježi što je audit naučio, pa sljedeći revizor kreće odatle, a ne od nule. Za tvrtke u regiji koje rade za strane klijente i partnere to je i dokaz: partner neće pitati samo imate li audit, nego i što se dogodilo nakon njega.

Pravilo je kratko. Audit je prekretnica, a test suite je proces. Koji invariant vašeg ugovora danas nije zapisan kao test?

Cijeli tekst: cijelo obrazloženje na blogu

Articolo originale: https://www.omarbaruzzo.it/hr/blog/un-audit-non-e-una-suite-di-test

Un audit è una fotografia, una suite di test è un'abitudine

Omar Baruzzo — Tue, 27 Oct 2026 11:17:48 +0000

In breve: l'audit copre un commit. Unit, fork e invariant test, eseguiti nella CI, tengono onesto il commit successivo.

L'audit di uno smart contract esamina una versione del codice, in un momento preciso, da persone che non l'hanno scritto. È un lavoro prezioso, ed è anche una fotografia. Non dice nulla sul commit successivo, e di commit il codice ne vedrà molti.

Cosa l'audit non copre

Dopo la consegna del report il codice continua a cambiare. Si aggiorna una dipendenza, si ritocca un parametro di commissione, si aggiunge una funzione per un cliente, si modifica all'ultimo minuto uno script di deploy. Nessuna di queste modifiche è descritta da un documento datato tre mesi prima. L'audit resta vero per la versione che ha esaminato, e diventa meno informativo sulla versione effettivamente distribuita a ogni modifica fatta da allora.

Tre tipi di test che portano avanti l'audit

Gli unit test controllano ogni funzione in isolamento e sono la base. I fork test eseguono i contratti su una copia dello stato reale della catena, così l'integrazione con protocolli già distribuiti si verifica e non si dà per scontata. Gli invariant test dichiarano proprietà che devono valere qualunque cosa accada: la somma dei saldi uguale alla fornitura totale, nessuno che prelevi più di quanto ha versato, un contratto in pausa che non accetta trasferimenti. Un fuzzer genera poi sequenze di chiamate che cercano di romperle, comprese sequenze a cui nessuno del team aveva pensato. Strumenti come Foundry e Hardhat supportano tutti e tre gli stili.

Test anche per ciò che non è logica del contratto

Molti incidenti in produzione nascono dal deploy e dall'upgrade, non dalla logica letta dall'audit. Mettete nella suite gli script di deploy, gli argomenti del costruttore e dell'inizializzatore, e il percorso di upgrade. Eseguite tutto nella integrazione continua a ogni modifica, in modo che un invariante che fallisce fermi un rilascio come farebbe un unit test in qualsiasi altro progetto .NET.

Come usare l'auditor

Chiedete all'auditor di consegnare ogni finding come riproduzione, e trasformatelo in un test che fallisce prima di correggerlo. Un finding diventato test non torna inosservato. Chiedete anche quali invarianti ha dato per assunti leggendo il codice, e scrivetele come test. Ne esce una suite che registra ciò che l'audit ha imparato, così il prossimo revisore parte da lì e non da zero. Per una software house che consegna a una PMI conta anche questo: la suite e gli script fanno parte della consegna, altrimenti il cliente eredita un audit e nessun modo di accorgersi che il codice è cambiato.

La regola è breve. L'audit è una tappa, la suite di test è il processo. Quale invariante del vostro contratto oggi non è scritta come test?

Testo completo: il ragionamento completo sul blog

Articolo originale: https://www.omarbaruzzo.it/it/blog/un-audit-non-e-una-suite-di-test

An audit is a photograph, a test suite is a habit

Omar Baruzzo — Tue, 27 Oct 2026 11:15:15 +0000

TL;DR: an audit covers one commit. Unit, fork and invariant tests, run in CI, are what keep the next commit honest.

A smart contract audit reviews one version of the code, at one moment, by people who did not write it. That is valuable work, and it is also a photograph. It says nothing about the next commit, and the code will have many of them.

What the audit does not cover

After the report is delivered, the code keeps changing. A dependency is updated, a fee parameter is adjusted, a function is added for one customer, a deployment script is edited at the last minute. None of these changes is described by a document dated three months earlier. The audit remains true about the version it examined, and becomes less informative about the version that is actually deployed with every change made since. This is the ordinary life of any codebase, and it is why a single dated report cannot be the only evidence that a contract behaves as intended. The question a reviewer should ask is not whether an audit exists, but how much of the deployed code it still describes.

Three kinds of test that carry the audit forward

Unit tests check each function in isolation and are the baseline. Fork tests run your contracts against a copy of real chain state, so the integration with protocols that are already deployed is exercised rather than assumed. Invariant tests state properties that must hold whatever happens: the sum of balances equals the total supply, nobody can withdraw more than they deposited, a paused contract accepts no transfers. A fuzzer then generates sequences of calls that try to break each property, including sequences nobody on the team thought of. Tools such as Foundry and Hardhat support all three styles.

Tests for the parts that are not contract logic

Many production incidents come from deployment and upgrade, not from the logic the audit read. Put the deployment scripts, the constructor and initializer arguments, and the upgrade path inside the suite. Run everything in continuous integration on every change, so that a failing invariant stops a release the same way a failing unit test would in any other codebase.

How to use the auditor

Ask the auditor to hand over each finding as a reproduction, and turn it into a failing test before fixing it. A finding that becomes a test does not come back unnoticed. Ask also which invariants they assumed while reading, and write those down as tests. The result is a suite that records what the audit learned, so the next reviewer starts from it instead of from zero.

The rule is short. The audit is a milestone and the test suite is the process. Which invariant of your contract is not written down as a test today?

Full text: the full argument on the blog

Articolo originale: https://www.omarbaruzzo.it/en/blog/un-audit-non-e-una-suite-di-test

Kako obrisati ono što ste anchorali?

Omar Baruzzo — Thu, 22 Oct 2026 11:14:25 +0000

Ukratko: osobni podaci izvan chaina uz nasumični salt po zapisu; na chain ide samo commitment. Obrišete li podatak i salt, commitment ne pokazuje ni na što.

Decision ledger je koristan jer se njegovi zapisi ne mogu naknadno mijenjati. Isto svojstvo postaje problem prvi put kad zapis sadrži osobne podatke, a netko traži njihovo brisanje. Odgovor se određuje pri projektiranju, prije prvog anchora, a ne nekim trikom na chainu.

Podijelite zapis na dva dijela

Sadržaj ostaje u običnom storeu pod vašom kontrolom: tablica u bazi, object store, što god koristi ostatak sustava. Tamo žive osobni podaci i tamo se mogu ispraviti ili obrisati kao svi drugi podaci. Chain prima samo commitment na taj sadržaj: hash jednog zapisa ili root Merkle stabla nad više zapisa koji se anchoraju zajedno. Zapis u ledgeru kaže što se dogodilo i upućuje na record preko identifikatora, a proof povezuje to dvoje bez objavljivanja sadržaja.

Običan hash nije dovoljan

Hashiranje imena, email adrese ili OIB-a djeluje sigurno, a često nije. Prostor mogućih ulaza je malen: tko može pogoditi kandidate, može izračunati njihove hasheve i usporediti. Dodajte nasumični salt svakom recordu, generiran po zapisu, i čuvajte ga uz podatak u vanjskom storeu, nikada na chainu. Commitment postaje hash od salta i sadržaja. Bez salta se vrijednost na chainu ne može reproducirati iz pretpostavke.

Što onda znači brisanje

Kad se zahtjev za brisanje prihvati, iz vanjskog storea brišu se sadržaj i njegov salt. Commitment na chainu ostaje, ali ne ostaje ništa što bi se moglo ponovno izračunati da mu odgovara. To je broj koji ne pokazuje ni na što. Ledger i dalje pokazuje da je zapis postojao na određenoj visini, u određenom slijedu, i da slijed oko njega nije mijenjan. Revizor tako i dalje može provjeriti da povijest nije prepravljena, ali ne može iz chaina saznati što je u tom zapisu pisalo. Za većinu poslovnih slučajeva to je upravo željena granica: integritet ostaje javno provjerljiv, a osobni podaci ostaju tamo gdje se njima može upravljati.

Što gubite i što tek treba odlučiti

Dvije posljedice treba zapisati u projekt. Prva: kad sadržaj nestane, nestaje i mogućnost da se dokaže što je pisalo. Brisanje i dokaz vuku u suprotnim smjerovima, a za neke zapise obveze čuvanja će reći što prevladava. Druga: smatra li se hash i dalje osobnim podatkom pravno je pitanje koje ovisi o slučaju, o ulazu i o tome što se još može povezati s njim. Tu procjenu daje službenik za zaštitu podataka (DPO), a ne arhitekt.

Praktično pravilo je kratko. Prije prvog anchora odlučite koja polja bi se ikada mogla morati brisati, držite ih izvan chaina i zapišite proceduru brisanja uz dizajn ledgera. Poslije je to migracija.

Koja polja u vašem ledgeru bi vam bilo žao što ste anchorali?

Cijeli tekst: cijeli obrazac brisanja

Articolo originale: https://www.omarbaruzzo.it/hr/blog/cancellare-un-dato-ancorato

Come si cancella ciò che si è ancorato?

Omar Baruzzo — Thu, 22 Oct 2026 11:13:39 +0000

In breve: dati personali fuori catena con un salt casuale per record; sulla catena solo l'impegno. Cancellati dato e salt, l'impegno non punta a niente.

Un registro delle decisioni è utile perché le sue voci non si possono cambiare a posteriori. La stessa proprietà diventa un problema la prima volta che una voce contiene dati personali e qualcuno chiede di cancellarli. La risposta si decide in fase di progetto, prima del primo ancoraggio, e non è un trucco da fare sulla catena.

Dividere il record in due

Il contenuto resta in un archivio ordinario sotto il vostro controllo: una tabella di database, un object store, quello che usa il resto del sistema. È lì che vivono i dati personali, e lì si possono correggere o cancellare come qualsiasi altro dato. La catena riceve solo un impegno verso quel contenuto: l'hash di una voce, o la radice di un albero di Merkle su molte voci ancorate insieme. La voce del registro dice cosa è successo e rimanda al record tramite identificativo, e la prova collega le due cose senza pubblicare il contenuto.

L'hash semplice non basta

Calcolare l'hash di un nome, di un indirizzo email o di un codice fiscale sembra sicuro, e spesso non lo è. Lo spazio degli input è piccolo: chi può indovinare dei candidati può calcolarne gli hash e confrontarli. Aggiungete un salt casuale a ogni record, generato per voce, e conservatelo accanto al dato nell'archivio esterno, mai sulla catena. L'impegno diventa l'hash di salt più contenuto. Senza il salt, il valore sulla catena non si riproduce partendo da un'ipotesi.

Cosa significa cancellare, allora

Quando una richiesta di cancellazione viene accolta, si eliminano dall'archivio esterno il contenuto e il suo salt. L'impegno sulla catena resta, ma non rimane più nulla che si possa ricalcolare per farlo coincidere. È un numero che non punta a niente. Il registro mostra ancora che una voce esisteva a una certa altezza, in una certa sequenza, e che la sequenza non è stata alterata attorno ad essa.

Cosa si perde, e cosa resta da decidere

Due conseguenze vanno scritte nel progetto. La prima: una volta sparito il contenuto, sparisce anche la possibilità di provare cosa diceva. Cancellazione e prova tirano in direzioni opposte, e per alcuni record saranno gli obblighi di conservazione a dire quale prevale. La seconda: se un hash conta ancora come dato personale è una questione giuridica che dipende dal caso, dall'input e da cos'altro vi si può collegare. Quel giudizio spetta al responsabile della protezione dei dati, non a chi disegna l'architettura.

La regola pratica è breve. Decidete prima del primo ancoraggio quali campi potrebbero dover essere cancellati, teneteli fuori dalla catena e scrivete la procedura di cancellazione insieme al progetto del registro. Dopo, è una migrazione.

Quali campi del vostro registro vi pentireste di aver ancorato?

Testo completo: lo schema di cancellazione per esteso

Articolo originale: https://www.omarbaruzzo.it/it/blog/cancellare-un-dato-ancorato

How do you delete something you anchored?

Omar Baruzzo — Thu, 22 Oct 2026 11:12:24 +0000

TL;DR: personal data off-chain with a per-record random salt; only the commitment goes on-chain. Erase the data and the salt, and the commitment points at nothing.

A decision ledger is useful because its entries cannot be changed after the fact. The same property becomes a problem the first time an entry contains personal data and someone asks for it to be erased. The answer is decided at design time, before the first anchor, and it is not a clever trick on the chain.

Split the record in two

Keep the content in an ordinary store that you control: a database table, an object store, whatever the rest of the system uses. This is where the personal data lives, and where it can be corrected or deleted like any other data. The chain receives only a commitment to that content: a hash of one entry, or the root of a Merkle tree over many entries anchored together. The ledger entry then says what happened and refers to the record by identifier, and the proof ties the two together without publishing the content.

A plain hash is not enough

Hashing a name, an email address or a tax code looks safe, and often is not. The input space is small, so anyone who can guess candidates can compute their hashes and compare. Add a random salt to each record, generated per entry, and store it next to the data in the off-chain store, never on the chain. The commitment becomes the hash of salt plus content. Without the salt, the value on the chain cannot be reproduced from a guess.

What deletion then means

When an erasure request is accepted, delete the content and its salt from the off-chain store. The commitment on the chain remains, but nothing is left that can be recomputed to match it. It is a number that points at nothing. The ledger still shows that an entry existed at a given height, in a given sequence, and that the sequence was not altered around it.

What you lose, and what you still need to decide

Two consequences should be explicit in the design. First, once the content is gone, so is the ability to prove what it said. Erasure and evidence pull in opposite directions, and for some records the retention rules will say which one wins. Second, whether a hash still counts as personal data is a legal question that depends on the case, on the input and on what else can be linked to it. That judgment belongs to your data protection officer, not to the architect.

The practical rule is short. Decide which fields may ever need deleting before the first anchor, keep those off the chain, and write down the erasure procedure together with the ledger design. Afterwards it is a migration.

Which fields in your ledger would you regret having anchored?

Full text: the erasure pattern in full

Articolo originale: https://www.omarbaruzzo.it/en/blog/cancellare-un-dato-ancorato

Tko održava agenta nakon isporuke?

Omar Baruzzo — Tue, 20 Oct 2026 11:23:04 +0000

Ukratko: isporučite runbook, klijentov eval set, zaključane verzije s rollbackom, imenovanog primatelja alerta i čitljiv decision log.

AI agent radi na dan isporuke. Hoće li raditi i nakon šest mjeseci ovisi o tome tko za njega odgovara i što ima u rukama. Handover je dio projekta, a ne sastanak na kraju.

Što se promijeni kad ga nitko ne dira

Agenti se kvare i bez ikakvih izmjena. Provider modela ukine verziju, a alias na koji ste se oslanjali sada pokazuje na nešto drugo. Upstream API preimenuje ili makne polje. Dokumenti koje agent čita udalje se od onih na kojima je testiran: novi predlošci, nove šifre artikala, drugačiji način pisanja iste stvari. Ništa od toga ne vidi se na code reviewu jer se kod nije mijenjao. Vidi se kao greška pred klijentom, a prvi je obično primijeti netko tko ne zna zašto se dogodila.

Pet stvari koje izlaze sa sustavom

Prva je runbook. Kaže što agent smije raditi, što nikada ne smije, u koje sustave smije pisati i što učiniti kad se čudno ponaša. Pisan je za dežurnu osobu, a ne za programera koji ga je izgradio.

Druga je eval set u vlasništvu klijenta. Ako pitanja i očekivani odgovori postoje samo na laptopu isporučitelja, klijent nakon promjene ne može ništa provjeriti. S setom u rukama može ga ponovno pokrenuti nakon ažuriranja modela, izmjene prompta ili nove serije dokumenata i usporediti s prošlim rezultatom.

Treća su zaključane verzije uz zapisan rollback. Model, prompt i indeks bilježe se kao točne verzije, a put natrag na prethodnu kombinaciju je dokumentiran korak, a ne sjećanje.

Četvrta je imenovana osoba za alerte koja nije autor sustava. Alert koji stigne u sandučić koji nitko ne čita jednak je kao da alerta nema.

Peta je decision log, s načinom čitanja koji ne ovisi o isporučitelju. Kad netko pita zašto je agent nešto napravio u ožujku, odgovor ne smije tražiti telefonski poziv vama.

Kome stiže prva poruka

Zamislite prvu obavijest o ukidanju verzije modela. Ako su eval set i zaključane verzije u rukama klijenta, to je stavka u kalendaru: zakaže se test, usporedi se i prijeđe na novu verziju. Ako nisu, to je hitnja koja pada na onoga tko je izgradio sustav, u trenutku koji nije birao. Za tvrtke koje rade za klijente u regiji i inozemstvu to je i pitanje marže, jer neograničena neformalna podrška rijetko je u cijeni. A revizor ili strani partner pitat će tko nadzire sustav nakon isporuke.

Održavanje je projektno ograničenje

Ugovor o podršci dodan nakon isporuke ne popravlja sustav izgrađen tako da ga razumiju samo njegovi autori. Ograničenje treba postaviti od prvog sprinta: što će klijent moći pokrenuti, provjeriti i promijeniti bez nas? Takav dizajn izgradnju čini malo sporijom, a sljedeće godine puno mirnijima.

Kad agent za godinu dana pogriješi, kome stiže prva poruka?

Cijeli tekst: cijela handover lista

Articolo originale: https://www.omarbaruzzo.it/hr/blog/agente-ai-dopo-la-consegna

Chi mantiene l'agente dopo la consegna?

Omar Baruzzo — Tue, 20 Oct 2026 11:20:33 +0000

In breve: consegnate un runbook, un set di valutazione del cliente, versioni fissate con rollback, un responsabile degli avvisi e un registro leggibile.

Un agente AI funziona il giorno della consegna. Che funzioni ancora dopo sei mesi dipende da chi ne risponde e da cosa ha in mano. Il passaggio di consegne fa parte del progetto, non è una riunione finale.

Cosa cambia quando nessuno lo tocca

Gli agenti peggiorano anche senza che nessuno li modifichi. Il fornitore del modello ritira una versione, e l'alias su cui contavate ora punta a qualcos'altro. Un'API a monte rinomina o toglie un campo. I documenti che l'agente legge si allontanano da quelli su cui è stato provato: modelli nuovi, codici articolo nuovi, un modo diverso di scrivere la stessa cosa. Niente di tutto questo compare in una revisione del codice, perché il codice non è cambiato. Compare come un errore davanti a un cliente, di solito notato da qualcuno che non sa perché sia successo.

Cinque cose che escono insieme al sistema

La prima è un runbook. Dice cosa l'agente può fare, cosa non deve mai fare, su quali sistemi può scrivere e cosa fare quando si comporta in modo strano. Scritto per chi è reperibile, non per lo sviluppatore che l'ha costruito.

La seconda è il set di valutazione, di proprietà del cliente. Se le domande e le risposte attese esistono solo sul portatile del fornitore, il cliente non può verificare nulla dopo una modifica. Con il set in mano può rilanciarlo dopo un aggiornamento del modello, una modifica al prompt o un nuovo lotto di documenti, e confrontare con l'ultimo risultato.

La terza sono le versioni fissate, con un rollback scritto. Modello, prompt e indice sono registrati come versioni esatte, e la strada per tornare alla combinazione precedente è un passaggio documentato, non un ricordo.

La quarta è una persona indicata a ricevere gli avvisi, che non sia chi ha costruito il sistema. Un avviso che arriva in una casella che nessuno legge equivale a nessun avviso.

La quinta è il registro delle decisioni, con un modo di leggerlo che non dipenda dal fornitore. Quando qualcuno chiede perché l'agente ha fatto una certa cosa a marzo, la risposta non deve richiedere una telefonata a voi.

A chi arriva il primo messaggio

Pensate al primo avviso di ritiro di un modello. Se set di valutazione e versioni fissate sono in mano al cliente, è una voce di calendario: si pianifica una prova, si confronta, si passa alla nuova versione. Se non lo sono, è un'emergenza che cade su chi ha costruito il sistema, in un momento che non ha scelto. Per una software house è anche un problema di margine, perché l'assistenza informale illimitata raramente è nel prezzo. E se il sistema rientra tra quelli ad alto rischio dell'AI Act, chi lo impiega ha obblighi di sorveglianza sul suo funzionamento: dovrà poterli esercitare senza passare da voi.

La manutenzione è un vincolo di progetto

Un contratto di assistenza aggiunto dopo la consegna non rimedia a un sistema costruito per essere capito solo dai suoi autori. Il vincolo va posto dal primo sprint: cosa potrà far funzionare, controllare e cambiare il cliente senza di noi? Progettare così rende la costruzione un po' più lenta e gli anni successivi molto più tranquilli.

Tra un anno, quando l'agente sbaglia, a chi arriva il primo messaggio?

Testo completo: la checklist completa del passaggio di consegne

Articolo originale: https://www.omarbaruzzo.it/it/blog/agente-ai-dopo-la-consegna

Who maintains the agent after you hand it over?

Omar Baruzzo — Tue, 20 Oct 2026 11:16:55 +0000

TL;DR: ship a runbook, a client-owned eval set, pinned versions with a rollback, a named alert owner and a readable decision log.

An AI agent works on delivery day. What decides whether it still works six months later is who owns it afterwards, and whether that person has what they need. Handover is part of the build, not a meeting at the end.

What changes when nobody touches it

Agents decay without anyone editing them. The model provider retires a version, and the alias you relied on now points at something else. An upstream API renames or drops a field. The documents the agent reads drift away from the ones it was tested on: new templates, new product codes, a different way of writing the same thing. None of this shows up in a code review, because no code changed. It shows up as a mistake in front of a customer, usually noticed first by someone who does not know why it happened.

Five things that leave with the system

The first is a runbook. It says what the agent is allowed to do, what it must never do, which systems it can write to, and what to do when it behaves strangely. It is written for the person on call, not for the developer who built it.

The second is the evaluation set, owned by the client. If the questions and the expected answers live only on the vendor's laptop, the client cannot check anything after a change. With the set in their hands, they can re-run it after a model update, a prompt edit or a new batch of documents, and compare with the last result.

The third is pinned versions with a written rollback. Model, prompt and index are recorded as exact versions, and the way back to the previous combination is a documented step, not a memory.

The fourth is a named recipient for alerts, and it is not the person who built the system. An alert that goes to a mailbox nobody reads is the same as no alert.

The fifth is the decision log, with a way to read it that does not depend on the supplier. When someone asks why the agent did something in March, the answer should not require a phone call to the vendor.

Who gets the first message

Consider the first model deprecation notice. If the eval set and the pinned versions are in the client's hands, it is a calendar item: schedule a test, compare, switch. If they are not, it is an emergency that lands on whoever built the system, at a time they did not choose. That is also a cost problem for the supplier, because unlimited informal support is rarely in the price.

Maintenance is a design constraint

A support contract added after delivery cannot fix a system that was built to be understood only by its authors. The constraint has to be there from the first sprint: what will the client be able to run, check and change without us? Designing for that makes the build slightly slower and the following years considerably calmer.

When your agent breaks in a year, who gets the first message?

Full text: the full handover checklist

Articolo originale: https://www.omarbaruzzo.it/en/blog/agente-ai-dopo-la-consegna

Ne počinjite s vektorskom bazom

Omar Baruzzo — Thu, 15 Oct 2026 11:23:32 +0000

Ukratko: izgradite baseline s pretragom koju već imate, ocijenite je na stvarnim pitanjima i dodajte embeddinge samo tamo gdje eval set pokaže razliku.

Pogledajte pitanja koja ljudi postavljaju

Prikupite stvarna pitanja od ljudi koji će koristiti asistenta, a ne izmišljena. Razvrstajte ih. Velik dio obično su lookup pitanja: broj ugovora, ime klijenta, raspon datuma, šifra artikla, osoba. Vector search uspoređuje značenje približno, i upravo zato je slab kod točnih podudaranja. Pretraga po ključnim riječima i SQL filter su suprotni: precizni na identifikatorima, slabi kad pitanje koristi drugačije riječi od dokumenta. Oboje je već u vašem stacku.

Prvo izgradite baseline

Zapišite kako izgleda točan odgovor za skup od pedesetak pitanja. Provedite ih kroz full-text pretragu i strukturirane filtere i zabilježite koliko ih se vrati točno. Taj rezultat je baseline i sve što se kasnije doda mora ga nadmašiti. Bez njega dodavanje vektora ne možete nazvati poboljšanjem. Možete ga nazvati samo promjenom.

Vektore dodajte tamo gdje baseline zakaže

Embeddinzi zaslužuju svoje mjesto kad je problem rječnik: korisnik pita kako prije roka prekinuti najam, a dokument govori o prijevremenom raskidu zakupa. Kad eval set pokaže tu klasu pogrešaka, hybrid retrieval je opravdan: ključne riječi plus vektori, rezultati spojeni. Tada se dobitak može izmjeriti i odlučiti vrijedi li onoliko koliko košta.

Cijena još jednog storea

Vektorski indeks je kopija vaših dokumenata. Mora ostati usklađen s izvorom, ponovno se graditi kad se promijeni embedding model i provoditi ista prava pristupa kao sustav koji kopira. Tko ne može otvoriti dokument u originalnoj aplikaciji, ne smije ga moći dohvatiti ni preko asistenta. Greške u pravima na kopiji su tihe i teško se nalaze, a kad su u pitanju osobni podaci, to je i problem usklađenosti.

Ništa od ovoga nije argument protiv vektorske pretrage. To je argument o redoslijedu posla. Tim s izmjerenim baselineom može reći što su embeddinzi dodali. Tim bez njega može reći samo da asistent sada djeluje bolje. Kad stigne sljedeća verzija modela ili indeksa, prvi tim ponovno pokrene skup pitanja i zna isplati li se prijeći. Embeddinzi su koristan alat, samo ne prvi.

Krenite od dosadne pretrage, izmjerite je i pustite da vam pogreške kažu što dodati.

Koja su pitanja u vašem asistentu zapravo lookupi u prerušavanju?

Cijeli tekst: izvorni članak s cjelovitim obrazloženjem

Articolo originale: https://www.omarbaruzzo.it/hr/blog/ricerca-classica-prima-dei-vettori

Non partire dal database vettoriale

Omar Baruzzo — Thu, 15 Oct 2026 11:22:51 +0000

In breve: costruite una base con la ricerca che avete già, valutatela su domande reali e aggiungete gli embedding solo dove il set di valutazione mostra il divario.

Guardate le domande che le persone fanno

Raccogliete domande reali da chi userà l'assistente, non inventate. Ordinatele. Una quota grande è di solito ricerca puntuale: un numero di contratto, il nome di un cliente, un intervallo di date, un codice articolo, una persona. La ricerca vettoriale confronta il significato in modo approssimato, ed è proprio per questo che è debole sulle corrispondenze esatte. La ricerca per parole chiave e un filtro SQL sono l'opposto: precisi sugli identificativi, scarsi quando la domanda usa parole diverse dal documento. Entrambi sono già nel vostro stack.

Costruite prima la base di confronto

Scrivete com'è una risposta corretta per un insieme di una cinquantina di domande. Provatele con la ricerca full-text e con i filtri strutturati, e annotate quante tornano giuste. Quel risultato è la base di confronto, ed è ciò che ogni aggiunta successiva deve battere. Senza, aggiungere i vettori non si può chiamare un miglioramento. Si può chiamare solo un cambiamento.

Aggiungete i vettori dove la base fallisce

Gli embedding si guadagnano il posto quando il problema è il vocabolario: l'utente chiede come chiudere un affitto in anticipo e il documento parla di recesso anticipato dalla locazione. Quando il set di valutazione mostra quella classe di errori, la ricerca ibrida è giustificata: parole chiave più vettori, risultati uniti. A quel punto il guadagno si misura e si decide se vale quanto costa.

Il costo di un archivio in più

Un indice vettoriale è una copia dei vostri documenti. Va tenuto allineato alla fonte, ricostruito quando cambia il modello di embedding, e deve far rispettare gli stessi diritti di accesso del sistema che copia. Chi non può aprire un documento nell'applicazione originale non deve poterlo recuperare tramite l'assistente. Gli errori di permessi in una copia sono silenziosi e difficili da trovare, e quando ci sono dati personali sono anche un problema di conformità.

Niente di tutto questo è un argomento contro la ricerca vettoriale. È un argomento sull'ordine del lavoro. Un team con una base misurata può dire cosa hanno aggiunto gli embedding. Un team senza può dire solo che l'assistente adesso sembra migliore. Quando arriva la versione successiva del modello o dell'indice, il primo team rilancia il set di domande e sa se conviene cambiare.

Partite dalla ricerca noiosa, misuratela, e lasciate che siano gli errori a dirvi cosa aggiungere.

Quali domande del vostro assistente sono ricerche puntuali travestite?

Testo completo: la versione originale con il ragionamento completo

Articolo originale: https://www.omarbaruzzo.it/it/blog/ricerca-classica-prima-dei-vettori

Do not start with a vector database

Omar Baruzzo — Thu, 15 Oct 2026 11:21:17 +0000

TL;DR: build a baseline with the search you already have, score it on real questions, and add embeddings only where the eval set shows the gap.

Look at the questions people ask

Collect real questions from the people who will use the assistant, not invented ones. Sort them. A large share is usually lookup: a contract number, a customer name, a date range, a product code, a person. Vector search matches meaning approximately, which is exactly what makes it weak at exact matches. Keyword search and a SQL filter are the opposite: precise on identifiers, poor when the question uses different words from the document. Both are in your stack already.

Build the baseline first

Write down what a correct answer looks like for a set of fifty or so questions. Run them against full-text search and structured filters, and record how many come back right. That result is the baseline, and it is what every later addition has to beat. Without it, adding vectors cannot be called an improvement. It can only be called a change.

Add vectors where the baseline fails

Embeddings earn their place when the failure is vocabulary: the user asks about ending a rental early, and the document says early termination of the lease. When the eval set shows that class of failure, hybrid retrieval is justified: keyword plus vector, results merged. You can then measure the gain it brings, and decide whether it is worth what it costs.

The cost of one more store

A vector index is a copy of your documents. It has to be kept in sync with the source, rebuilt when the embedding model changes, and it has to enforce the same access rights as the system it copies. A user who cannot open a document in the original application must not be able to retrieve it through the assistant. Permission mistakes in a copy are quiet and hard to find, and when personal data is involved they are also a compliance problem.

None of this argues against vector search. It argues for an order of work. A team with a scored baseline can say what embeddings added. A team without one can only say the assistant now feels better. When the next model or index version arrives, the first team re-runs the question set and knows whether to switch.

Start with the boring retrieval, measure it, and let the failures tell you what to add.

Which questions in your assistant are lookups in disguise?

Full text: the original write-up with the full reasoning

Articolo originale: https://www.omarbaruzzo.it/en/blog/ricerca-classica-prima-dei-vettori