v2.0.0: Research-Backed Two-Tier Methodology

Summary

Restructures the .context method around measured LLM failure modes. Previous versions assumed richer context always helped. Research shows the opposite once you cross a small budget, and the methodology is now engineered around that constraint.

This is a major version bump because the default loading model has changed. Existing .context/ content is preserved, but how it gets into an AI conversation is different.

The Four Findings

Finding	Implication
Context length alone hurts performance (13-85% accuracy degradation as input grows, even when added content is relevant)	Keep always-loaded content small
Instruction budget is ~150-200 distinct rules before instruction-following degrades	Distribute rules across path-scoped files
Lost in the middle: LLM attention is U-shaped, mid-document content gets ignored	Short files only, critical rules at the top
Path-scoped rules sharply reduce per-turn rule-token usage because most rules are inactive for any given task	Default to .claude/rules/*.md rather than CLAUDE.md bloat

Full citations and discussion: .context/research.md.

What Changed

Tier 1 (Always Loaded)

• New .claude/rules/ directory with README and six path-scoped rule files (api, auth, database, ui, seo, testing). Each under 50 lines.
• CLAUDE.md slimmed to ~40 lines: a path-to-rule mapping table plus project-wide pointers.
• AGENTS.md (renamed from agents.md, uppercase to match the OpenAI convention) reshaped to mirror CLAUDE.md plus cross-tool wiring for Cursor, GitHub Copilot, Windsurf, and generic LLMs.
• .context/ai-rules.md and .context/glossary.md remain the project-wide always-loaded substrate.

Tier 2 (On Demand)

• All existing .context/ domain folders (architecture/, auth/, api/, database/, ui/, seo/) preserved.
• Operational files (anti-patterns.md, boundaries.md, debt.md, errors.md, performance.md, testing.md, etc.) preserved.
• Decisions and prompts preserved.
• Loading model changed: Tier 2 files are pulled in only when a task explicitly needs them, not by default.

Documentation

• .context/research.md: new, explains the four findings and how each shapes the methodology.
• .context/substrate.md: rewritten to introduce the Tier 1 / Tier 2 split explicitly.
• .context/decisions/004-research-backed-pivot.md: new ADR capturing rationale, consequences, and migration steps.
• README.md: reframed around the research; new structure diagram, updated minimal starter (4 files, 65 min), updated FAQ.

Breaking Changes

• agents.md is now AGENTS.md. Projects that reference it with lowercase will need a path fix (silent failure on case-insensitive filesystems, visible on Linux/CI).
• The "more files = better" framing is retired. File count is no longer a methodology target.
• CLAUDE.md and AGENTS.md shapes have changed. Existing users of this template should follow the migration steps in ADR 004.

Migration (for projects using v1)

1. Slim CLAUDE.md to the path-scoped-table shape. See this repo's CLAUDE.md for the template.
2. Extract path-specific rules from any monolithic ai-rules.md into .claude/rules/<domain>.md files.
3. Leave .context/ domain folders in place. They are Tier 2 now, loaded on demand.
4. Update tool-specific configs (.cursor/rules/, .github/copilot-instructions.md, .windsurfrules) to reference the new rule files.
5. Rename agents.md to AGENTS.md if you standardize on the uppercase convention.

Full migration walkthrough: ADR 004.

Research References

• Context Length Alone Hurts LLM Performance
• How Many Instructions Can LLMs Follow at Once?
• Lost in the Middle

Full Changelog: 1.0.0...v2.0.0

1.0.0

Initial release of .context method, I'll be using semver going forward for any changes.