← Back to Blog

Contract - a new unit of information for AI. Will it change how AI thinks and writes? We already know, because we have the results

AITM contract graph: hundreds of connected nodes around a central contract

When you start a new greenfield project, AI coding feels like pure magic. You type a prompt and the model effortlessly generates a clean component or a working backend endpoint.

But as the codebase grows, reality sets in.

Around 100,000 lines of code, ordinary AI starts to noticeably run out of steam. It guesses, searches the repository blindly and hallucinates functions that don't exist. Around 300,000 lines, the model's independent judgment practically collapses - the context window isn't enough, classic grepping of the whole project burns thousands of tokens, and development turns into an endless cycle of fixing broken code.

This is exactly where system contracts take over.

What is a contract in AITM?

A contract is not an ordinary inline code comment, nor a line in a forgotten README.md that stops being true after two sprints.

It is machine-queryable system behavior.

It describes exactly what a specific part of the application is supposed to do, and points to the exact source files, tests and UI elements. Instead of groping around and reading dozens of files, the agent asks the system a direct question: "Where and how is this behavior implemented?" - and instantly gets a precise answer.

Every contract in AITM rests on three key pillars:

  • behavior - A one-line essence of what the code does. The most important field of all. The agent compares this rule with the actual implementation in the file. If they contradict each other, the system immediately knows it is either a bug or an outdated contract.
  • confidence - A measure of how trustworthy the information is. It tells you how reliable the description is relative to other data in the system (e.g. whether the behavior has been verified by real tests).
  • variables - A link to the system's shared communication language (e.g. BL.PIPELINE). It acts as a bridge between business logic on the frontend and backend, so contracts can be filtered instantly by a specific part of the UI or the data layer.

A real example from production

In AITM a contract is structured and instantly available through the GraphQL API:

contractsForFile(path: "src/pipeline/MergeQueueService.ts", projectId: "ctm-dashboard") {
  id          # "GM-057"
  module      # "Git/Merge"
  behavior    # "Self-merge restart is manual: after a merge, dev-watch keeps serving
              #  the pre-merge code until the user clicks Restart in the menu, or
              #  Settings.selfMergeRestartMode is 'auto'."
  confidence  # "tested"
}

This is the fundamental difference from static documentation. The agent requests the contract before it even opens or writes a single line of code. It doesn't act blindly, doesn't waste context, and knows exactly how much weight to give the rule.

Saving tokens and compute: Claude Sonnet at Low-Medium effort

One of the biggest benefits of precise guidance through contracts is the efficiency of the AI model itself.

In AITM our agents run on Claude Sonnet with Low to Medium effort (thinking). When the model has a precise contract available, it doesn't need minutes of "thinking", speculating about the architecture of the whole repository or burning a huge reasoning budget on trivial research.

Thanks to the contract, the model is handed a ready-made map:

  • It knows exactly which file to go to.
  • It knows the expected behavior (behavior).
  • It knows how much to trust the information (confidence).

So even at lower effort, Claude Sonnet delivers fully deterministic, clean work, because it doesn't have to rely on its own "guess" and strictly follows the given specification.

The result on 500K lines of code

The real power of this approach doesn't show in the first days of a project, but when the codebase grows to enterprise scale.

In our own system with more than 500,000 lines of code, roughly 3,500 contracts now run reliably:

  • No more blind grepping: The agent doesn't search hundreds of files, it goes straight to what is certain.
  • A radical reduction in tokens and hallucinations: The context window stays clean and the model doesn't suffer from information overload.
  • Consistent results: Even on a half-million-line project, the AI achieves the same speed and accuracy as with the first prompt on an empty repository.