When you’re working on a mature codebase, or even on a codebase that you wrote by yourself but haven’t touched for half a year or more, inevitably the time will come when you see a piece of code and go “Why on earth did someone do that?” - even if you know the someone was you.
With agentic coding, the timelines are compressed, and an agent who would like to change an existing piece of code must know the answer to that question.
There are basically three possible answers: firstly, this piece of code might be an expression/consequence of the core design of the respective component. In this case, it should probably be kept as is, or if it’s changed it’s worth double-checking with a human that the change still aligns with the core design.
Secondly, the piece of code might have a reason that was true when it was written, but not necessarily anymore. Maybe it was accommodating a legacy dependency that has been refactored, for example, or working around an older version of another component. In that case, the agent should understand the original reason, and only respect that in its code changes to the extent that it’s still relevant.
Finally, the piece of code might not have a particular reason behind it - just one of half a dozen possible reasonable options that a previous agent session happened to pick. Then there is no reason to respect it particularly, as long as the new version passes all tests (this assumes an extensive testing setup, but that is a sine qua non in agentic coding in any case).
Now comes the crux: how is an agent supposed to know which of these cases holds? That is what the proponents of “the ultimate source of truth about the code is the code” miss. The agent might make educated guesses, but that path does not tend to end well.
Our agent-coding workflow, which we have now open-sourced, addresses exactly that issue. The software is modelled at a high level by a LikeC4 model, consisting of a hierarchical collection of cross-linked nodes, corresponding to the software’s modules. The core normative design principles of a module are spelled out explicitly by the human in an .arc42.md document attached to the respective node (all part of the repo, of course), and can only be changed with explicit human consent.
Then, each PR workflow interviews the human about corner cases and design choices, and creates a complete set of OpenSpec artefacts, scenarios, design doc, and all, including all the choices made. As the PR is merged, that OpenSpec change is archived with it, creating a lasting record of the reasoning behind that PR.
So now an agent’s job is easy: first, it looks up the principles for the nodes that the code in question touches; if it finds nothing relevant there, it looks at the archived design docs for the PRs that created/changed the code in question, to see what the reasoning was at that time.
That gives it all the context it needs, and enough information to see which of the cases above applies.
The OpenSpec change archives and the normative principles are complementary: the former are a changelog, explaining each individual change’s reasoning at the time it was made. The latter are a concise summary of what must hold now. The former are descriptive - the OpenSpec specs emerging from this process describe in great detail how things currently behave; the latter are normative: they tell what principles should always hold, for current and future code (and each principle is tagged with its current compliance status, so you don’t have to make your current code perfectly compliant all at once before spelling them out).
Sounds too good to be true? We’ve been building the SLayer codebase for months now using this approach, and it’s working well for us. For an example of a juicy real-world principles document, see here.
Give it a try and see if it works for you!