Designing Sources of Truth

In traditional software development, code is considered the primary source of truth. A requirement becomes a task, the task becomes changes to files, and Git preserves the history of those changes.

In the world of AI-driven development, this model is beginning to change. If an agent can independently create, modify, and even completely regenerate code, a new question arises: what should remain the immutable source of truth?

The answer is not the code itself, but the knowledge from which that code is generated.

Code Is the Result, Not the Source

Consider a simple order-processing system. Its code contains a rule:

An order cannot be shipped until it has been paid for.

If this rule exists only inside several functions, it is tied to a particular implementation. When the service is rewritten, an agent may accidentally lose it.

In a regenerative model, the rule is elevated to the specification level:

Order cannot transition to SHIPPED
unless payment_status = PAID.

Now it is not an implementation detail, but a system invariant.

The agent can implement it in Go, Python, or Rust — but the result must comply with the rule.

A Source of Truth Should Describe Meaning

A good specification does not try to replace source code with a detailed description of every function.

It captures what must remain true regardless of the implementation:

• business rules;
• architectural constraints;
• API contracts;
• data schemas;
• invariants;
• security requirements;
• performance requirements;
• access controls;
• failure conditions;
• acceptance criteria.

For example, instead of:

The validatePayment() function must call checkBalance().

it is better to specify:

A payment cannot be confirmed
if the available balance is less than the payment amount.

The first description is tied to an implementation. The second survives its complete replacement.

A Source of Truth Must Be Verifiable

A textual requirement alone is not enough.

If the specification says:

The service must be fast.

the agent does not know what “fast” means.

A much more useful requirement is:

p95 latency < 200 ms
at 1000 RPS.

Now the requirement can be verified automatically.

A mature system therefore follows a chain:

Specification
      ↓
Generation
      ↓
Tests
      ↓
Validation
      ↓
Production

Tests become more than a way to check code. They become an executable part of the source of truth.

The Source of Truth Must Survive Implementation Changes

There is a simple test for a specification:

If we delete all generated code, can we reconstruct the system?

If the answer is yes, the architecture is genuinely moving toward a regenerative model.

If the answer is no, some of the system's knowledge is still hidden inside the code.

This does not mean all code must become disposable. Critical or highly complex components can remain stable and human-controlled. But it must be clear which code is derived and which artifacts contain the actual decisions.

Provenance Matters Too

The specification itself is not enough.

We also need to understand how a particular production artifact came into existence:

Requirement
    ↓
Architecture
    ↓
Contract
    ↓
Agent task
    ↓
Model
    ↓
Generation
    ↓
Code
    ↓
Tests
    ↓
Production

This is provenance — the lineage of a result.

When an agent generates a thousand lines of code, it is more important to understand not only the diff, but also:

what decision produced these changes and which rules do they implement?

The Biggest Mistake

The most dangerous mistake is treating everything as a source of truth.

If we simultaneously treat these as authoritative:

• legacy code;
• documentation;
• README files;
• prompts;
• tests;
• architecture diagrams;
• Jira tickets;

they will eventually contradict one another.

Sources of truth therefore need an explicit hierarchy and ownership.

For example:

Business rules
      ↓
Architecture
      ↓
Contracts
      ↓
Policies
      ↓
Generated implementation

If the code contradicts the contract, the code should be fixed.

If the contract contradicts an architectural rule, the conflict should be resolved at the architectural level.

The key is not to maintain every artifact as an equally authoritative truth.

A New Role for Engineers

In this model, engineers spend less time maintaining every line of code and more time designing the system that produces that code.

They define:

• rules;
• contracts;
• constraints;
• architectural boundaries;
• testable invariants;
• context for AI agents;
• validation mechanisms;
• decision provenance.

As a result, the central question of software development gradually changes.

Not:

“How do we write this code?”

But:

“How do we describe the system so that the correct implementation can be generated from that description again and again?”

That is the essence of designing sources of truth — creating a set of specifications, rules, and contracts that preserve the meaning of the system, even when its implementation changes completely.