Context Engineering the @mistercrunch Way

AGENTS.md and CLAUDE.md made it easy to dump everything in one place—and just as easy to blow up your context window. Great for a quick start; brittle at scale. On bigger projects with many engineers (and even more agents), you need structure that doesn’t fight velocity.

The pattern I use: keep context bite‑sized, self‑referential, and treat it like code. Simple, durable, and it scales with humans and AIs.

The Problem With Giant Context Dumps

One mega‑file is easy to start, impossible to maintain.
Agents overfit on stale guidance or miss key constraints.
Humans can’t find the right nugget without reading everything.
Diffing, reviewing, and “what changed?” become guesswork.

The Pattern

context/ folder: a small, linked graph of markdown “context nuggets”.
Bite‑sized files: one concept per file; link, don’t repeat.
Self‑referencing: index at context/README.md; cross‑link liberally.
Treat docs like code: PRs, reviews, clear types of docs, graduation paths.
CLAUDE.md/AGENTS.md as a map: glossary + pointers, not a dump.

Recommended Folder Structure

The only hard rule: context nuggets are md files under context/. The exact shape can vary by repo. A structure that worked well for me:

context/
├── README.md              # index, how to fetch/use context
├── concepts/              # stable, canonical ideas & primitives
├── guidelines/            # standards and “how we build”
├── proposals/             # design docs / RFCs under review
├── projects/              # per‑initiative nuggets: goals, constraints, links
├── ongoing-refactors/     # living docs for migrations/renames
├── playbooks/             # common tasks (“add a service”, “cut a release”)
└── explorations/          # rough notes that may graduate

Graduation path: explorations → proposals → concepts/guidelines.
Deprecation: keep links, mark clearly, point to the replacement.
CLAUDE.md/AGENTS.md: glossary + links into context/, nothing more.

Superset’s SIP has additional recommendations; the core idea remains the same: small md nuggets in a navigable folder tree, with a clear index and graduation.

“Compiled” Docs And Scripts

Keep scripts that regenerate sections or roll‑ups deterministically.
Commit both sources and the “compiled” outputs agents will read.
Overwrite intentionally; diff for drift; review like code.

This makes “docs as inputs” repeatable and auditable.

How It Played Out In Agor

Started with context/explorations/*.md for fast sketching.
As ideas hardened, rewrote and moved them to context/concepts/ or context/guidelines/.
CLAUDE.md is now a symlink to AGENTS.md — a glossary that routes agents to the right nuggets on demand.
Agents fetch what they need per task instead of slurping everything.

Did this alone enable shipping most of Agor in under a month (after hours)? Not alone — but it removed a major bottleneck for both me and the agents.

Attaching Context To Your Development Workflow

Having organized context nuggets is step one. Using them effectively is where the real leverage comes from. Here’s the workflow I’ve iterated into:

1. Plan Mode: Design Before Code

Start every significant feature in plan mode — no code yet. The goal is a design document.

Describe the feature clearly.
Pull in the relevant context nuggets (architecture.md, models.md, the specific guidelines that apply).
Let the agent synthesize a proposal: scope, approach, edge cases, open questions.

Iterate until the design feels solid. This is cheap — just markdown — and catches misunderstandings before they become refactoring.

2. Clear The Long Tail

Before implementation, ask the agent: “What’s unclear? What assumptions are you making?”

This surfaces the long tail of questions that would otherwise become bugs or rework. Clarify now; pay less later.

3. Break It Down (Or Don’t)

Here’s the hard-won intuition:

One agent can probably do it all — frontend, backend, tests, docs — sequentially. Models are getting better at long-duration, heavy-context tasks.

But specialist agents with just the right context often do better. A backend agent with backend-guidelines.md and architecture.md. A frontend agent with design.md and frontend-guidelines.md. Each with a fresh context window, focused on their slice.

When to break down:

Context can be cleanly segmented (backend vs. frontend vs. tests).
The task is complex enough that a single agent starts losing coherence.
You want parallelism — multiple agents working simultaneously.

When to keep it unified:

The feature is small enough to one-shot.
Heavy cross-cutting concerns (a change that touches everything).
Orchestration overhead isn’t worth the gains.

My default: Try the one-shot first. Save the design doc, create a worktree, let one agent run. If the results disappoint, fall back to breaking it down. Don’t over-engineer your agent orchestration before you know you need it.

4. Spawn With Fresh Context

When you do break down, spawn subsessions with:

The design document (your shared contract).
Only the context nuggets relevant to that agent’s slice.
A clear, bounded task description.

Fresh context windows mean less noise and more focus. The design doc keeps everyone aligned without each agent needing to understand the whole system.

The Meta-Pattern

This is context engineering applied to workflow, not just files:

Plan phase: Load broad context, produce a focused artifact (the design doc).
Implementation phase: Load narrow context, execute against the artifact.
Coordination: The design doc is the shared state; context nuggets are the specialized knowledge.

The same principles apply: bite-sized, task-scoped, linked not duplicated.

For Humans And AIs

Humans:

Faster onboarding: start at the index, follow links, get unstuck.
Clear contracts: canonical types/models live in one place.
Less drift: smaller files, easier reviews, shared vocabulary.

Agents:

Smaller prompts with higher‑quality grounding.
Task‑scoped fetch instead of giant context stuffing.
Deterministic links to “the right doc” for a given operation.

Agor Roadmap: Context Tools

Planned (roadmap, not shipped):

list_context_files: discover and navigate the context graph.
attach_context_used_to_session: persist what was read for auditability.
alter_context_file: propose changes; humans review and merge.

A simple glossary in CLAUDE.md works today; these tools add just enough structure to scale without ceremony.

FAQs I Keep Hitting

Isn’t this duplicative of README/user docs? Sometimes. That’s fine. Docs have audiences; context is for coding (human + agent).
Won’t links rot? Less than you think with small files and reviews. Rot shows up in prompts quickly — fix at the source.
Where do types belong? In code. Docs link to canonical types; they never redefine them.

Try It In Your Repo

Add context/ with an index and a few small nuggets.
Reduce CLAUDE.md/AGENTS.md to a glossary + links.
Keep explorations rough; graduate when stable.
Review docs like code. Small PRs win.

If you use Agor, you’ll see this structure reflected across boards and the agent workflows. It keeps everyone — humans and AIs — on the same page without inflating prompts.

Superset context discussion: https://github.com/apache/superset/issues/35820
Agor announcement: /blog/announcement
Working notes on building Agor: /blog/making-of-agor

— “Context that breathes” beats “context that bloats.”

Agor Cloud Private Beta The Orchestration Layers