---
title: "The Entity"
slug: the-entity
date: "February 2026"
read_time: "5 min read"
word_count: 1520
excerpt: "Every tool needs a unit of analysis. For text editors it's characters. For git it's lines. For compilers it's tokens. We think the right unit for code intelligence is the entity."
filed_under: ["Code intelligence","Architecture","Primitives"]
---

# The Entity

Every tool that works with code has to choose a unit of analysis. Text editors work in characters. Git works in lines. Compilers work in tokens and AST nodes. Each of these is the right choice for what that tool does. But when you want to do higher-level things with code, things like understanding what changed, figuring out what depends on what, merging parallel edits, or deciding what to review, you need a different unit.

An entity is a function, a class, or a method. That's it. Not a file, not a line, not an AST node, not a module. A function. The reason this particular granularity is the right one isn't arbitrary, and it's worth understanding why, because a lot of the power of entity-level tooling comes from properties that only hold at this specific level of abstraction.

**DEFINITION 1.1.** An entity is the smallest unit of code with a name, defined inputs, defined outputs, and an identity that persists across versions.

Start by thinking about what makes a good unit of analysis for code. You want something that is self-contained: it has a clear boundary, a name, defined inputs, and defined outputs. You want something that is independently meaningful: you can understand what it does without reading everything around it. You want something that maps to how people actually think about code: when a developer says "I changed the payment logic," they're pointing at something, and you want your unit to be that thing.

> The entity is the *Goldilocks* unit: not too big, not too small, just right for ownership, merging, and independent reasoning.

Functions satisfy all of these properties. A function has a name, a signature, a body. You can read a function and understand what it does. You can talk about a function in conversation and your colleague knows exactly what you mean. Functions call other functions, forming a dependency graph that tells you how changes propagate through a codebase. Classes satisfy these properties too, as do methods within classes, which are essentially functions with an implicit receiver.

Now consider the alternatives and why they don't work as well. Files are too coarse. A single file might contain ten unrelated functions, and if you treat the file as your unit, you lose the ability to distinguish between them. Two developers editing different functions in the same file look like they're in conflict, even though they're working on completely independent things.

Lines are too fine. A single line of code has no independent meaning. It's a fragment of a larger thought. If you diff at the line level, you can see that something changed, but you can't tell what it means without reading the surrounding context. Lines also don't have dependencies.

For agents specifically, the entity is the right unit because it matches the granularity at which agents naturally work. When an agent modifies code, it doesn't think in lines. It thinks: I need to change this function to handle the new edge case, and I need to update that function to call it with the new parameter. Those are entity-level operations.

There's also a coordination argument. When multiple agents work on the same codebase, they need a way to avoid stepping on each other. The entity is the natural unit of coordination because it's the smallest unit that can be independently owned. An agent can claim a function, work on it, and merge its changes with a guarantee that no other agent's work will conflict, as long as no other agent claimed the same function.