System Reasoning

I was walking my kids to school and, for whatever reason, discussing AI. I was telling them about the frustration of working with people who rely on it too heavily. My oldest then offered a profound bit of wisdom:

If people use AI for everything, they won’t know how to do anything.

Bingo! He’s right. If you don’t take part in the work, you atrophy the same skills hardened through years of being in the work. The process is where skills, knowledge, and experience are forged. The harder the work is, the more the lessons stick. But it’s also the same space humans resist most. If you want to grow, you need to get comfortable with being uncomfortable.

I’ve spent a lot of time thinking about how to preserve judgement in a world where AI takes over the execution work and output moves faster than our understanding. The only way to keep up is to know where to focus.

Consider this scenario. You’re a longtime individual contributor who is now moving up into a managerial position. You no longer do the same tasks as part of your work, but you need to know how the work is being done in order to manage it. You “zoom out” to develop a better understanding of the entire system.

This is like the parable of The Blind Men and the Elephant. Each blind man touches one part of the elephant, stating what they think it is: the trunk is a snake, says one man; the tusk is a spear, says another; the leg a tree trunk, says a third blind man. Each man, in isolation, builds a mental model without understanding the larger whole. The elephant is a system of individual components. It’s only in the holistic representation of the entire elephant that you can understand what it is and how it works.

Systems are not understood through their component parts. They’re understood through the relationships between components, and the principles that govern their behavior.

AI is expanding capability faster than understanding

One of the key observations I’ve made while working with AI agents to write code is just how much it’s expanded the purview of each engineer. In the past, engineering teams relied on the diverse and collective skillset of the team to cover the broad spectrum of changes required. The front-end folks worked on the front end; the backend on the API and database; DevOps on servers and infra.

Now that’s shifting.

Equipped with your very own swarm of AI agents, you can work on any part of the stack. The implementation capability of each engineer is no longer limited to what they formally know and understand. It’s only limited by the risk of change they’re willing to accept. Risk-tolerant vibe-coders don’t care what part of the stack they’re changing. And the agents willingly abide. You are, after all, spending their currency-of-choice: tokens!

But there’s a catch.

The process of slowing down and engaging in system design discussions is how engineers maintained balance in the system. The system was built within the constraints of their knowledge. To effectively write code and work in the system, it couldn’t, by design, be built beyond your scope of understanding.

If I didn’t understand how the API worked, I’d rely on another engineer who did. I’d cover my area and they theirs. But, in the process of the work, we’d share knowledge and expand our individual mental models, deepening our understanding of the larger system.

So what happens when agents write all the code, blur the lines, and move so fast we can’t keep up with the changes?

We need new ways to preserve judgement.

Preserving judgment requires understanding components, relationships, and principles

I wrote down two words in my notebook:

“Isolation” + “Integration”

I don’t know why these words came up, but I was thinking about them. Isolation is how you understand the capabilities of an individual component. Integration is how you understand the relationships that make up a system.

Isolation reveals intrinsic properties.

Integration reveals emergent properties.

But that’s incomplete.

You need something else to govern the behaviors and interactions of the components within the system. You need principles.

The components explain capabilities.

The relationships explain interactions.

The principles govern behavior.

Collectively, they represent a model of the system you can visualize and reason with.

Preserving judgement while letting AI write the code comes from a deep understanding of each of these three factors. But you can’t get there when every engineer is isolated to the context of their agent (and their agent’s agents). AI agents evolve through cascading, where one agent’s style informs the next. When one agent starts writing Pull Requests a certain way, the others follow. Without human intervention, coherence drifts. Like the individual contributor stepping into the manager role, we need to step into a role where we take ownership of the model of the system. We need to understand what the components are, how they interact, and what principles guide their evolution.

We need a shared representation.

A living System Model makes systemic evolution explicit, shared, and intentional

Product Memory holds the feedback, signals, decisions, releases, and updates. It helps solve the problem of documenting historical context so humans and agents can collaborate and move at their best pace.

Equilio Coding provides a set of sequential and supporting skills to leverage AI to write code in a way that documents understanding and shares key changes with human drivers.

System Model is the missing piece required to surface a shared model of the system at the level of fidelity necessary to maintain understanding and preserve judgement.

There are three parts:

1. Components detail capabilities.
2. Relationships detail interactions.
3. Principles detail guidelines.

A System Model can describe two layers:

1. The Architecture Model describes the components, relationships, and principles of the codebase.
2. The Product Model describes the components, relationships, and principles of the product experience.

Together, they form a rich mental model of the current system. You can use this model to gain alignment with the engineering team, and to point your agents at it so they understand the key parts of the system. When something starts to drift, there’s a source of truth driving a conversation and resolution of the tension.

Components

Components are the individual parts of the system with their own distinct capabilities.

The Architecture Components are things like authentication, checkout, billing, or any of the larger architectural components in the system. They are not things like React or Node or PostgreSQL. Those are part of the tech stack, which are less relevant today.

Why?

Because agents can write in any language, so you should pick the best language for the system, not the one that fits the skills and preferences of your team. That is why, historically, those were chosen. If you have to write the code, you want it to be in a language you know and enjoy. You can argue that you still need to direct and review the writing of the code, but agents, with constraints, will write it independently as they get better.

The Product Components are the taxonomy I described in the Product Landscape—the Regions, Zones, and Context. I apply these to all Linear issues in the Work Registry, so they get the benefits of tracking their evolution in the work as it develops. This is a great starting point for defining the components.

But components are isolated, so we need to look at how they relate to one another. If we don’t, we’re like the blind men, mistaking the individual part for the whole.

Relationships

Knowing the capabilities of each component helps you understand the composition, but the relationships, dependencies, and connections are where you see how a system works.

Relationships matter most in systems.

Architecture Relationships show dependencies between the components, drawing lines into and out of each component so you can see how they rely on one another. This matters in the codebase because you can identify the obvious tension points and linchpins where you need to focus your energy.

Product Relationships are similar, but they reveal workflows. You can visualize how a customer would move through the features.

Knowing components and relationships heightens your awareness about how the system operates, but you won’t immediately improve your judgement. You need something more defined to guide decisions.

Principles

Principles help you identify what’s important in the System Model. You might already have principles to govern the codebase and the product experience. If you don’t, no worry.

To compile the principles for our System Model, I ran a prompt with Claude to review the codebase, the product, and all the memory. I had it try to infer principles from the current state of the system, which gave me a starting point to build from and iterate.

One example: The client can only pull data from the API. The API reaches out to the database and external services. A principle like this helps steer code changes because it’s easy to see when it’s not followed. That’s why the principles follow the components and relationships: they show you where principles matter so the components work well together as part of the larger system.

The System Model helps you diagnose problems, too

I created the System Model for our product and shared it with an engineer. They pointed out a few gaps I resolved, and now I’m working on integrating it with agents. I also took the generated documentation and had Claude build an interactive artifact. It even built a few scenarios that would show what components and relationships would be involved with specific changes. The source is there, and now you can visualize it in a way for anyone else on the team to reason with.

The System Model is also a tool for solving any system-level problem. Take any problem and think about it as a process:

1. Isolate the components. Start small with the individual component to understand its properties and functions. Do this for as many components as there are.
2. Find the relationships. Draw lines to and from all the components to see where and how they interact with one another.
3. Define the principles. Establish guiding principles you can use to make decisions to improve the components and relationships and evolve the system.

Try it. I bet you’ll see ways to solve the problem you missed before. We often end up like the blind men and the elephant, making assumptions based on limited information instead of thinking holistically.

If you want to build your own System Model, I created a repo with documentation, prompts, and examples on GitHub:

drewbarontini/system-model

System Reasoning is a philosophy for how to think about systems. System Models give you a tangible artifact to surface a mental model you and your AI agents can reason with. And the entire purpose is to preserve judgement so you can maintain coherence in the product, your codebase, and how your team works.