AI engineering

This is the long note. The short version is in Systems in operation.

What exists today

One skill per tool or operational domain of the house. Automatic hooks, in pairs for the two operating systems the team uses. Command-line tools covering service desk, database, logs, identity, versions, standards and context. The rules of the code standard. And a test suite larger than the tooling itself, which is a merge request gate.

It installs and updates with the same command, has a check mode that writes nothing, and a non-interactive mode to repeat the configuration on a second machine.

It stopped being mine. Today other people in engineering commit to it, and that is the test that matters: tooling only its author maintains is personal configuration with a nice name.

The pieces

The cycle is what closes the design. It consumes the other pieces and gives capability back to them, without me having to push.

• Tool as CLI: an agent that cannot act on the real tools is a chat window. Making each tool addressable from the command line is what turns it into an operator
• A standard the machine consumes: the house standard written once, materialized in the format each AI tool understands, with skills pointing to the CLIs
• The cycle that feeds itself: a problem that cost a lot becomes a record, a repeated record becomes an opportunity, an opportunity becomes a new skill. Even the promotion is automatic

What holds the design up

Knowledge lives once, the adapter is disposable

The knowledge, what a tool does, which trap it has, what the house standard is, sits in a single layer. The format a specific AI tool consumes sits in another, isolated as an adapter.

The consequence is the one that matters: switching AI tools tomorrow is writing a sibling adapter, not rewriting the knowledge. Agent tooling is the market that changes the most today; tying years of operational knowledge to one vendor’s format would be buying debt with a due date.

Synchronization, not installation

The command is not a first-time one: it runs as many times as needed. A piece of the tooling whose version changed is rewritten; the user’s own content is never touched.

That separation is what lets the same command serve to install and to update, and it is what allows distributing to the team without fear: nobody loses their personal configuration when the new version arrives. That is why the command stopped being called “install”: the wrong name invited the wrong use.

Writing graded by blast radius

All the tooling belongs to the team: anyone in engineering proposes changes. But the pieces whose mistakes reach far require review from whoever leads: the automatic hooks, the context common to all sessions, the code standard, the commands that write to sensitive systems, and the synchronizer itself.

It is not hierarchy by status. It is blast radius: a mistake in a query skill gets in the way of whoever used it; a mistake in the commit hook or in the synchronizer hits every machine on the team on the next run.

The tooling has tests that prevent leaks

The suite is larger than the tooling itself, and two of those checks refuse the commit if something personal or identifiable enters the versioned prose: a token, an absolute machine path, a personal email, a credentials file.

Two decisions in those guards that I stand by:

Exemption is by name, never by directory. It is tempting to exempt testes/ as a whole, since the fixture needs to contain the dirty content. But an exempt directory shields forever, including against a real leak that lands there next year. Each exemption is for a specific file, and it only goes in when the finding cannot be solved by tightening the pattern.

A guard without a positive case is not a guard. Each detector has a test that plants the problem and requires it to be caught. Without that, a broken detector passes for a working one, which is exactly the kind of silent failure this tooling exists to avoid.

I learned this the expensive way, and the same principle is applied in this vault: the checker that prevents leaks here also has a positive fixture, because its first version approved a third of the files without looking and said “clean”.

AI in the product, not only in the process

Everything above is AI applied to how I build software. It is most of my work on the subject, but not all of it, and it is worth separating because they are different problems.

In Tender triage with an LLM the AI is inside the product: a model reads thousands of public tender notices a day, assigns a relevance score and the reason for it, and the system I built is the human curation layer on top of that: it sorts by the score, shows the why, and records the verdict of whoever decides.

The design decision that matters there is the division of labor: the model ranks, the person decides. Triage tolerates imprecision because an approximate ranking already cuts a thousand down to twenty; the decision to bid involves capacity, margin and the relationship with the agency, which are not in the document. And the reason comes with the score, otherwise the person rereads the notice to trust it and the gain evaporates.

Why this is an engineering skill

Because the bottleneck moved. When implementing gets cheap, the value migrates to whoever knows how to define the problem, verify the result and organize the context in which the work happens.

And there is a consequence I had not foreseen: the agent fails exactly where the documentation fails. When the convention is implicit, when the rule lives in someone’s head, when “that’s how we do it here” was never written down, that is where the result comes out wrong. Working this way forced me to make explicit what I should already have made explicit for people. The quality gain for the team came along with it, and it was not the stated goal.

What I changed in my own practice

The quality of the problem definition became the bottleneck. Understanding the problem, choosing the architecture and writing the acceptance criteria became where the result is decided. It is what Design before implementing already argued, now with an immediate practical consequence: the specification is what the agent executes.

Versioned context is infrastructure. What an agent needs to know about a repository (architecture, conventions, known traps, what not to do) lives in the repository, versioned like code. It is not a disposable prompt.

Verification is not optional. An agent produces a plausible result with the same confidence with which it produces a correct one. Every result goes through a test or a check against the source, and that check is my job. That is why the most interesting part of A standard the machine consumes is not the standard: it is the mechanism that makes a lying standard break the build.

How far it has come

The tooling is recent, and adoption per repository is still small, and I prefer to state where it already is rather than where I would like it to be. What is already distributed to the team is the base; repository-by-repository use comes later.

How this connects with the rest: Quality and context engineering is the skill that sustains it, and How I debug and How I work are where the practice shows up day to day.