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.

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.”

Making of Agor Security