context-builder

Context Builder

Overview

Create a shared vocabulary between you and the agent. Once built, the agent speaks YOUR language — concise, precise, domain-native.

The Problem This Solves

Without shared context:

• Agent uses 20 words where your domain has 1 term
• Variables named generically ("data", "handler", "service") instead of domain terms
• Every session starts from scratch explaining the same concepts
• Conversations are verbose because the agent doesn't know your jargon

With CONTEXT.md:

• Agent speaks your domain language natively
• "the materialization cascade" replaces "when a lesson inside a section of a course is made real"
• Code uses domain terms for variables, functions, modules
• Sessions start with shared understanding already loaded

Process

1. Interview (grill the user)

Ask these questions ONE AT A TIME:

1. "What is this project? One sentence."
2. "What are the 3-5 most important CONCEPTS in this domain?"
3. For each concept: "Define it in one sentence. What terms should I AVOID using for this?"
4. "Are there relationships between these concepts? (X contains many Y, Y belongs to one X)"
5. "Any terms that were previously confusing or ambiguous? What did you resolve them to?"
6. "What actions/verbs are specific to this domain?" (e.g., "materialize", "triage", "hydrate")

2. Generate CONTEXT.md

Write to the project root:

# [Project Name]

[One-sentence description]

## Language

**[Term 1]**:
[Definition in one sentence]
_Avoid_: [terms NOT to use for this concept]

**[Term 2]**:
[Definition]
_Avoid_: [alternatives to avoid]

## Relationships

- A **[Term 1]** contains many **[Term 2]**s
- A **[Term 2]** belongs to one **[Term 1]**

## Flagged Ambiguities

- "[confusing term]" was previously used for both X and Y — resolved: [how it's now used]

3. Persistence

Once CONTEXT.md exists:

• Agent reads it at session start
• Uses defined terms in ALL communication
• Names variables/functions using the vocabulary
• Flags when new undefined terms appear: "Should I add '[term]' to CONTEXT.md?"

4. Evolution

CONTEXT.md grows over time:

• New concepts emerge during development → add them
• Ambiguities surface → resolve and document
• Terms become obsolete → remove them
• The vocabulary becomes MORE precise with each session

Verification

After generating CONTEXT.md:

• Every domain concept has exactly ONE term (no synonyms in use)

Concrete Example

For an e-commerce project, a good CONTEXT.md entry:

**Cart**:
A temporary collection of products a customer intends to purchase. Exists per-session, persists across page navigation, cleared on checkout completion.
_Avoid_: basket, bag, order (an Order only exists AFTER checkout)

**SKU**:
The unique identifier for a specific product variant (size + color). NOT the product itself — one Product has many SKUs.
_Avoid_: product ID, item number (SKU is variant-level, product ID is parent-level)

This level of precision prevents: wrong variable names (orderId when it should be cartId), confused queries (joining on product_id when you need sku_id), and verbose explanations ("the thing where users put stuff before buying").

• Each term has an "Avoid" list (prevents drift back to vague language)
• Relationships are explicit (not just a flat list)
• The agent can explain the project using ONLY these terms

Common Mistakes

• Adding implementation details to CONTEXT.md (it's a GLOSSARY, not a spec)
• Defining too many terms at once (start with 5-8 core terms, grow organically)
• Skipping the "Avoid" list (without it, the agent drifts back to generic language)
• Treating it as write-once (update when new domain concepts emerge)

Why This Works

Cognitive science: shared mental models reduce communication overhead exponentially. In software, Eric Evans called this "Ubiquitous Language" (Domain-Driven Design). mattpocock proved it works for AI agents with 75% token reduction in practice.

The CONTEXT.md IS the Ubiquitous Language for your human-agent collaboration.