groundrules
groundrules lays the documentation backbone of a software project — and keeps it alive. A Claude Code plugin that interviews you, captures the project's intent, and generates a tailored, opinionated doc structure (vision, decisions, learnings, architecture…), then gives you the skills to maintain it as the project evolves.
Interview → tailored project structure → git init → first commit → optional remote.
Why
Coding agents rarely fail for lack of information — they fail for lack of the right information, structured and at hand. Two forces make that hard, and groundrules is built to answer both:
- More context isn't better — it's measured. Research on context rot (Chroma, 2025) found every frontier model tested — Claude included — degrades as the input grows; the classic lost in the middle effect drops accuracy 30%+ for anything buried mid-window. Anthropic's own guidance agrees: keep
CLAUDE.md under 200 lines, because "larger files produce lower adherence." Stuffing everything into context actively hurts.
- Knowledge evaporates. Decisions, conventions, and hard-won lessons end up in chat logs and an agent's volatile memory — gone by the next session, invisible to the next contributor.
groundrules' answer is a method, not just a folder of templates: write everything down on disk, load almost none of it. It generates a small always-loaded index (CLAUDE.md) that points to exhaustive docs read on demand, an ADR trail for the why, a rule-format learnings journal, and the discipline that the repo is the only memory. Exhaustive storage, minimal loading — the agent gets precisely what each task needs and nothing it doesn't.
What it buys you:
- Sharper agents — a small, current index plus on-demand reads keeps attention undiluted and adherence high, instead of a bloated always-on file.
- Knowledge that survives — decisions, conventions and lessons live in the repo, available to the next session, the next contributor, and any agent — not trapped in one chat.
- Lower token cost — exhaustive on disk, minimal in context: you don't pay to carry the whole project every turn.
- No lock-in — it's plain markdown; the structure stays readable and useful even without the plugin.
- Docs that don't rot — living-docs discipline, checkpoint capture, and
/groundrules:slim keep the backbone current and under budget over time.
The full reasoning and token economics: docs/CONTEXT-ECONOMY.md (ADR 0021).
Built for the age of loops
The way people drive coding agents is shifting from prompts to loops: instead of typing each prompt, you run a loop that restarts the agent from a fresh context every iteration and lets the repo — not the model — carry the memory. Claude Code's creator puts it plainly: "I don't prompt Claude anymore… my job is to write loops." The technique's slogan is blunter still: the model forgets, the repo remembers.
That is groundrules' thesis, arrived at independently — and the same context-rot research underwrites both: a short, fresh context each turn isn't a compromise, it's the goal. A loop only survives its amnesiac restarts on durable, on-disk state — a vision of what to build, a plan checked off run after run, lessons so it stops repeating mistakes, decisions for the why, and git for what's done. That state is exactly what groundrules generates. It makes a repo loop-ready: the structure a loop re-reads at the start of every iteration.
And it answers the paradigm's sharpest risk. Loops ship code fast, but they accrue comprehension debt — code that exists and works, yet no human ever read. groundrules' ADR trail, learnings journal, and the why it preserves are the antidote: loops write the code fast; groundrules keeps the understanding of the code.
