Context

The AI reads why, not just what.

We've all been down this road. You ask an AI to build a feature, it comes back brimming with confidence, and then you open it in UAT and your heart sinks. The AI can write code perfectly well. The trouble is that it had to guess why your system works the way it does, and it guessed with a completely straight face.

Most codebases record what the software does and almost nothing about why. Most development shops skip the decision records altogether, which leaves the AI to work out the reasons from the code, and code is a poor witness to its own history. So we write the reasons down before the code, and the AI reads them first.

Where the AI's context comes fromThe operator and the outside world feed the AI. The knowledge base feeds it from below. What it builds is recorded back into the knowledge base.The operatorintent and prioritiesrulings at the grillThe outside worldISO 20022 · IFRS · banking practicemarket and competitor analysisThe AIreasons from intentdesign · build · debug · reviewThe changecode, tests, screensa help articleThe knowledge baseconcept models · decision records · plans · the rulebook · standards · findings · lessonswhy it is the way it is, what was rejected, and what actually happenedread firstrecorded back
You and the outside world feed the AI, the knowledge base is read first, and every change goes back into it.
We've believed this for a while

From Rational Rose to decision records

In 1999 we modelled CreditPlus in Rational Rose and generated the framework code from the models. The idea was the same one we hold now, that you write the intent down first and let the code follow from it. The difference is the reader. A code generator in 1999 could only turn boxes into classes. Today the reader is an AI that can follow an argument, weigh a rejected option and notice when a request contradicts a decision we made three months ago.

So every change starts in writing, in three layers. A model page says what a concept actually is. The AI writes the design from it, with our guidance, and we review it before anything is built. A decision record says how we got there: the options, the pros and cons, what we turned down and why, and once it ships, a short note of what actually happened rather than what we intended. A plan says what gets built, down to every file each step touches and the scenarios the tests must pass, and because the code is organised by feature rather than by layer, that list is usually short enough to hold in your head. Across all three sit a rulebook for how code is shaped here and a register of every external standard we follow, ISO 20022, ISO 4217, IFRS and the rest, with every place we deliberately depart from one.

What the AI does with it

It reasons faster

It starts from the decision instead of reverse-engineering the code. When it asks "why is it like this?", there's a written answer, usually with the alternatives we threw out.

It debugs against intent

A defect is a gap between what we decided and what the code does, and the record tells you which side is wrong. That matters more than it sounds, because a passing test can quite happily encode a bug.

It asks "have we done this before?"

Before naming anything new, the plan goes looking for prior art and decides whether to reuse, extend or start fresh. That's where consistency comes from, in the code and on the screens.

It brings in the outside world

Standards, industry practice, and market and competitor analysis all feed the design. One of the four seats at every design review is a salesperson asking what an incumbent would charge for the same thing as a custom build.

A worked example

Three features that turned out to be one

A notice account, a card reservation and a pending debit order look like three different features, and in most systems they're built as three. They're really one thing: money that's in the account but not free to spend, a claim against the available balance.

The rulebook tells the AI to look for the general concept before it adds a field named after a product, and the decision record that pulled those three together says where the concept lives and why. So when a new product needs to hold money back, it becomes configuration on that one concept, instead of a fourth mechanism that slowly drifts away from the other three. We've lived with the drifting kind. It isn't fun at month-end.

It gets better on its own

Every piece of work leaves something behind

Most teams learn things in a retrospective that nobody reads again. We write down what the work teaches us, in the same place the AI looks, and the lessons that keep coming back get turned into checks that the build runs, so nobody has to remember them.

The learning loop: work, finding, triage, lesson or decision, checkFive steps left to right. The last feeds the next piece of work.The workgrill · build · land · sweepFindingone line, sized, sourcedWeekly triagepromote · park · closeLesson or decisionwhat it taught, writtenA check that runshook · script · testThe next change starts with it
Nothing we notice gets lost, and nothing we learn stays in someone's head.

We harvest the issues the work throws up. If a session spots something out of scope, it doesn't fix it in passing, it records it as a finding, and every change that lands records what it taught us. Once a week we sort through the lot: some become decision records, some are parked, and the ones that keep coming back are turned into checks that run, so the same mistake gets harder to make twice. We don't change the process after one bad day, though. Once is a finding, twice is a pattern.

Why this matters now

There are two camps in AI development at the moment, and they're both a bit wrong for the same reason. One says AI is amazing but generates rubbish, and half of them have no paid plan, no context and no memory. The other thinks it can vibe-code everything, and it may well look good on screen, but don't look behind it, because it'll be a mess and it will cost you down the line. Without standards and context you get one or the other.

The record today
  1. 883 decision recordseach with its reasons, and an outcome once shipped
  2. 499 plansfiles touched, steps and acceptance criteria
  3. 101 standardson the register, with what we follow and where we depart from it
  4. 2,657 findingsraised from the work, 50 of them promoted to decision records
  5. 209 lessonsrecorded as changes landed
  6. 198 guide articlesshipped in the same commit as the screen they explain

The decision records, plans and rulebook ship with the source. If your team takes the engine on, their AI starts on day one with the reasons, not a guess at them, and with a process that has spent months learning from its own mistakes.