Claude Code Folder Structure for Software Development

Why folder structure matters more than the prompts

Most people start with Claude Code by writing better prompts. That’s the wrong order.

The folder structure you give Claude Code matters more than any prompt — because it defines what context the agent has access to, which agents exist, and how commands are organized. Get the structure right, and average prompts produce great output. Get the structure wrong, and even brilliant prompts fail.

This is the structure I use across 4 production SaaS products. It’s evolved over 12 months of daily use.

The complete structure

my-project/
├── .claude/
│   ├── agents/
│   │   ├── architect.md         # System design + architecture decisions
│   │   ├── code-reviewer.md     # PR review with senior-level standards
│   │   ├── debugger.md          # Production bug investigation
│   │   └── refactorer.md        # Clean Architecture refactoring
│   ├── commands/
│   │   ├── godmode.md           # Maximum verbosity mode
│   │   ├── explainlikeim5.md    # Simplified explanations
│   │   ├── compact.md           # Token-efficient mode
│   │   ├── insights.md          # Strategic situational assessment
│   │   └── ship.md              # Production-ready code mode
│   └── settings.json            # Per-project Claude config
├── knowledge/
│   ├── 01-product.md            # What this product is + who it's for
│   ├── 02-architecture.md       # Clean Architecture conventions
│   ├── 03-stack.md              # Tech stack + dependency choices
│   ├── 04-patterns.md           # Code patterns we use (and don't)
│   ├── 05-glossary.md           # Domain terminology
│   └── 06-deployment.md         # How we ship to production
├── scripts/
│   └── (your project scripts)
├── src/
│   └── (your code)
├── docs/
│   └── strategy/                # High-level strategic docs
└── CLAUDE.md                    # Top-level Claude Code entry point

What goes in each folder

.claude/agents/

One file per specialized agent. Each agent is a markdown file with YAML frontmatter:

---
description: Reviews PRs with senior-level engineering standards. Use when reviewing code changes, before merging, or when discussing architecture trade-offs.
---

You are a senior software engineer with 15+ years of experience reviewing code...

The description field is critical. Claude Code uses it to decide which agent to invoke for which task.

.claude/commands/

Slash commands you trigger with /commandname. Each is a single markdown file with the prompt.

knowledge/

Numbered markdown files with the canonical truth about your project. Numbering matters — Claude Code reads them in order, so put foundational stuff first.

The 6-file structure I use:

1. Product — What this is, who it serves, the problem it solves
2. Architecture — Clean Architecture layers, dependency rules, where things live
3. Stack — Exact versions, why each choice was made
4. Patterns — Repeated code patterns we use (e.g., Result types, error handling)
5. Glossary — Domain terminology that’s easy to misunderstand
6. Deployment — How we ship, what infrastructure looks like

CLAUDE.md

The top-level entry point. Claude Code reads this first when you open the project. Keep it short — under 200 lines. Point to the knowledge files instead of inlining everything.

Example:

# Project: [Product Name]

## What this is
One paragraph. See `knowledge/01-product.md` for full context.

## Architecture
Clean Architecture, .NET 8 + React 18. See `knowledge/02-architecture.md`.

## Where to find things
- Agent definitions → `.claude/agents/`
- Slash commands → `.claude/commands/`
- Knowledge base → `knowledge/`
- Strategic docs → `docs/strategy/`

## Conventions
- All code follows Clean Architecture (no Infrastructure refs from WebAPI)
- All PRs go through `/codereview` agent before merge
- All architectural changes go through `/architect` agent first

What NOT to do

Get the full template

I’ve packaged this exact structure as a template you can clone for any project, including 6 starter agents and 8 commands I use daily.

Download the ZIP → (link sent via email after submitting above)

The template includes:

• .claude/ folder with 6 agents and 8 commands
• knowledge/ folder with 6 templates filled with prompts
• CLAUDE.md template
• README.md explaining how to adapt it to your project

---

Want resources like this every week? Subscribe below.