[Feature Request] Multi-file guidance organization and discovery in Claude Code (i.e. CLAUDE.md)

Bug Description

Suggestion: Multi-File Guidance Organization for CLAUDE.md

Issue

A Claude instance and I could not find documentation or product features for organizing Claude guidance across multiple files. For non-trivial projects, CLAUDE.md files grow to 4000+ lines covering development standards, testing practices, documentation conventions, and workflows. This creates:

• Maintainability issues - difficult to navigate and update
• Context inefficiency - Claude may process irrelevant guidance for every task
• Organization challenges - no clear way to structure scope-specific guidance

Current Behavior

When asked to organize large guidance files, a Claude instance created a directory structure:

.claude/
├── README.md
├── development.md
├── testing.md
├── documentation.md
└── workflows/

The Claude instance described this as a convention or standard. Later, another Claude instance did not succeed in identifying or producing supporting documentation when asked.

Example: CLI app

https://github.com/JeffreyUrban/cli-template/tree/main/%7B%7Bcookiecutter.project_slug%7D%7D-workspace/%7B%7Bcookiecutter.project_slug%7D%7D/.claude

Requested Features

1. Multi-File Guidance Discovery

• Official directory structure for organizing guidance files
• Mechanism for Claude to discover and load files (automatic or explicit reference)
• Documentation on how to split and reference guidance

2. Context-Aware Guidance Loading

• Apply scope-specific guidance based on task context (coding, testing, documentation)
• Support for conditional guidance (project phases, templates vs. production)
• Control over which guidance applies when

3. Token-Efficient Loading

• Load only relevant guidance for current task
• Visibility into which guidance is active
• Performance guidelines for multi-file organization

4. Guidance Lifecycle Management

• Patterns for temporary or phase-specific guidance
• Managing guidance evolution as projects mature
• Deprecation and versioning support

Questions

1. Does an official pattern exist for splitting CLAUDE.md that we missed?
2. Should guidance be organized by scope (development, testing) and/or task type (workflows)?
3. How should Claude discover guidance files - automatic directory scanning or explicit references?
4. What are the token/performance implications of multiple files vs. one large file?
5. Are there size limits or recommendations for when to split?

Impact

Without this capability:

• Users invent incompatible organizational structures
• No way to verify if custom structures actually work or will continue to function
• Claude instances assert non-existent "standards," undermining trust
• No path from simple projects to complex ones
• Teams cannot effectively organize guidance for real-world codebases

Suggested Documentation

If features exist:

• Document the official pattern for multi-file guidance
• Provide examples and best practices
• Clarify how Claude discovers and applies files

If features don't exist:

• Consider implementing multi-file guidance as a core capability
• Document how projects should handle large guidance requirements
• Provide official patterns to prevent fragmentation

Environment Info

• Platform: darwin
• Terminal: pycharm
• Version: 2.0.57
• Feedback ID: