“Tests are documentation” is useful advice, up to a point. A well-written test can show how a component behaves and what its callers may expect.
But it is easy to ask tests to explain more than they can. This becomes particularly noticeable when an AI assistant is asked to change an unfamiliar project.
Consider a command handler in a system that uses CQRS and event sourcing. Its tests show that a valid command produces an event and an invalid command is rejected. An assistant can read those tests, implement another handler, and write new tests following the same pattern.
It may still miss why the team chose events rather than updating a database record directly. Perhaps every change must be available to another service. Perhaps the event history is needed for an audit. The tests show the expected behaviour, but they may not reveal which of those reasons matters.
A developer new to the project faces the same problem. The difference is that a developer can ask the team. That works when the right person is available and still remembers the decision. It is a fragile way to preserve architectural context.
What Tests Can Tell Us
Tests are particularly good at recording examples:
- Given these inputs, the system produces this result.
- This module expects this behaviour from another module.
- This bug must not reappear.
Tests can also enforce some architectural rules. In a solution, for example, a test can check that the domain project does not reference infrastructure. Such a test tells both developers and AI assistants that the boundary exists. It can fail if they cross it.
It usually cannot explain why the boundary exists. The reason might involve deployment, team ownership, or a problem the team encountered years ago.
Recording the Missing Context
The answer does not have to be a large architecture document. A short note near the relevant code or an architecture decision record can explain the decision, its reasons, and when it should be reconsidered.
For the command handler, that note might say why changes are recorded as events, which operations must follow this rule, and whether any exceptions exist. An AI assistant can use that context when making a change. A new developer can use it to ask better questions.
Tests remain valuable. They show what the code is expected to do and warn us when we change it. But if we want someone, human or AI, to preserve an architectural decision, we should make that decision visible as well.