Skip to content

CONCEPT Cited by 1 source

Compass, not encyclopedia

Definition

"Compass, not encyclopedia" is the design principle Meta names for per-module AI-agent context files: each file is 25-35 lines / ~1,000 tokens — short enough that it can be loaded into an agent's context without crowding out tool outputs — with four mandated sections oriented around navigation + failure-avoidance, not exhaustive description.

"No fluff, every line earns its place." (Source: sources/2026-04-06-meta-how-meta-used-ai-to-map-tribal-knowledge-in-large-scale-data-pipelines.)

The four mandated sections

Section Purpose Why not "encyclopedia"
Quick Commands Copy-paste ops the agent runs most Not: prose describing the CLI surface area
Key Files "The 3-5 files you actually need" Not: a table of every file in the module
Non-Obvious Patterns Tribal knowledge + gotchas Not: a narrative of the module's design history
See Also Cross-references to related modules + concepts Not: full dependency graphs inline

Why the shape matters

The principle is a token-budget discipline applied at the per-file level, composing with concepts/context-engineering at the per-turn level:

  • ~1,000 tokens per file means loading 10 files still fits inside a generous headroom for tool outputs + conversation history.
  • All 59 files together consume less than 0.1% of a modern model's context window (Meta's disclosure) — the entire knowledge layer fits inside the headroom of a single tool call.
  • Four sections with explicit purposes means agents can section-hop rather than read linearly — "looking for the gotcha" is a direct jump.
  • Short files mean fast maintenance — when the underlying code changes, 30 lines are easier to re-validate than 300.

Contrast with encyclopedia-style docs

Encyclopedic documentation (the academic-research comparison point: Django / matplotlib auto-generated context files) fails because:

  • Context rot — long encyclopedic blobs dilute the signal the agent needs for this specific task.
  • Pretraining overlap — on well-known OSS, the model already knows the encyclopedia; injecting it adds noise.
  • Maintenance unfeasibility — 300-line files can't stay fresh at Meta's refactor pace.

2025 academic research found AI- generated context files decreased agent success rates on Django / matplotlib. Meta's response: "Files are concise (~1,000 tokens, not encyclopedic summaries), opt-in (loaded only when relevant, not always-on), and quality-gated."

Applied more broadly

The principle generalises beyond code-navigation context files:

  • LLM system prompts — the same discipline argues for task- focused 25-35-line system prompts over exhaustive role/persona pages.
  • Runbooks for human + AI incident response — the "what specifically to do when alert X fires" shape beats the "full history of the service" shape.
  • Migration guides — compass-shaped is "here are the 5 files you change and the 3 invariants you must not break"; encyclopedia- shaped is a 300-line narrative.

Seen in

Last updated · 319 distilled / 1,201 read