Claude Code Guide — Part 2: The .claude directory

What .claude/ is

CLAUDE.md is the file that loads on every session. .claude/ is the directory next to it that holds everything else Claude Code reads — rules, skills, subagents, hooks, commands, and the settings.json it maintains for you (see the settings reference in the official docs). This part covers two of those surfaces: the rules/ subfolder, and the loading rules for CLAUDE.md itself. Skills, subagents, and hooks each get their own part later in the series. settings.json stays hands-off the same way Part 1 left it — Claude Code edits it as you click through permission prompts.

What goes in the rules folder

.claude/rules/ is a directory of short markdown files Claude Code loads alongside CLAUDE.md. One file per topic. Filenames are descriptive — testing.md, code-style.md, api-design.md. All .md files under the directory are discovered recursively, so you can group related rules into subdirectories if you want.

Two things make rules different from CLAUDE.md content.

First, rules are narrow and focused. CLAUDE.md is the project briefing — what this project is, how you work in it, what to be careful about. A rule is one directive that's too specific to belong in the briefing or too long to live as a single line in it. "Use named exports, never default exports" can sit in CLAUDE.md. A page of testing conventions belongs in .claude/rules/testing.md.

Second, rules can be path-scoped. Add a paths: field in YAML frontmatter and the rule only enters context when Claude reads files matching the pattern:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

A rule with no paths: field loads on every session, the same way CLAUDE.md does. A rule with paths: sits dormant until Claude opens a matching file. That's how you keep instructions out of context until they're relevant.

The full reference lives at docs.claude.com/en/docs/claude-code/memory under "Organize rules with .claude/rules/". The .claude/ directory tour at docs.claude.com/en/docs/claude-code/claude-directory shows how the rules folder sits alongside the rest of .claude/.

How CLAUDE.md actually loads

Part 1 said every session in or below the directory containing CLAUDE.md starts with the file in context. That's the short version. Here's the rest of it.

Parent-directory walk. Claude Code starts in your working directory and walks up the tree, picking up every CLAUDE.md and CLAUDE.local.md it finds along the way. Run from foo/bar/ and you get foo/bar/CLAUDE.md, foo/CLAUDE.md, and any ancestors. They concatenate — none of them overrides the others. CLAUDE.local.md (gitignored, personal) loads after CLAUDE.md at each level, so your local notes are the last word at that scope.

@path imports. A CLAUDE.md line like @docs/git-instructions.md or @README pulls another file into context at session start. Relative paths resolve from the file containing the import, not from the working directory. Imports can recurse five hops deep. Use this to keep the root CLAUDE.md lean — break long sections out into their own files and reference them, so the briefing stays scannable without losing detail.

This project's git workflow: @docs/git-instructions.md
Personal preferences: @~/.claude/my-project-prefs.md

Imports load at session start the same as the rest of CLAUDE.md. They keep the file organized, not smaller in context — every imported line still costs tokens.

User-scope ~/.claude/CLAUDE.md. Drop a CLAUDE.md at ~/.claude/CLAUDE.md and it loads on every session you start, in every project. Use this for things that apply to you across all your projects — tooling preferences, formatting habits, "I prefer pnpm over npm everywhere." Project CLAUDE.md always wins on conflict, but the user-scope file rides along underneath.

The 200-line cap. The official guidance is to target under 200 lines per CLAUDE.md. Longer files still load in full — there's no truncation — but adherence drops as the file grows. If your CLAUDE.md is creeping past 200 lines, that's the signal to either move material into .claude/rules/ (especially anything that can be path-scoped) or into a @path import for organization.

Full memory rules at docs.claude.com/en/docs/claude-code/memory.

Give every artifact a home

Working with Claude Code generates files. Notes from a planning conversation. A PRD draft. A design doc Claude wrote during an interview. Scratch files from an experiment that didn't ship. An archived version of something you replaced. A generated report. Meeting notes Claude transcribed.

Without somewhere to put these, they end up at the repo root. Then they end up everywhere — checked in next to source files, scattered across feature branches, mixed into directories that already had a job. A month in, nobody can find anything and Claude can't either.

The fix is two-part. Pick a home for each kind of artifact, and document those homes in CLAUDE.md so Claude reads them every session. A typical layout:

• notes/ — working notes, feedback logs, follow-up TODOs, scratch thinking. Not rendered, not shipped.
• docs/ — PRDs, design docs, architecture notes that travel with the code.
• archive/ — superseded versions of files you want kept but not active.
• reports/ — generated audit output, reviews, anything Claude produces as a deliverable.

The exact set depends on the project. A small library might only need notes/ and docs/. A larger repo might need separate homes for design docs vs. PRDs vs. meeting transcripts. The point isn't the specific list — it's that every kind of artifact has a documented home, and Claude knows about each one.

Once those homes are written into CLAUDE.md, the next time you ask Claude to "draft a PRD for this feature," it puts the file in docs/ instead of dropping it at the repo root. The next time you ask for working notes, they land in notes/. The convention does the routing.

Set up your rules folder

The first prompt in the sidebar walks you through .claude/rules/ from scratch. Claude explains what the folder is in plain language, suggests one starter rule that's useful in most projects, and lets you edit or swap it before saving. When the first rule lands, Claude asks if you want to add another — and loops until you say you're done. The directory gets created for you if it doesn't exist yet.

Open the prompts panel (right side on desktop, the floating button on mobile), copy Prompt 1, and paste it into your Claude Code session.

Document where things live

The second prompt sets up the conventions side. Claude looks at your project's top-level folders first and tells you what already looks like a deliberate home for one type of artifact — a notes/, a docs/, an archive/. Then it offers examples of common conventions for things you don't have yet (PRDs, design docs, scratch, generated reports, meeting notes) and asks which apply to your project. You pick the ones that fit, decide where each one should live, and choose how the result gets written into CLAUDE.md — as its own section, as a paragraph, or as a list. Claude writes it and shows you what landed; you can adjust if it reads too rigid or too thin.

Copy Prompt 2 from the sidebar when you're ready.

When you're done

You have a .claude/rules/ folder Claude reads alongside CLAUDE.md, and a CLAUDE.md that names where each kind of artifact lives in your repo. Both are plain markdown on disk — open them, edit them, move them. The next time you ask Claude for a PRD or a set of notes, the file lands in the home you picked.

Part 3 covers Skills — reusable procedures Claude Code can apply inline or invoke as a slash command. Skills live in .claude/skills/ next to the rules folder you just set up, and they're the first surface in the series where you'll author a real piece of Claude Code's behavior. Continue at Part 3 — Skills.