Claude Folder Blueprint (March 2026).docx

The .claude Folder Blueprint

@keshavsuki

Context clarity, not context bloat.

Stop overloading CLAUDE.md. Use a structured .claude folder instead.

Small, focused files. Claude knows exactly what to load and when.

Note on ~/.claude/projects/ paths

Claude Code names project folders by replacing slashes with hyphens in your path.

e.g. /Users/you/projects/myapp becomes ~/.claude/projects/-Users-you-projects-myapp/

The structure in this guide uses simplified names for clarity.

Directory Structure

~/.claude/

├── CLAUDE.md # GLOBAL: <500 lines

└── projects/

└── your-project/

├── CLAUDE.md # PROJECT: <1000 lines

├── session-log.md # Updated when instructed in CLAUDE.md

├── project-state.md # Updated when instructed in CLAUDE.md

├── tools.md # APIs, credentials, tool refs

├── context.md # Domain knowledge, terminology

└── .claude/

├── commands/

│ ├── voice-agent-setup.md

│ ├── database-schema.md

│ └── testing-protocol.md

├── scripts/

│ ├── build.sh

│ ├── deploy.sh

│ └── test.sh

└── reference/

├── api-docs.md

├── architecture.md

└── incident-log.md

File Quick Reference

File	Size Limit	Purpose
CLAUDE.md (global)	Recommended <500	Permanent rules, identity, operating principles
CLAUDE.md (project)	Recommended <1000	Architecture, tech stack, conventions for this project
session-log.md	Auto	What happened this session — instruct Claude in CLAUDE.md to maintain this
project-state.md	Auto	Current phase, blockers, metrics — instruct Claude in CLAUDE.md to maintain this
tools.md	Scannable	APIs, credential paths (no values), platform references
context.md	As needed	Business logic, client info, domain terminology
.claude/commands/	Per task	Reusable prompt files for common repeated tasks
.claude/scripts/	Automated	Shell scripts: build, deploy, test
.claude/reference/	Deep docs	Architecture, API docs, incident log — not loaded by default

01	CLAUDE.md (Global) — Who You Are

Loads in every session, every project. Keep it lean. Bloat here wastes context everywhere.

# CLAUDE.md

## WHO YOU ARE

Your name / role / working style

## PERMANENT RULES

Never delete user data

Always ask before major changes

Always test before deploying

## HOW YOU THINK

Problem-solving approach

Communication style

Decision framework

## TOOLS YOU USE

APIs: reference paths only, no secrets

Platform preferences

## OPERATING PRINCIPLES

When to work autonomously

When to pause and ask

When to escalate

02	CLAUDE.md (Project) — This Project's Rules

Sits in your project root. Loads when Claude works in this project. Architecture, stack, conventions.

# CLAUDE.md — Project Specific

## PROJECT NAME & SCOPE

What this project does

Current phase

Key constraints

## TECH STACK

Language: Node.js/TypeScript

Database: PostgreSQL

Cache: Redis

## ARCHITECTURE

Pattern: MVC / Event-driven / Serverless

Folder structure conventions

## CONVENTIONS

Naming: camelCase for functions, PascalCase for classes

Error handling: try-catch, log to Sentry

Testing: Jest, >80% coverage

## CURRENT BLOCKERS

What is stuck and what it needs

03	session-log.md + project-state.md

These are custom conventions. Add an instruction in CLAUDE.md telling Claude to maintain these files. Claude will update them when you ask or when it completes major work.

session-log.md — Updated at Session End

# Session Log — 2026-03-26

## WHAT WAS DONE

Built auth middleware

Fixed database migration

Added unit tests

## WHAT BROKE

CORS issue (fixed)

Memory leak in cleanup (pending)

## WHAT'S NEXT

Deploy to staging

Test with real users

## DECISIONS MADE

Use JWT instead of sessions

Move cache to Redis

TIME: 2h 15m

project-state.md — Updated After Major Work

# Project State

## CURRENT PHASE

Phase 3: API Build (Sessions 8-12)

## COMPLETED

[x] Database schema

[x] Authentication

[x] User CRUD endpoints

[x] Testing framework

## IN PROGRESS

[ ] Payment integration (Stripe)

[ ] Admin dashboard

## BLOCKED

Payment integration: awaiting Stripe API keys

## METRICS

Test coverage: 82%

API endpoints: 24/30 complete

Bugs: 3 open

04	tools.md + context.md

tools.md — References Only

No credential values here. Paths and references only. Scannable at a glance.

# Tools & References

## APIs

Stripe API: docs.stripe.com

Auth0: manage.auth0.com

SendGrid: sendgrid.com/docs

## CREDENTIALS (paths, no values)

Database URL: stored in .env as DB_URL

Stripe key: stored in GitHub Secrets

## LOCAL TOOLS

Redis: localhost:6379

PostgreSQL: localhost:5432

## DEPLOYMENT

Staging: staging.yourapp.com

Production: yourapp.com

context.md — Domain Knowledge

Client info, business logic, terminology Claude needs to do the work correctly.

# Context

## CLIENT / PRODUCT

Company: Acme Corp

Business: B2B SaaS payment platform

Users: Finance teams (5-50 per company)

## TERMINOLOGY

"Ledger" = transaction history

"Reconcile" = match invoices to payments

"Batch" = 1000+ transactions processed at once

## CONSTRAINTS

SOC 2 certified

PCI compliant (payment data)

## EDGE CASES

Invoices over $100K need approval

Refunds take 7-10 days

Bulk exports limited to 10K rows

05	.claude/commands/ + scripts/

.claude/commands/ — Slash Commands

Each .md file in .claude/commands/ becomes a slash command. Invoke them with /project:name. Reusable, consistent, team-shared.

# .claude/commands/voice-agent-setup.md

You are building a voice AI agent for [CLIENT].

REQUIREMENTS

- Understand voice input via spacebar hold

- Process speech to action mapping

- Return structured output

INTEGRATIONS

- Speech API: OpenAI Whisper

- Voice output: ElevenLabs

CONSTRAINTS

- Response time: <2 seconds

- Accuracy: >95%

- Languages: English + Spanish

scripts/ — Automation

Shell scripts Claude can run. Versioned. Consistent across environments.

# build.sh

#!/bin/bash

npm install

npm run lint

npm run test

npm run build

# deploy.sh

#!/bin/bash

git pull origin main

npm install

npm run migrate

npm run build

pm2 restart app

# test.sh

#!/bin/bash

npm run test:unit

npm run test:integration

npm run test:e2e

06	Session Workflow

Session Start

• Claude reads GLOBAL ~/.claude/CLAUDE.md

• Claude reads PROJECT ./CLAUDE.md

• Claude reads session-log.md (what happened last time)

• Claude reads project-state.md (current phase and blockers)

• Claude proceeds with full context

During Session

• Claude references .claude/commands/ for repeated task types

• Claude runs .claude/scripts/ for automated build, deploy, test

• Claude reads .claude/reference/ for deep architectural context

Session End

• Claude auto-updates session-log.md with what happened

• Claude auto-updates project-state.md with current status

• Ready for next session with no manual setup

Maintenance Schedule

Cadence	Task
Weekly	Review project-state.md. Update blockers and current phase.
Monthly	Archive old session-logs. Keep last 20. Clear stale entries.
Quarterly	Review context.md. Update terminology and constraints.
Yearly	Archive completed projects. Keep reference files only.

Example: Recruitment AI Project

~/.claude/projects/recruitment-ai/

├── CLAUDE.md # permanent rules + recruitment principles

├── session-log.md # what we built today

├── project-state.md # phase 3: email system

├── tools.md # Firecrawl, Clay, Apollo refs

├── context.md # client: AI startup, 50 engineers

└── .claude/

├── commands/

│ ├── candidate-screening.md

│ ├── email-copy-generation.md

│ └── mcp-tool-builder.md

├── scripts/

│ ├── scrape-companies.sh

│ ├── train-lm.sh

│ └── deploy-agent.sh

└── reference/

├── email-templates.md

├── candidate-evaluation-rubric.md

└── incident-log.md

@keshavsuki