Part of Mechanisms of Vibe Coding

Mechanism: Anchor Files

One-sentence definition

Anchor files are the small set of documents or source files you almost always attach — README, types, architecture note, or canonical example — so the agent orients to your project instead of generic patterns.

The problem

The agent invents a config system, uses npm instead of pnpm, puts handlers in the wrong folder, and names types differently from the rest of the repo. It never saw how this project actually works — only the one file you @ mentioned.

Without anchors, every session re-bootstraps project knowledge from weights and luck. Anchors are cheap context that prevent expensive wrong assumptions.

Symptoms:

• New dependencies or tools inconsistent with the repo
• File paths and naming unlike neighboring modules
• Agent “fixes” conventions documented in README
• Same orientation mistakes every new chat

How it works

Pick 1–3 anchors per repo type:

• App / API — README.md, shared types or schema, one exemplar route
• Library — README.md, main export module, test fixture
• Monorepo — package README + root AGENTS.md or architecture snippet

Anchors are not the whole codebase. They answer:

• How do we run tests?
• Where do routes / components live?
• What patterns are mandatory?

  Every session start
       │
       ▼
  Goal + constraints + anchors (fixed set)
       │
       ▼
  Task-specific files ([progressive disclosure](/mechanism-progressive-disclosure/))

Standing anchors can live in rules (“always read README before edits”).

When to use it

• Every non-trivial session on a repo you did not write today
• Onboarding agents (and humans) to team conventions
• Before @codebase or wide search — anchors first, search second
• Multi-package repos where defaults are ambiguous

When not to use it

• Anchors that are huge (1000-line README) — trim or link to sections
• Stale anchors worse than none — update when stack changes
• Ten “anchors” — that is a kitchen-sink context budget, not anchoring

Failure modes

Wrong anchor — CONTRIBUTING.md from another project copied in. Fix: Curate anchors; date them.

Anchor overload — Five docs every time. Fix: Cap at 2–3; rotate task-specific fourth file.

Ignored anchor — Agent still violates README. Fix: Quote the relevant anchor line in the goal block.

No exemplar — Types without a real module example. Fix: One canonical file that “looks like we want.”

Secret leakage — Anchors with credentials. Fix: Sanitize; use env docs without values.

Minimal example

Context: Health API sessions in a Node service.

Standing anchors:

• README.md (test command, package manager)
• src/types/health.ts or shared API types
• src/routes/health.ts as exemplar route (even when editing bootstrap)

First message always @ these plus task files. Agent sees pnpm, test script, response type patterns before editing bootstrap.

Done when: Agent’s first pass uses project test command and type names without you correcting basics.

Tool instances (optional deep-dive)

Portable idea above; this section is tool-specific. Date: June 2026.

Cursor

• .cursor/rules: “Read README.md for commands and conventions.”
• Notepads / docs — pinned project orientation for repeated tasks.
• @README + @types in template first message for the team.
• Do not duplicate entire README in rules — point to anchor file.

Other tools

CLAUDE.md, AGENTS.md, Aider CONVENTIONS.md — anchor files by convention.

Related mechanisms

• Context budget — anchors are the first budget spend
• Progressive disclosure — anchors before optional files
• Rules / skills as memory — rules can mandate anchors

Try it yourself

Exercise: List 2–3 anchor files for your main repo. For each, one sentence: what mistake this prevents.

You need: One repo; five minutes

Done when: You would @ the same files tomorrow without re-deciding.