The .context method

TL;DR: Give AI tools a brain dump of your project so they stop guessing. A .context/ folder with structured docs = AI that actually understands your codebase.

A complete "Documentation as Code as Context" template implementing the Substrate Methodology. Transform any software project into a self-documenting, AI-optimized codebase with modular, Git-native documentation that serves as a living knowledge base.

What is the Substrate Methodology?

The Substrate Methodology addresses the problem of outdated documentation and AI hallucinations by creating a structured, domain-organized documentation system in a .context/ directory. This approach:

• Reduces documentation drift by keeping docs in Git alongside code
• Provides context that reduces AI hallucinations through structured, project-specific information
• Supports faster onboarding with comprehensive domain knowledge
• Captures decision history for future reference
• Helps teams scale with consistent, documented patterns

Quick Start

1. Clone and customize:

   git clone https://github.com/andrefigueira/.context.git your-project
   cd your-project
   rm -rf .git && git init
   

2. Customize the template:

   • Replace [Your Project Name] placeholders
   • Update code examples for your stack
   • Modify domains in .context/ to match your architecture

3. Start documenting:

   # Edit the entry point
   vim .context/substrate.md
   
   # Add your first domain documentation
   vim .context/architecture/overview.md
   

4. Generate your substrate with AI: Use the comprehensive AI prompt below to create domain-specific documentation for your project. See AI-Assisted Substrate Generation section for the complete prompt.

Why This Matters

Modern software development faces a documentation crisis:

• Most developers work with outdated or incomplete docs
• AI tools hallucinate when missing context
• Knowledge silos slow team velocity
• Onboarding takes weeks instead of days

The Substrate Methodology transforms documentation from a burden into a force multiplier, creating a comprehensive knowledge base that grows with your codebase.

Before & After

Without .context:

Prompt: "Add a password reset endpoint"

AI output: Generic implementation, wrong auth pattern,
missing your error codes, doesn't match your architecture.
You spend 30 min fixing it.

With .context:

Prompt: "Add a password reset endpoint"

AI output: Uses your JWT pattern, your error codes (AUTH_*),
your service/repository layers, your validation approach.
Ready to use.

The difference is context. AI tools are capable. They just don't know your project.

Minimal Starter (5 Files)

Don't have time for 47 files? Start with these 5:

| File | Purpose | Time | |------|---------|------| | substrate.md | Entry point, project overview | 15 min | | ai-rules.md | Hard constraints (naming, patterns) | 20 min | | anti-patterns.md | What NOT to do | 15 min | | architecture/overview.md | System design, layers | 30 min | | glossary.md | Your terminology | 10 min |

That's 90 minutes to massively improve AI output. Add more files as needed.

Adding to Existing Projects

Already have a codebase? Here's how to retrofit:

1. Create the folder:

   mkdir -p .context/architecture .context/auth .context/api .context/database
   

2. Generate initial substrate with AI:

   Analyze this codebase and generate .context/ documentation following
   the structure at https://github.com/andrefigueira/.context
   
   Focus on:
   - Current architecture and patterns
   - Authentication approach
   - API conventions
   - Database schema
   - Naming conventions
   - Known technical debt
   

3. Review and refine - AI gets you 80%, you refine the rest

4. Validate regularly - Use the Hot Tip prompt to keep it accurate

Add the Badge

Using .context in your project? Add the badge:

[![.context](https://img.shields.io/badge/.context-method-blue)](https://github.com/andrefigueira/.context)

How the .context Method Works with AI Tools

The .context/ folder is the core of this methodology. It contains your structured documentation. But different AI tools need different ways to discover and use this context.

The Entry Point Problem

AI tools need to know your .context/ folder exists and how to use it. This is solved differently depending on your tool:

| AI Tool | Entry Point | How It Works | |---------|-------------|--------------| | Claude Code (Anthropic CLI) | CLAUDE.md | Auto-loaded at session start. Claude Code reads this file automatically and follows its instructions to reference .context/ files. | | Other AI tools (ChatGPT, Cursor, Copilot, generic Claude) | agents.md | Manual inclusion. You copy relevant .context/ files into your prompts following the patterns in agents.md. |

Why Two Files?

CLAUDE.md is a Claude Code feature. When you start a Claude Code session, it automatically reads CLAUDE.md from your project root and treats it as persistent instructions. This means Claude Code will automatically know to check .context/ files before generating code.

agents.md exists for AI tools that don't have this auto-discovery feature. It documents how to manually feed context into your prompts for consistent results.

The Relationship

┌─────────────────────────────────────────────────────┐
│                  .context/ folder                    │
│         (Your structured documentation)              │
│                                                      │
│  substrate.md, architecture/, auth/, api/, etc.     │
└─────────────────────────────────────────────────────┘
                         ▲
                         │
         ┌───────────────┴───────────────┐
         │                               │
    ┌────┴────┐                    ┌─────┴─────┐
    │CLAUDE.md│                    │ agents.md │
    │         │                    │           │
    │ Claude  │                    │  Other    │
    │  Code   │                    │ AI Tools  │
    │(auto)   │                    │ (manual)  │
    └─────────┘                    └───────────┘

Both files point to the same .context/ documentation. They're just different bridges for different tools.

FAQ

Why do I need .context/ if I already have CLAUDE.md or agents.md?

CLAUDE.md and agents.md are entry points, not the knowledge itself. They're like the table of contents in a book. The .context/ folder is the actual book.

Without .context/, your CLAUDE.md becomes a flat list of instructions with no depth. The AI reads "use JWT authentication" but has no reference for your JWT implementation, your token lifetimes, your refresh strategy, your error codes.

The power is in the structured knowledge that lives in .context/. The entry point files just tell AI tools where to find it.

What is "crystallized knowledge" and why does it matter?

When your team discusses architecture, debates patterns, and makes decisions, that knowledge exists as fluid conversation. It lives in Slack threads, meeting notes, pull request comments, and people's heads.

Crystallized knowledge is that same information solidified into permanent, structured reference material. The .context/ folder captures decisions after they've been made, patterns after they've been validated, and constraints after they've been learned the hard way.

This matters because:

• Fluid knowledge disappears when people leave or forget
• AI tools can't read Slack history or attend your meetings
• New team members can't absorb years of tribal knowledge
• Your future self won't remember why that weird pattern exists

Crystallizing knowledge into .context/ makes it permanent, searchable, and AI-consumable.

Isn't this just markdown files? What makes it different?

The files are markdown. The value is in the structure and interconnection.

Consider the difference:

• Flat docs: A single README with everything in one place
• Wiki-style: Separate pages with no clear relationships
• Substrate: Domain-organized, cross-referenced, with explicit hierarchies

The .context/ structure encodes relationships:

• auth/security.md links to architecture/patterns.md for error handling
• api/endpoints.md references database/models.md for validation rules
• decisions/001-jwt.md explains why auth/overview.md uses that approach

AI tools follow these connections. When you ask about authentication, the AI doesn't just read one file. It traverses related context across domains. The structure is the intelligence.

How is this different from just good comments in code?

Comments explain what code does. .context/ explains:

• Why the code exists (decision rationale)
• What else relates to it (cross-domain connections)
• What not to do (anti-patterns and boundaries)
• How it evolved (decision history)

Code comments are local. Substrate context is global. When AI generates new code, it needs to understand the whole system, not just the function it's modifying.

Does the AI actually use all these files?

Not all at once. The methodology works through selective loading:

1. Entry point (CLAUDE.md / agents.md) tells AI where context lives
2. Task determines scope: Auth wor