What this is. Opinion + Experience + Fact (45% opinion · 30% experience · 20% fact · 5% fiction). Written in collaboration with AI — I discuss, I do not outsource.

1. The reader that runs your code

A while back I argued that AI can write your frontend but has a hard time with your firmware — not because the model is weak, but because the structure it needs to reason about is rarely written down. That post named the gap. This one is the concrete answer: seven specific things that make a firmware codebase legible to an AI agent, each one addressable today, each one already part of a structured application layer above the RTOS.

This is for the firmware lead who has watched a capable agent write a clean driver and then lose the thread the moment it had to reason about the whole system. The seven things below are what closes that gap. None of them are exotic. Each is a property you can point at in a codebase and say "we have this" or "we do not have this yet." By the end you will have a one-page table you can run against your own project.

The frame that matters: there is now a second reader of every firmware codebase. The first reader is the team — the next hire, the on-call engineer at 2am. The second reader is the agent that extends a feature, runs the tests, and reads the output. The same properties serve both. Writing for the machine is, almost entirely, writing clearly for the human.

▸ First principle. An AI agent is the second reader of your codebase. The structure that makes it legible to the agent is the same structure that makes it legible to the next engineer.

2. Readable is not the same as writable

There is a useful distinction hiding here. An agent can write a function from a clear prompt — that has been true for a while. What an agent has a hard time doing is reading a system well enough to safely extend it. Those are different skills, and firmware tends to be strong on the first and thin on the second.

Readable means the agent can answer four questions from the code alone, without a tribal-knowledge phone call. What talks to what? What is the contract at each boundary? What state can the system be in? What actually happened at runtime? Most firmware answers those questions in the heads of the two engineers who wrote it. A readable codebase answers them on disk, in a form both the human and the agent parse the same way.

The seven properties below each turn one of those questions from tribal knowledge into written structure. They are not AI features bolted on. They are ordinary good architecture, viewed through the lens of a new reader who happens to be very fast and very literal.

▸ First principle. Writable is about generating a function. Readable is about extending a system. Firmware's gap has always been the second one — and the second reader makes closing it urgent.

3. The seven, on one page

Here is the whole argument as a table. Column one is what an agent needs to reason about a firmware system. Column two is what most firmware offers today. Column three is what a structured application layer above the RTOS provides instead. Copy it and mark each row for your own project.

#What the agent needsWhat most firmware hasWhat a structured layer gives
1Typed message schemasad-hoc structs, void*declared message types in one registry
2Table-driven state machinesswitch/case across three filesflat (state, event, next) tables
3Formal contractscomments, if anypre/postconditions per interface
4Module metadatanaming conventionsa manifest each module publishes
5Host-side executiontarget-only buildsthe same code runs on a laptop
6Observability streamsfree-form printfbounded event taxonomy, captured
7Deterministic replay"works on my bench"record a run, replay it byte-for-byte

Read column two honestly. Most of it is not bad engineering — it is engineering written for one reader, the author, at the moment of writing. The third column is the same intent written for three readers across the life of the product. The work is the same size. The payoff lands every time a new reader, human or machine, opens the code.

▸ First principle. Every row is a question the agent must answer. The middle column answers it in someone's head; the right column answers it on disk.

4. Structure an agent can parse

The first three rows are about shape — the static structure the agent reads before it changes anything.

Typed message schemas. When modules talk through declared message types held in one registry, the agent can enumerate every message a module sends and receives and reason about the contract. When they talk through ad-hoc structs passed as void*, the agent has to guess from call sites, and guessing is where it goes wrong. A typed schema is a map; an untyped one is a rumor.

Table-driven state machines. A state machine spread across switch statements in three files is a puzzle even for the engineer who wrote it. The same machine as a flat (state, event, guard, next_state) table is something the agent reads top to bottom and reasons about completely — every transition visible, every gap obvious. I made this argument in full in the post on state machines as tables; the AI-readability payoff is the same one, seen from the agent's side.

Formal contracts. A module boundary with a written contract — what it expects, what it guarantees — lets the agent extend a caller without reading the implementation. A boundary documented only by a comment, or by nothing, forces the agent to infer the contract from the body, and an inferred contract is the thing that breaks when the body changes next quarter.

▸ First principle. Static structure is the part the agent reads before it touches anything. Typed messages, table FSMs, and written contracts turn three guessing games into three lookups.

5. A manifest and a place to run

The next two rows are about discovery and execution — how the agent finds the pieces and how it checks its own work.

Module metadata. When each module publishes a small manifest — what it is, what it depends on, what messages it owns, what it configures — the agent can build a map of the system without reading every line. Naming conventions are a weaker version of the same idea: they hold until they slip, and the agent has to take it on faith that every module followed the convention, including the ones that only look like they did. A declared manifest is a fact; a convention is a hope.

Host-side execution. This is the one that turns reading into a loop. When the same firmware runs on a laptop with a faked HAL — the move from the last post — the agent does not just read the code, it runs it. Extend a feature, run make run-host, read the scenario trace, confirm the behavior. That is the same inner loop a human uses, at the same speed. Without it, the agent writes a change and hands it back unverified, which is the worst kind of help. With it, the agent closes its own loop.

▸ First principle. A manifest lets the agent find the pieces. Host execution lets it check its own work. Together they turn a static read into a build-run-confirm loop.

6. A record it can read, and replay

The last two rows are about runtime — what the system did, captured in a form the agent can use.

Observability event streams. A bounded event taxonomy — boot, message, state change, fault, the few categories that matter — captured by default, gives the agent a structured record of what actually happened. Free-form printf gives it a wall of strings to parse with a regular expression and a prayer. The structured stream is the difference between an agent that can say "the heater FSM entered fault after three timeouts" and one that can only echo back log lines.

Deterministic replay. The strongest property of the seven. When a run can be recorded and replayed byte-for-byte — same inputs, same timing, same result — a field bug stops being a story and becomes an artifact. The agent replays the failing run, watches the exact transition that went wrong, proposes a fix, and replays again to confirm. "Works on my bench" becomes "here is the run, reproduce it." That is the loop that finally lets an agent debug a system rather than just describe it.

▸ First principle. A structured event stream is the system's account of what it did. Deterministic replay turns that account into something the agent can re-run, reason about, and verify a fix against.

7. Readable is a property you design in

None of the seven is an AI feature. Every one is a property a strong embedded team already values for its own sake — typed interfaces, legible state, written contracts, fast loops, clean records. The new fact is that a second reader has arrived, and that reader rewards exactly the structure good engineers were already trying to justify to their schedules.

That is the quiet good news in all of this. You do not adopt a different architecture to make firmware AI-readable. You adopt the architecture you already wanted, and the agent is the forcing function that finally makes the case for it. A structured application layer above the RTOS — typed messages, table FSMs, contracts, manifests, host execution, observability, replay — is AI-readable as a side effect of being well-built.

Run the table against your own project. Most teams find they already have two or three rows and are one decision away from two or three more. The gap is rarely capability. It is usually that no one named these as properties worth designing for — until a very fast, very literal reader started reading along.

▸ First principle. AI-readability is not a new architecture. It is the architecture you already wanted, with a second reader that finally makes the schedule case for it.

Which of the seven does your firmware already have on disk — and which one is still living in the heads of the two people who wrote it?

Next: of all the modules every embedded team rebuilds, OTA is the one I've watched the same engineer write five different ways across five products. There's a better answer.

Labeled: Opinion + Experience + Fact (45% opinion · 30% experience · 20% fact · 5% fiction)

Sources:

(Written in collaboration with AI — I discuss, I do not outsource.)

New to this labeling? Read the framework → 20+ Years of Ideas. Articulation Is the Craft.

— Ritesh | ritzylab.com

#EmbeddedSystems #Firmware #AIAgents #SystemsArchitecture #FirstPrinciples