Feature Request: Systematic Directory Organization for Claude Code Projects

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Dear Anthropic Development Team,

I hope this message finds you well. I'm writing to suggest an enhancement to Claude Code that would improve project organization and maintainability as codebases grow in complexity.

Issue Overview

While working with Claude Code on multiple projects, I've observed a consistent pattern: initial projects maintain clean, organized directory structures. However, as projects grow and become more dynamic, new files increasingly get created in the home directory rather than being placed in logically organized subdirectories. This creates maintenance challenges and reduces code discoverability as projects scale.

Current Behavior

• Early-stage projects: Files are properly organized by function (e.g., /src, /tests, /config, /utils)
• - Mature/growing projects: New files default to placement in the working directory or home directory, breaking the established structure
• - - Result: Directory bloat and reduced project coherence

Suggested Improvement

Implement systematic directory organization logic in Claude Code that:

1. Analyzes existing project structure at the start of each session to understand the established organizational pattern
2. 2. Enforces structural consistency by defaulting new file creation to appropriate subdirectories based on file type and purpose (e.g., utilities → /utils, tests → /tests, configurations → /config)
3. 3. Provides user control through optional parameters to override default placement when needed
4. 4. Documents placement decisions so users understand why files were created in specific locations

Impact

This enhancement would significantly improve:

• Long-term project maintainability
• - Code discoverability and navigation
• - - Consistency across Claude Code sessions
• - - - Developer productivity when working with complex, growing projects

Thank you for considering this feature request. I'm happy to provide additional context or examples if helpful.

Proposed Solution

The implementation should work as follows:

1. Project Structure Analysis: When Claude Code initializes a session with an existing project, it would scan the directory structure to identify the established organizational pattern. For example, it would recognize directories like /src, /tests, /utils, /config, etc.
2. File Type Mapping: Establish intelligent mapping between file types/purposes and appropriate subdirectories:
3. - Test files → /tests or /test
4. - Utility functions → /utils or /lib
5. - Configuration files → /config
6. - Source code → /src
7. - Documentation → /docs
8. Smart File Creation: When creating new files, Claude Code would default to placing them in the appropriate subdirectory based on both the file type and the project's existing structure.
9. User Override: Provide clear options for users to override the default placement when needed, without losing the organizational benefits for future files.
10. Transparency: Log and display placement decisions so users understand the reasoning.

Alternative Solutions

Currently, I work around this issue by:

1. Manual File Organization: Manually moving files to appropriate directories after they're created, which is time-consuming and error-prone
2. 2. Custom Naming Conventions: Using verbose naming patterns in file names to indicate their purpose, which clutters the codebase
3. 3. Project Templates: Creating project templates with pre-established structure, though this doesn't help with growing projects that deviate from the template

These workarounds are inefficient and don't fully solve the problem of maintaining organization as projects evolve over time.

Priority

Critical - Blocking my work

Feature Category

File operations

Use Case Example

Scenario: Growing a Node.js backend project

1. I start a new backend project with Claude Code, establishing a clean structure:
2. - /src - main application code
3. - /tests - test files
4. - /utils - utility functions
5. - /config - configuration files
6. As the project grows, I ask Claude Code to:
7. - Add a new utility function for authentication
8. - Create a test file for a new API endpoint
9. - Add an environment configuration file
10. Current behavior: All these files get created in the home directory, requiring me to manually move them to the correct folders after creation.
11. With this feature: Claude Code would automatically place:
12. - The utility function in /utils
13. - The test file in /tests
14. - The config file in /config
15. Result: Project structure remains clean and organized without manual intervention. As I continue adding files over weeks or months, the organization is maintained automatically.

Additional Context

_No response_