Claude Code Project Structure: 7 Essential Ways to Organize Your Files in 2026

🌐 この記事を日本語で読む

For official documentation, see the Anthropic Claude Code docs. MCP specifications are available at modelcontextprotocol.io.

If you want to use Claude Code seriously, your project structure is the foundation. A poorly organized directory makes it difficult for the AI to find the right files, leading to inconsistent results and wasted tokens.

In this article, I share the Claude Code project structure I use in production, along with detailed guidance on writing CLAUDE.md — the configuration file that shapes how AI behaves in every conversation.

Overview of the Claude Code Project Structure

Here is my actual repository layout:

project-root/
├── .claude/
│   ├── CLAUDE.md          # Global config (most important)
│   ├── settings.local.json # Local settings
│   ├── skills/            # Custom skills
│   ├── scheduled-tasks/   # Recurring tasks
│   ├── scripts/           # Helper scripts
│   ├── mcp-servers/       # Custom MCP servers
│   └── projects/          # Project-specific memory
├── scripts/               # Standalone tools
├── the-stash/             # Finance dashboard app
├── .mcp.json              # MCP connection config
└── .gitignore

The key principle is to centralize everything under .claude/. Claude Code automatically recognizes this directory, so anything placed here is loaded without explicit configuration. As a result, your Claude Code project structure stays clean and maintainable.

CLAUDE.md — Your Permanent Instructions to AI

CLAUDE.md is the configuration file that Claude Code reads automatically at the start of every conversation. Think of it as permanent instructions to the AI — whatever you write here applies to all future sessions.

Therefore, documenting your project-specific rules and development guidelines here eliminates the need to repeat the same explanations. Below are the sections I include in my own CLAUDE.md.

Desktop Automation Rules

## Windows Desktop Automation
1. Launch app → 2. Screenshot → 3. Verify coordinates → 4. Click/Type

This defines the workflow for Windows MCP desktop operations. Without this, Claude Code might try different approaches each time, resulting in unstable automation. In other words, standardizing the workflow within your Claude Code project structure directly improves reliability.

Browser Automation Priority

## Browser Automation
- Primary: k-chrome MCP (custom, uses existing Chrome profile)
- Fallback: Windows MCP (screenshot + coordinate clicking)

When multiple browser MCPs are available, you need to define which one takes priority. Otherwise, Claude Code may randomly select tools, leading to inconsistent behavior.

Security Rules

## Security Rules
- Never enter passwords (user does it manually)
- Financial accounts are read-only

A security-first approach is essential. Especially with browser and desktop automation, Claude Code frequently encounters login screens. By including this rule, the AI automatically pauses for manual input whenever authentication is required.

Performance Rules — Token Conservation

## Performance Rules
- Delegate investigations requiring 3+ Grep/Glob calls to sub-agents
- Read only needed sections of files over 100 lines
- Never read the same file twice

Since Claude Code consumes tokens, preventing waste is important. These rules roughly doubled my effective conversation length. For instance, reading only relevant portions of large files instead of the entire contents saves significant tokens per session.

Skills, Scheduled Tasks, and Scripts Directories

Custom skills go in .claude/skills/, each in its own folder with a SKILL.md file. Claude Code automatically registers them. Similarly, scheduled tasks follow the same structure under .claude/scheduled-tasks/.

Standalone Python scripts that work independently of Claude Code go in scripts/ at the project root. This separation keeps your Claude Code project structure organized by function.

Five Tips for Folder Design

• One folder, one function — Separate skills, tasks, and scripts into individual directories
• Keep CLAUDE.md concise — Excessive length wastes tokens. Write rules and policies only
• Configure .gitignore — Exclude cache files, temp files, and credentials without exception
• Unify naming conventions — Use kebab-case (e.g., amazon-purchase) consistently
• Co-locate documentation — Place related docs in the same folder for easy discovery

Following these principles ensures your Claude Code project structure remains maintainable over time. Consequently, collaboration with AI becomes smoother and more productive.

Next Up

The next article covers MCP Servers. You will learn how the Model Context Protocol extends Claude Code’s capabilities, and see the custom MCP servers I have built for browser control, email, and desktop automation.