Claude Code — Project Structure Guide

Purpose: This document defines the standard file and folder structure for any project developed with Claude Code. Read this before writing any code or creating any files. Follow it exactly.

---

Overview

A Claude Code project has two layers of files living alongside the source code:

1. Context files — tell Claude who this project is, how it works, and what rules apply
2. Spec files — define what to build, one feature or fix at a time

Both layers are committed to git. They are part of the project, not throwaway documents.

---

Required File Structure

project-root/
│
├── CLAUDE.md                        ← Global rules for this project (max 200 lines)
├── ARCHITECTURE.md                  ← Living map of the codebase structure
│
├── .claude/
│   ├── settings.json                ← Project-level hooks and tool permissions
│   └── agents/                      ← Specialized subagents (optional)
│
├── specs/
│   ├── spec-template.md             ← Master template — copy this for every new spec
│   ├── [feature-name]-spec.md       ← One spec per feature or fix
│   └── [feature-name]-plan.md       ← Generated by Claude before implementation starts
│
├── src/                             ← Source code
│   ├── CLAUDE.md                    ← Module-level rules (only if conventions differ from root)
│   ├── [module-a]/
│   │   ├── CLAUDE.md                ← Rules specific to this module (only if needed)
│   │   └── ...
│   └── [module-b]/
│       └── ...
│
└── tests/
    └── ...

---

File Responsibilities

CLAUDE.md (root) — The most important file

This is the first file Claude reads. Keep it under 200 lines — beyond that, instruction-following degrades.

What goes here:

• Stack and versions (language, framework, key libraries)
• How to run the project locally
• How to run tests and linting
• Global code conventions
• Files and directories that must never be modified
• Where specs live
• The architecture update rule (see below)

What does NOT go here:

• Module-specific conventions → those go in the module's own CLAUDE.md
• Feature specs → those go in specs/
• Architecture documentation → that goes in ARCHITECTURE.md

Template:

# CLAUDE.md

## Stack
- [Language and version]
- [Framework and version]
- [Key libraries]

## Commands
- Run project: `[command]`
- Run tests: `[command]`
- Lint: `[command]`

## Conventions
- [Convention 1]
- [Convention 2]

## Files to never modify
- `path/to/file` — [reason]

## Specs
All specs live in `specs/`. Before implementing any feature, read the spec fully
and generate a plan file at `specs/[feature-name]-plan.md`.

## Architecture update rule
After completing any implementation task, update `ARCHITECTURE.md` to reflect
the current state of the codebase. Add new modules, update descriptions, and
remove entries that no longer exist.

---

ARCHITECTURE.md — Living map of the codebase

This file gives Claude (and humans) a fast mental model of the project without reading every file.

What goes here:

• Directory tree with a one-line description of each module
• Main data flow (how a request moves through the system)
• Key architectural decisions and why they were made
• External dependencies and what they do
• Anything non-obvious about how the pieces connect

What does NOT go here:

• Code — no code snippets unless they clarify a non-obvious pattern
• Specs or requirements
• Decisions still under discussion

How it stays up to date: Two mechanisms work together:

1. CLAUDE.md global rule — The architecture update rule in CLAUDE.md tells Claude to update this file after every implementation task. This applies to every session automatically.

2. Spec acceptance criteria — Every spec includes this checkbox:

   - [ ] ARCHITECTURE.md updated to reflect changes made in this spec

   This makes the update a verifiable condition of completion, not a suggestion.

Template:

# Architecture

## Directory structure

src/ ├── [module-a]/ — [what this module does] ├── [module-b]/ — [what this module does] └── [module-c]/ — [what this module does]

## Main data flow

[Describe how a typical request or operation moves through the system.]

## Key decisions

- **[Decision]**: [Why it was made this way]
- **[Decision]**: [Why it was made this way]

## External dependencies

- `[library]` — [what it does in this project]
- `[service]` — [what it does in this project]

---

specs/ — One file per feature or fix

Every piece of work starts with a spec. No implementation without a spec.

Naming convention:

specs/[feature-name]-spec.md     ← written by the developer
specs/[feature-name]-plan.md     ← generated by Claude before implementation

The plan file is mandatory. Before Claude writes a single line of implementation code, it must generate [feature-name]-plan.md with a sequential task breakdown. See spec-template.md for the required format.

Spec files are committed to git alongside the code they describe. This preserves the history of decisions.

---

Module-level CLAUDE.md files

Create a CLAUDE.md inside a module only when that module has conventions that differ from the root. Do not create them preemptively.

When to create one:

• The module uses a different testing pattern than the rest of the project
• There are files in this module that must never be touched
• The module has a specific pattern that overrides the global pattern

How Claude uses them: Claude reads the CLAUDE.md closest to the file it is working on. More specific rules override general ones.

---

.claude/settings.json — Project hooks

Use this file to configure behaviors that must happen automatically during Claude Code sessions for this project.

Common uses:

• Block edits to protected files
• Run linting after every file edit
• Enforce test execution before stopping

This file is committed to git so all team members share the same automated behaviors.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "[lint command] $(jq -r '.tool_input.file_path')"
          }
        ]
      }
    ]
  }
}

---

How to initialize this structure

When starting a new project, create these files in this order:

1. CLAUDE.md — fill in stack, commands, conventions, and the architecture update rule
2. ARCHITECTURE.md — document the initial structure, even if it is small
3. specs/spec-template.md — copy the standard spec template
4. .claude/settings.json — configure any project-wide hooks

Do not create module-level CLAUDE.md files until the project is large enough to need them.

---

Rules Claude must follow at all times

• Never implement without a spec. If there is no spec file, ask for one before writing code.
• Never skip the plan file. Generate [feature-name]-plan.md before any implementation starts.
• Never modify files listed in CLAUDE.md as protected, regardless of what the spec says.
• Always update ARCHITECTURE.md after completing an implementation task.
• Keep each CLAUDE.md under 200 lines. If it grows beyond that, split content into module-level files or .claude/rules/.
• Read context files before touching code. The read order is: root CLAUDE.md → module CLAUDE.md → ARCHITECTURE.md → spec file → plan file.
• Always cite the exact localhost URL when reporting a dev server. When starting or referencing a local development server, include the full URL with port (e.g., http://localhost:3000) in the response. Do not assume the user is on the default port or the same port as a previous session.