dot-folder-architecture

name

dot-folder-architecture

description

Set up, scaffold, or audit a .claude/ folder structure for any project using Claude Code. Use this skill whenever a user wants to initialise a new Claude Code project, add structure to an existing one, or asks how to organise their Claude instructions, agents, rules, context, schemas, or memory. Also triggers when a user says their Claude Code setup feels brittle, inconsistent across sessions, or impossible to hand off to another operator. The skill produces a ready-to-commit folder layout with starter files for every subdirectory.

.claude/ Folder Architecture

A structured, git-committed workspace that separates what Claude knows, how Claude behaves, and where a workflow is right now — so Claude Code produces consistent, auditable, handoff-ready results across sessions, operators, and projects.

---

The Core Principle

Most Claude Code setups fail at scale because everything lives in one file. Instructions, domain knowledge, session state, agent definitions — all piled into a growing CLAUDE.md that Claude re-interprets differently every session.

The fix is separation of concerns across three questions:

Question	Folder(s)
How should Claude behave?	rules/
What should Claude know?	context/, schemas/
Where is the workflow right now?	memory/

Everything else (commands/, agents/, skills/, protocols/) layers on top of this foundation.

---

Folder Layout

your-project/
├── CLAUDE.md                  ← entry point (committed)
├── CLAUDE.local.md            ← personal overrides (gitignored)
└── .claude/
    ├── STRUCTURE.md           ← what each folder is for
    ├── settings.json          ← shared permissions (committed)
    ├── settings.local.json    ← personal permissions (gitignored)
    ├── settings.env.json      ← env-aware config (committed)
    ├── commands/              ← human-triggered slash commands
    ├── agents/                ← subagent persona definitions
    ├── rules/                 ← behavioural instructions
    ├── context/               ← persistent domain knowledge
    ├── schemas/               ← output shape definitions
    ├── skills/                ← auto-invoked workflows
    ├── protocols/             ← agent-to-agent contracts
    └── memory/                ← runtime state (gitignored)

---

Step-by-Step Setup

Step 1 — Create the folder structure

mkdir -p .claude/{commands,agents,rules,context,schemas,skills,protocols,memory}
touch CLAUDE.md CLAUDE.local.md
touch .claude/STRUCTURE.md
touch .claude/settings.json .claude/settings.local.json .claude/settings.env.json

Step 2 — Write CLAUDE.md

CLAUDE.md is the first file Claude Code reads. Keep it short. It should contain: project purpose, stack, and pointers to the relevant .claude/ subfolders for the task at hand.

# [Project Name]

## What this project is
[One paragraph — purpose, stack, primary language.]

## Key conventions
- Rules: .claude/rules/
- Domain knowledge: .claude/context/
- Output specs: .claude/schemas/
- Slash commands: .claude/commands/
- Memory (current state): .claude/memory/state.json

## Read first for [task type]
- Code tasks: .claude/rules/code-style.md
- Content tasks: .claude/rules/brand-voice.md + .claude/context/
- Deployments: .claude/commands/deploy.md

Step 3 — Populate settings.json

Define which tools Claude Code can use and which paths it can write to.

{
  "tools": {
    "bash": true,
    "file_write": true,
    "allowed_write_paths": ["src/", "docs/", ".claude/memory/"]
  },
  "safety": {
    "require_confirmation_before_deploy": true,
    "protected_paths": [".env", "secrets/"]
  }
}

Step 4 — Populate settings.env.json

Prevents agents from publishing, deploying, or notifying in the wrong environment.

{
  "dev":     { "publish": false, "notify": false, "log_level": "verbose" },
  "staging": { "publish": false, "notify": true,  "log_level": "standard" },
  "prod":    { "publish": true,  "notify": true,  "log_level": "minimal" }
}

Step 5 — Add .gitignore entries

.claude/settings.local.json
.claude/memory/
CLAUDE.local.md

---

What Goes in Each Folder

rules/ — How Claude behaves

Modular behavioural instructions. Slow-changing. Committed to git.

rules/
├── code-style.md          ← formatting, naming, test coverage
├── brand-voice.md         ← tone, vocabulary, banned phrases
├── api-conventions.md     ← endpoint patterns, error handling
└── funnel-map.md          ← CTA rules, stage logic (content projects)

What belongs here: anything that tells Claude how to act regardless of what task it's doing.

What does not belong here: facts about your business or domain (that's context/), output shapes (that's schemas/), or anything that changes per-run (that's memory/).

---

context/ — What Claude knows

Persistent project knowledge. Domain grounding, not behavioural instruction. Updated when the project's domain evolves.

context/
├── brand-voice.md         ← if brand tone is complex enough
├── topics.md              ← content taxonomy, topic hierarchy
├── sources.md             ← approved sources, trust tiers
└── audience.md            ← who we're building for

What belongs here: anything Claude needs to know to do good work — not how to behave, but what the world of this project looks like.

---

schemas/ — What Claude must produce

Output shape definitions. The contract between an agent and whatever consumes its output. Machine-readable where possible.

schemas/
├── brief-format.md        ← human-readable spec
├── newsletter-item.json   ← structured output shape
├── research-summary.json  ← agent output format
└── task-handoff.json      ← inter-agent payload shape

Rule: any agent that produces structured output must reference a schema in its definition. Never let output shape be implicit.

---

commands/ — Human-triggered actions

Each .md file becomes a /project:filename slash command in Claude Code. Use for actions that should only run when a person explicitly asks.

commands/
├── review.md              → /project:review
├── fix-issue.md           → /project:fix-issue
└── deploy.md              → /project:deploy

Each file should state: purpose, required inputs, expected output, and preconditions.

---

agents/ — Subagent personas

Isolated agents with their own role, instructions, and boundaries. Agents do not share state unless explicitly passed via protocols/.

agents/
├── code-reviewer.md
├── security-auditor.md
└── research-agent.md

Each agent file must declare:

• Role — what it is responsible for
• Scope — what it can and cannot do
• Input — what it expects to receive
• Output — what it must produce (reference a schema)
• Trigger — when it auto-activates (if applicable)

---

skills/ — Auto-invoked workflows

Claude Code triggers these automatically when conditions are met. Each skill is a folder containing a SKILL.md.

skills/
├── index.md               ← trigger map: condition → skill
├── security-review/
│   └── SKILL.md
└── deploy/
    └── SKILL.md

skills/index.md must exist and must explicitly map conditions to skills — triggering logic should never be implicit.

| Condition                        | Skill             |
|----------------------------------|-------------------|
| Any file in /auth modified       | security-review   |
| PR targeting main branch         | security-review   |
| deploy.md command invoked        | deploy            |

---

protocols/ — Agent-to-agent contracts

How agents hand off work to each other. Essential for multi-agent orchestration.

protocols/
├── handoff-format.json    ← source-of-truth payload shape
└── input-output-spec.md   ← prose explanation for anyone writing agents

---

memory/ — Runtime state only

The only folder that changes between runs. Gitignored. Contains whatever agents need to resume a workflow or avoid repeating completed steps.

memory/
├── state.json             ← current pipeline state, updated per run
└── run-log.md             ← append-only log of completed actions

Rules:

• Keep files small and structured
• state.json must be readable in isolation — an agent should know exactly where a workflow left off from this file alone
• Never put instructions or knowledge here — those belong in rules/ or context/

---

Audit Checklist

Use this when reviewing an existing .claude/ setup:

□ CLAUDE.md is short and points to subfolders — not a dump of all instructions
□ rules/ contains only behavioural instructions (not domain facts)
□ context/ contains only domain knowledge (not how-to instructions)
□ memory/ is in .gitignore
□ settings.local.json is in .gitignore
□ Every agent in agents/ references a schema in schemas/
□ skills/index.md exists and lists all trigger conditions explicitly
□ state.json in memory/ is readable standalone (not dependent on context)
□ No instruction, rule, or fact is duplicated across multiple files

---

Folder Purpose at a Glance

Folder	Answers the question	Changes how often
rules/	How should Claude behave?	Rarely
context/	What should Claude know?	Occasionally
schemas/	What must Claude produce?	Occasionally
commands/	What can a human trigger?	Rarely
agents/	Who does what autonomously?	Occasionally
skills/	What triggers automatically?	Rarely
protocols/	How do agents talk to each other?	Rarely
memory/	Where is the workflow right now?	Every run

---

.gitignore Reference

# Claude Code — personal and runtime files
.claude/settings.local.json
.claude/memory/
CLAUDE.local.md

---

Built by Yuri Vonchitzki — used across Ninjabot client builds. Part of the CALMER framework for calm, deliberate AI adoption.