Shape

Context

Every artifact (a function, a module, a system, a conversation with an AI agent) has a structural form. Shape is that form as perceived at a particular level of observation. It operates at the architectural scale, though the concept applies at every level. When someone says “this codebase has a clean shape” or “the shape of this API feels wrong,” they’re talking about the structural outline rather than the details inside.

Shape is related to, but distinct from, architecture. Architecture is the intentional design of a system’s shape. Shape itself is descriptive: it is what you see when you step back and squint.

Problem

How do you talk about the overall form of something (its symmetry, its balance, its fit) without getting lost in implementation details?

Forces

• Detail is necessary for building, but it obscures the big picture.
• People (and agents) need to orient themselves quickly before diving in.
• The same system can have different shapes depending on the vantage point (runtime behavior, file layout, dependency graph, data flow).
• A shape can be accidental (it just grew that way) or intentional (someone designed it).

Solution

Cultivate the habit of seeing and naming the shape of things. Before modifying a system, ask: what is its current shape? Is it a pipeline (data flows one direction through stages)? A hub-and-spoke (one central piece connects many peripherals)? A layered cake (each layer depends only on the one below)? A tangled web (everything connects to everything)?

Naming the shape gives you vocabulary for structural discussions. It also reveals mismatches: if you intend a layered shape but find that your “presentation” layer reaches directly into the database, the shape has drifted from the design.

In agentic coding, shape awareness helps you give better instructions. Telling an agent “this is a pipeline — add a new stage between parsing and validation” is far more effective than saying “add some code somewhere to do X.” The agent can reason about where a new piece fits if it understands the overall form.

How It Plays Out

A developer joins a new project and spends thirty minutes reading the directory structure and top-level imports. She sketches a rough diagram: three services communicating via a message queue, each with its own database. That sketch — the shape — lets her reason about where a new feature belongs before reading a single function body.

An AI agent is asked to refactor a monolithic script into modules. The agent first analyzes the script’s shape: it identifies three clusters of functions that form natural groups. By seeing the shape, the agent can propose a decomposition that respects the existing structure rather than imposing an arbitrary one.

Consequences

Thinking in terms of shape helps teams communicate about structure without drowning in detail. It makes architectural drift visible: you can compare the intended shape to the actual shape. It also provides a common vocabulary for guiding AI agents, like “preserve the pipeline shape” or “this should be a tree, not a graph.”

The risk is that shape is inherently a simplification. Two systems with the same high-level shape can have very different internal qualities. Shape is a starting point for understanding, not a substitute.

Related Patterns

• Refined by: Architecture — architecture is the deliberate design of shape at the system level.
• Uses: Abstraction — seeing shape requires abstracting away detail.
• Enables: Decomposition — understanding the shape helps you decide where to split.
• Related to: Cohesion, Coupling — these measure the quality of a shape.