Stop manually listing context files in every prompt. A simple slash command lets your AI intelligently load relevant AGENTS.md files and DDRs based on what you're working on. The AI figures out what it needs to read.
I've been working with AI coding assistants for over a year now on my personal projects, I've tried most coding agents from Copilot to Augment Code, and what makes the biggest difference, besides the base model like Claude Opus or ChatGPT-5.2, is the context available to the AI. What the LLM has in its context window makes a huge impact on what you get out of the model.
Giving the AI the right context is crucial for getting quality results.
Building on my recent post about AGENTS.md and my discussion about DDRs, I often found myself manually specifying all the relevant AGENTS.md and DDR (Design Decision Records) files in my prompts before getting started. This works really well as the AI reads the specified files and then knows all the relevant context.
"Please read src/app/AGENTS.md, src/api/AGENTS.md, and docs/ddrs/DDR-010-auth-flow.md before helping me with authentication..."
It works but it's tedious. And I'd inevitably forget something important.
Instead of me figuring out which files are relevant, why not let the AI figure it out?
I created a /read-references slash command that does exactly this. The AI reads two index files, analyses what I'm asking for, and loads all the relevant documentation itself.
I maintain two simple index files that the AI keeps updated:
These indexes give the AI a map of all available context without forcing it to read everything up front.
# /read-references - Autonomous Context Loading
---
description: Comprehensive Context Loading with All Tools
---
**Purpose**: Load relevant CLAUDE.md and DDR files AND use all available tools ([Tool Redacted], web search, etc.) to build a complete understanding of context.
## ⛔ ABSOLUTE RULE: NEVER RUSH ⛔
**YOU WILL BE CALLED OUT IF YOU RUSH THROUGH THIS.**
This is NOT a speed exercise. This is a THOROUGHNESS exercise. The user expects you to:
- Read EVERYTHING that could possibly be relevant
- Search for patterns and examples in the codebase using [Tool Redacted]
- Look at similar implementations to understand conventions
- Read actual source code, not just documentation
- Use web search and documentation tools to understand external context
- Spend time understanding the full context
**IF YOU THINK YOU'RE DONE, YOU'RE PROBABLY NOT.** Research more.
## ⚠️ MANDATORY FIRST STEP - READ INDEX FILES IMMEDIATELY ⚠️
**YOU MUST READ THESE TWO INDEX FILES FIRST, BEFORE DOING ANYTHING ELSE:**
1. **C:\git\[Project Name]\AGENTS-REFERENCE.md** - Index of ALL CLAUDE.md files by component
2. **C:\git\[Project Name]\docs\ddrs\CLAUDE.md** - Index of ALL relevant DDRs
**DO NOT SKIP THIS STEP.** Even if the user provides specific file paths in the command, you MUST read the index files first. This is non-negotiable. No exceptions. No judgment calls.
---
## Task: Read Required Files AND Search the Codebase
**Step 1**: Read the two mandatory index files above (AGENTS-REFERENCE.md and docs/ddrs/CLAUDE.md)
**Step 2**: Analyze user's request to determine which CLAUDE.md and DDR files are relevant.
**🚨 CRITICAL: Show curiosity and dig deeper - DO NOT take shortcuts!** When analyzing the request:
- Read broadly across related components, not just the obvious ones
- Search for DDRs that might be relevant to the topic (e.g., security topics → read DDR-019, DDR-010, etc.)
- Consider architectural dependencies and cross-cutting concerns
- When in doubt about relevance, ERR ON THE SIDE OF READING MORE FILES
- Extract keywords from the task and match them to DDR titles and component purposes
**Examples of context analysis:**
- Frontend files (src/app/) → read frontend CLAUDE.md (src/app/CLAUDE.md, src/app/src/services/CLAUDE.md, src/app/src/services/api/CLAUDE.md, tests if relevant)
- Backend files (src/api/) → read backend CLAUDE.md (src/api/*/CLAUDE.md, src/common/[Project Name].Common/CLAUDE.md)
- DDRs mentioning UI/frontend → read frontend CLAUDE.md files
- DDRs mentioning backend → read backend CLAUDE.md files
- Testing → read testing CLAUDE.md (src/app/tests/CLAUDE.md, src/app/tests/e2e-journeys/CLAUDE.md)
- **Security topics** → read DDR-019 (CSP), DDR-010 (authentication), DDR-048 (bot defense), DDR-049 (OAuth), etc.
- **Authentication/cookies** → read related DDRs AND API Host CLAUDE.md AND frontend CLAUDE.md
- **Middleware/headers** → read API Host CLAUDE.md, relevant security DDRs, and authentication DDRs
**Step 3**: Read all relevant files comprehensively:
- **When in doubt, read MORE rather than fewer** - over-read rather than miss critical context (this is NOT a shortcut to speed; it's the RIGHT way to do this)
- Read source code files for full context, not just CLAUDE.md files
- **ALWAYS read specific files mentioned by user** in their message or command arguments (file paths, explicit references, example files)
- **READ RELATED COMPONENTS**: If working with cookies, read authentication + API Host files. If working with middleware, read security DDRs + API Host. If working with any security topic, read all security-related DDRs.
- If a file read fails, keep trying until you succeed
- **DO NOT assume you know what's relevant** - investigate the full context to understand connections and dependencies
**Step 4**: USE [Tool Redacted] AND ALL AVAILABLE TOOLS FOR DEEP CODEBASE UNDERSTANDING
### 🎯 Leverage the [Tool Redacted] MCP Tool
**The [Tool Redacted] MCP tool is your most powerful resource for understanding patterns and context across the codebase.** It provides advanced searching and indexing capabilities:
- **`[Tool Redacted]`** - Search for code patterns, keywords, and implementations across the entire codebase with regex support, file filtering, and context lines
- **`[Tool Redacted]`** - Find files matching glob patterns (e.g., all components with "Form", "Modal", "Edit" in their names)
- **`[Tool Redacted]`** - Get summaries of files including function/class definitions, imports, and complexity metrics
- **`[Tool Redacted]`** - Build a complete symbol index for comprehensive code understanding across the entire project
**USE [Tool Redacted] EXTENSIVELY** when:
- Searching for similar implementations across the codebase
- Finding all usages of a particular pattern (e.g., all `useQueryState` usage, all API hooks, all Result<T> handlers)
- Understanding where specific functionality is implemented
- Identifying patterns and conventions in the codebase
- Locating related files and dependencies
### 🌐 Additional Research Tools
Don't limit yourself to just reading local files:
- **Web Search** (`WebSearch`, `mcp__google-search__search`): Look up libraries, frameworks, patterns, best practices, and architectural approaches relevant to the task
- **Web Fetch** (`WebFetch`, `mcp__fetch__fetch`, `mcp__google-search__read_webpage`): Read documentation, examples, and reference implementations when you have a specific URL
- **Context7 Library Docs** (`mcp__context7__resolve-library-id`, `mcp__context7__get-library-docs`): Get up-to-date library documentation for any framework, library, or tool used in the project (Next.js, React, TanStack Query, NUnit, etc.)
### Search for Patterns and Examples in the Codebase
This is where most AIs fail. Don't just read docs - FIND REAL EXAMPLES. Use the [Tool Redacted] tools systematically.
#### For UI/Component Tasks (editing, forms, modals, etc.)
1. **Search for similar implementations using [Tool Redacted]**:
- Use `[Tool Redacted]` to locate files with similar patterns (e.g., `*Edit*.tsx`, `*Modal*.tsx`, `*Form*.tsx`)
- Use `[Tool Redacted]` to find implementations of similar functionality
- Read at least 2-3 similar implementations to understand established patterns
2. **Read the actual component mentioned by the user**:
- Don't just skim - read the ENTIRE file
- Understand the current structure, state management, and patterns used
- Understand how it integrates with the service layer
3. **Search for type definitions**:
- Use `[Tool Redacted]` to locate type definition files (e.g., `*Payload.ts`, `*Request.ts`, `*Response.ts`)
- Read the type definitions WITH CONTEXT
- Understand what fields are editable vs read-only
4. **Look for existing API hooks**:
- Use `[Tool Redacted]` to locate service layer files
- Use `[Tool Redacted]` to find all mutation hooks and their usage patterns
- Understand the parameters and return types
5. **Check for styling conventions**:
- Use `[Tool Redacted]` to find similar styled components
- Understand the Tailwind v4 + HeroUI patterns used in the project
#### For API/Backend Tasks
1. **Use [Tool Redacted] to find the controller** that handles the endpoint
- `[Tool Redacted]` to search for the endpoint path, method, or controller name
2. **Find the command/query handler** using [Tool Redacted] to understand business logic
- Search for related handler classes and their patterns
3. **Locate the aggregate** using [Tool Redacted] pattern search to understand domain rules
- Find examples of similar aggregates
4. **Search for similar endpoints** using [Tool Redacted] regex patterns to understand conventions
- Look at request/response patterns
5. **Find and read request/response payload types** using [Tool Redacted] to locate type definitions
6. **Check test examples** using [Tool Redacted] to find similar endpoint tests
#### For Testing Tasks
1. **Find similar test files** using `[Tool Redacted]` with patterns like `*.test.ts`, `*.spec.ts`, `*Tests.cs`
2. **Search for test patterns** using `[Tool Redacted]` to find testing conventions
3. **Locate test data setup** using [Tool Redacted] to find factories, fixtures, and test utilities
4. **Use web search** to understand best practices for testing frameworks (NUnit, Jest, Playwright) if needed
5. **Look at test patterns** across similar test files to understand the project's testing style
## Step 5: VERIFY YOU HAVE EVERYTHING
**START HERE - MANDATORY VERIFICATION:**
- [ ] **HAVE I READ C:\git\[Project Name]\AGENTS-REFERENCE.md?** (If NO, STOP and read it now)
- [ ] **HAVE I READ C:\git\[Project Name]\docs\ddrs\CLAUDE.md?** (If NO, STOP and read it now)
**ONLY AFTER CONFIRMING THE TWO INDEX FILES ABOVE, continue with:**
- [ ] Have I read all files explicitly mentioned by the user?
- [ ] Have I used [Tool Redacted] tools to search for similar implementations?
- [ ] Have I used `find_files` to locate relevant source files?
- [ ] Have I used `search_code_advanced` to understand patterns and find implementations?
- [ ] Have I read the actual source files, not just documentation?
- [ ] Have I read type definitions with full context?
- [ ] Have I understood the existing patterns and conventions?
- [ ] Have I looked at how similar features are implemented elsewhere?
- [ ] Do I understand the data flow (UI → API → backend)?
- [ ] Have I read related CLAUDE.md files for all layers involved?
- [ ] Have I used web search to understand external libraries, patterns, or best practices relevant to the task?
- [ ] Have I used Context7 library docs to get up-to-date documentation for frameworks/tools used?
- [ ] Have I leveraged [Tool Redacted] deep symbol search for cross-cutting concerns?
**IF YOU ANSWERED "NO" OR "MAYBE" TO ANY OF THESE, KEEP RESEARCHING.**
### 📋 Required Tools to Use Before Responding
**ALWAYS USE THESE TOOLS** to build complete understanding:
- ✅ Read all CLAUDE.md and DDR files mentioned in analysis
- ✅ Use `[Tool Redacted]` to locate relevant source files by pattern
- ✅ Use `[Tool Redacted]` to understand patterns and find similar implementations
- ✅ Use `[Tool Redacted]` to understand file structure and key definitions
- ✅ Use `WebSearch` or `mcp__google-search__search` for external context, best practices, and library information
- ✅ Use `mcp__context7__resolve-library-id` and `mcp__context7__get-library-docs` for framework/library documentation
- ⚠️ Use `WebFetch` when you need specific content from a known URL
**DO NOT settle for partial understanding** - use all these tools in parallel where possible to build a complete mental model before responding.
---
## 🔥 Remember: Thoroughness > Speed
The user would rather wait 3 minutes for you to research comprehensively than have you rush through in 30 seconds and miss critical context. **TAKE YOUR TIME. BE THOROUGH. USE ALL AVAILABLE TOOLS. SEARCH COMPREHENSIVELY.**
---
## Final Response
When you have completed all research and are ready to assist the user, respond with ONLY:
**I have completed all required research, What would you like to do?**
Do NOT provide any summaries, lists, or explanations of what you read. Simply end with this message.
---
If the only thing given to you is a file name then you don't need to do much research. Just read the file and understand the code.
As you can see, it's often necessary to constrain the AI with extra instructions. If I observe behavior that I don't like, I'll update the prompt to constrain the actions next time.
Now when I want to work on something, I just write:
/read-references I want to work on the forgotten password feature
The AI:
No more guessing which files I need to specify. No more forgetting that one critical DDR that would have prevented a mistake.
The compound effect of AGENTS.md + DDRs + automatic loading is greater than the sum of its parts. The AI doesn't just know what patterns to use - it understands the architectural decisions behind them and can make better suggestions because it sees the full picture.
The AI does the work of keeping context organized and loading the right files. You just focus on building.
This approach has transformed how I work with AI. Instead of the AI being a tool I have to constantly correct and guide, it becomes a partner that understands the project and works within its constraints.
What's your approach to managing context for AI coding assistants?