Feature: Native support for hierarchical project context directories

Feature Request: Native Hierarchical Project Context with Selective Loading

Summary

Add native support for a hierarchical project context directory (e.g., .claude/context/) where Claude discovers the structure at session start but only reads files selectively when relevant to the current task.

Problem

Currently, CLAUDE.md is loaded entirely at session start regardless of what task the user needs help with. For complex projects this means:

1. Context pollution: Irrelevant conventions compete for attention with relevant ones
2. Scaling issues: Large projects need extensive documentation, but loading it all wastes context window
3. Subagent blindness: Explore/Plan agents don't have access to project context, leading to suggestions that don't follow project patterns

Proposed Solution

Directory Structure

.claude/context/
├── project/
│   └── overview/context.md
├── api/
│   ├── overview/context.md
│   └── patterns/context.md
├── database/
│   └── patterns/context.md
└── testing/
    └── patterns/context.md

Each context.md file includes a Keywords: line for discoverability:

# API Patterns
Keywords: api, endpoint, handler, route, REST, validation

## Conventions
...

Proposed Implementation

1. SessionStart: Structure Discovery

Claude Code scans for .claude/context/ and injects the tree structure + keywords into the system prompt:

Project context available in .claude/context/:
├── project/overview       Keywords: architecture, structure, monorepo
├── api/patterns           Keywords: endpoint, handler, REST, validation
├── database/patterns      Keywords: schema, migrations, queries
└── testing/patterns       Keywords: jest, mocks, fixtures

Claude sees what context is available, but contents are not loaded yet.

2. Task Execution: Selective Read

Claude uses the existing Read tool to load relevant files based on the user's task. No new tools needed.

User: "Add a new API endpoint"
→ Claude reads .claude/context/api/patterns/context.md
→ Claude follows project-specific API conventions

3. Subagent Spawning: Automatic Context Injection

When the Task tool is invoked, Claude Code:

1. Analyzes the prompt parameter
2. Matches keywords/folder names against the context index
3. Appends matched context file contents to the subagent's system prompt

Task(prompt="Find how error handling works in the API layer")
→ Claude Code matches "API" and "error handling"
→ Injects api/patterns/context.md into subagent system prompt

This ensures Explore/Plan agents follow project conventions without manual intervention.

Why Selective Loading Matters

| Scenario | Load Everything | Selective Loading |
|----------|-----------------|-------------------|
| "Fix API auth bug" | 15 context files loaded | Only api/, auth/ read |
| Explore agent task | No context or all context | Relevant context auto-injected |
| "Update database schema" | API patterns pollute reasoning | Only database/ loaded |

The goal is minimal relevant context - enough to follow project conventions without noise.

Example Workflow

$ claude
Project context available in .claude/context/:
├── project/overview       Keywords: architecture, structure
├── api/patterns           Keywords: endpoint, handler, REST
├── database/patterns      Keywords: schema, migrations
└── testing/patterns       Keywords: jest, mocks

> Help me add a new API endpoint

Claude: (reads api/patterns/context.md based on task)
I see your API uses controller pattern with zod validation. Let me create...

Benefits

• Right-sized context: Only what's needed for the task
• Subagent effectiveness: Plan/Explore agents automatically follow project patterns
• Maintainability: Small focused files instead of monolithic CLAUDE.md
• Discoverability: Keywords + folder names guide selection
• No new tools: Uses existing Read tool for selective loading