Spatial Context Theory
The Human-AI
Collaboration Layer
Where humans provide intent and AI provides speed. A shared visual language for building software together.
High-Level Architecture
See your entire system at a glance. View Modules link to detail views.
The Problem
You're using Claude Code, Cursor, or Windsurf. The AI is fast. But something's wrong.
On small tasks, it's brilliant. On complex codebases, it starts guessing. It hallucinates files that don't exist. It misses dependencies. It suggests changes that break things three services away.
The model isn't broken. The context is.
You're feeding it the Forest when it needs the Leaf.
This is the Complexity Wall - the point where AI error rates climb faster than the value AI provides. Every team hits it eventually. Most blame the model. The model isn't the problem.
The Solution: Views
Views give AI precision context instead of brute force.
Instead of feeding the AI your entire codebase, you show it exactly what's relevant for this task.
The Hierarchy
High-Level View
Your architecture at the repo level. 18 microservices = 18 modules. The shape of the system.
Module View
Drill into one service. Its internal structure, components, files.
Sub Views
Different perspectives - functional flows, feature groupings, component relationships.
The Lasso
Select exactly the components relevant to this feature. That selection becomes the context.
Precision scope. The Leaf, not the Forest.
Who This Is For
Developers using AI coding tools who've noticed accuracy drops as projects grow.
Engineering Leaders whose AI pilots worked in demos but struggle in production codebases.
Architects managing microservices, monorepos, or legacy systems where tribal knowledge matters.
If your codebase has grown past the point where "just feed it everything" works, this research is for you.
The Theory
Spatial Context Theory addresses four problems that emerge when AI works with insufficient or noisy context:
1. The Black Box Problem
When a human prompts an AI, neither side has visibility into what the other truly understands. Visual structure solves this by creating mutual visibility - the human and the AI see the same map.
2. The Guessing Problem
When context is incomplete, AI systems infer. Inference at scale means hallucination at scale. Explicit pointers replace guessing with precision.
3. The Context Problem
Current approaches feed AI everything and hope the model figures out what matters. Views provide precision scope - the "Leaf" rather than the "Forest."
4. The Scaling Problem
As applications grow, brute-force context breaks down. Spatial structure scales because it's hierarchical - complexity is managed through layers of Views.
How It Works
Connect via MCP
Views connects to Claude Code, Cursor, and Windsurf via MCP. The AI can read your Views, and update them as it builds.
The 2-Minute Handshake
Humans provide Intent. AI provides Speed.
Select
Lasso the relevant components from a View. Seconds, not minutes. Create Feature.
Align
Chat with the AI for two minutes. The UX nuance, the edge cases, the human judgment.
Build
The AI executes and creates the Feature Doc from the View, the chat, and the State.
The Self-Healing Loop
As the AI builds, it enriches the context. Updates metadata. Refreshes pointers. The map heals itself. The more you build, the stronger the context becomes.
The Economics
By passing the "Leaf" instead of the "Forest", teams see 60-80% reduction in token consumption while improving accuracy.
| Metric | Brute Force | Spatial Context |
|---|---|---|
| Prompt Density | 80% Noise | 100% Signal |
| Token Consumption | Linear growth with repo | Fixed to feature scope |
| Documentation Debt | Accumulates indefinitely | Eliminated - docs are generated |
About
I've spent 30 years building systems that scale - from an ISP I grew in a garage to £6M ARR, to leading 56 engineers as VP Engineering at Napster.
While the world sees rows of text, I see Spatial Structures - 3D maps of intent. I kept this private for years. Now I realise it's my unfair advantage.
I'm releasing this research as Open Source because progress happens faster when knowledge is shared.
Open Source
The theory and research are open source. MIT License.
What's Open Source
- • Spatial Context Theory paper
- • The concepts: Views, Modules, Connections, File Pointers
- • Research on AI context management
Solve Your Documentation Problem
If your CEO asked to see your architecture docs right now, would you have them?
Most teams don't. Documentation is always out of date, scattered across wikis, or exists only in people's heads.
What problems would you like to solve?
- • Legacy systems nobody understands anymore
- • Onboarding takes months instead of days
- • AI coding tools that hallucinate in your codebase
- • Architecture knowledge trapped in senior engineers' heads
- • Compliance audits that require documentation you don't have
I consult on Spatial Views to solve these problems. We can plug into your existing workflow, connect AI to legacy systems, or build documentation from scratch.
→ Let's TalkLet's Talk
30-minute call. You tell me about your documentation challenges, I'll show you how Spatial Views can help.
Or email directly: tony@spatialthinking.ai
Spatial Context Theory - is all you need.