Technically perfect, practically wrong – Corpus 1/3

Text: Arttu Ylärakkola

Before AI, business stakeholders complained that features weren't being delivered quickly enough. Developers, on the other hand, grumbled that the existing backlog was already taking up all their time and that there was no room for new features.

Now code is written faster than ever. Yet the complaints haven't stopped – they have merely changed shape.

Debt that isn't visible in the code

Technical debt is a familiar concept: cut corners now, pay later.

Cognitive debt is a trickier case, because it accumulates even when the code is clean, tested, and bug-free. Features are completed faster than anyone can actually digest them.

On the business side, no one has an up-to-date grasp of how the software really behaves anymore. Within the development team, the problem is different: software is always greater than the sum of its parts, and when ever-less time is spent on a single feature, its wider impact on the system is left unconsidered.

In this way, the big picture slips out of grasp, one piece at a time.

Code shows how, not why

AI is exceptionally good at reading code, and the code explains how the system works. What it typically doesn't reveal is:

• why a certain rule exists,

• what customer promise the rule protects,

• what was once tried and why it was discarded,

• which edge cases aren't visible in the code or tests, and

• what "done" means for the business, not just for the tests.

For example, in a billing system, an invoice is issued only three days after an order. The delay is visible in the code, but the reason is not: customers have been promised time to cancel their order without the hassle of credit notes.

Then someone in a hurry writes a ticket to "speed up billing". The AI removes the delay, updates the tests, and submits a neat pull request. The reviewer sees the code looks good and approves it.

Technically flawless, but practically wrong.

What can be done about it?

In our own projects, we gradually evolved a way of working that we ultimately named Corpus. The whole concept boils down to three points:

1. Create a directory in the project's version control.

2. Add Markdown files there that describe the business context for both humans and AI: terminology, user roles and their motivations, and process flows.

3. Update the files with every commit.

The crucial shift lies in that last point. Without Corpus, a delivery is just code; with Corpus, a delivery is code plus a small update to Corpus.

During the implementation phase, the AI can see the business rules and previous decisions. When there are multiple technically viable options, it knows how to choose the one that also aligns with the business.

During code review, the Corpus diff explains in plain language what the change means. In the billing example, the diff would show a line reading "invoice goes out immediately after order". That can be read and stopped even by someone who has never opened a code editor in their life.

Is this suitable for everything?

No. A tightly specified, purely technical backend service with rigid interfaces gains virtually nothing from Corpus. The more user journeys and processes a project contains, the more helpful it becomes.

In the next part, I will share what happened when we started comparing Corpus and the code automatically.

Read all parts of the Corpus series:

1/3: Technically flawless, practically wrong: why fast code generates cognitive debt (or wait, you just read that one!)

2/3: Code wrong, Corpus wrong, or both? Three contradictions that reveal more than tests

3/3: Corpus in its own repo: what to put in the directory and what to leave out

What is Corpus?

Corpus is a directory of Markdown files in a project's version control. They describe the system at a business level: terminology, user roles and their motivations, process flows, and decisions made. The files can be read by a developer, a business person, or an AI, and they are updated whenever the system's behaviour changes.

Code tells the AI how the system works. Corpus tells it why.

Corpus is not a product and requires no licence. It is simply a version-controlled directory of text files, so it works with any language, tool, and methodology. We don't claim to have invented it. We naturally arrived at this way of working in our own projects and named it Corpus.

Example repo: github.com/rakettitiede/corpus

Want to try it in your own project? Drop Arttu a line, let's chat, and get a Corpus PDF to get you started over a single coffee break: arttu@rakettitiede.com