Advanced Claude.md

Reference Sheet

Claude Project Folder Setup Walkthrough

The .claude/rules/ directory allows you to organize project instructions into multiple focused rule files instead of one large CLAUDE.md. All markdown files in the directory are automatically loaded into Claude Code's context when launched. The killer feature: rules can be targeted to specific file patterns using YAML frontmatter. A rule with paths: src/api/**/*.ts only activates when Claude works on files matching that pattern. Your API guidelines stay out of the way when you're editing React components.

Recommended Project Structure

.claude/
├── settings.json
├── settings.local.json
├── CLAUDE.md
├── agents/
├── skills/
│   └── design-review/
│       └── SKILL.md
├── rules/
│   ├── code-style.md
│   └── frontend/react.md
└── .mcp.json

Project root
└── CLAUDE.local.md
Current Claude Code docs support both project and user scopes. Team-shared files typically live in the repository, while your private overrides live in local files that should stay out of source control.

Step-by-Step Setup

  1. Create the project folders: 
    mkdir -p .claude/agents
mkdir -p .claude/skills/design-review
mkdir -p .claude/rules/frontend
  2. Create the main instruction files: 
    touch .claude/CLAUDE.md
touch CLAUDE.local.md
touch .claude/settings.json
touch .claude/settings.local.json
touch .claude/.mcp.json
touch .claude/rules/code-style.md
touch .claude/rules/frontend/react.md
touch .claude/skills/design-review/SKILL.md
  3. Add your local-only files to git ignore: 
    echo "CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore
  4. Start Claude Code from the project root: 
    claude
  5. Check what Claude loaded: 
    /memory
/skills
/agents
/hooks
/mcp
/permissions

What Each Item Is Used For

.claude/CLAUDE.md

Shared project instructions

Use this for team-wide instructions Claude should load for the project, such as architecture notes, commands, naming conventions, workflow rules, and coding standards.

# Example
- Run npm run lint before finalizing edits
- Use Tailwind utilities before writing custom CSS
- Keep components under 200 lines when practical
CLAUDE.local.md

Your private project notes

Use this for personal reminders and preferences for this repository only. Keep it out of git.

# Example
- Prefer concise diffs first
- Ask before touching deployment files
- I usually review UI work in Chrome
.claude/settings.json

Shared permissions and behavior

Use this JSON file for project-wide settings such as permissions, hooks, environment variables, model defaults, and related Claude Code behavior.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}
.claude/settings.local.json

Your local overrides

Use this for local experimentation or personal settings that should not be committed.

{
  "permissions": {
    "allow": [
      "Bash(pnpm dev)"
    ]
  }
}
.claude/agents/

Custom subagents

Put custom subagent definitions here when you want specialized helpers for recurring side tasks such as code review, research, or debugging in their own context window.

---
name: code-reviewer
description: Review diffs for bugs, readability, and risky changes
tools: Read, Grep, Glob
---

Review code changes and return concise findings.
.claude/skills/

Reusable slash-command workflows

Use skills for multi-step playbooks you want Claude to reuse. Each skill lives in its own folder and must contain a SKILL.md file.

---
name: design-review
description: Review a web page screenshot and propose visual refinements
---

1. Review spacing, hierarchy, alignment, and contrast
2. Identify the top visual issues
3. Propose focused CSS and HTML refinements
.claude/rules/

Modular instruction files

Use rules when your instructions are too large for one CLAUDE.md file or only apply to certain paths, stacks, or parts of the codebase.

# code-style.md
- Use descriptive variable names
- Keep functions small and single-purpose

# frontend/react.md
- Prefer functional components
- Keep prop interfaces explicit
.claude/.mcp.json

Project MCP servers

Use project MCP config when the team wants Claude connected to shared tools or data sources for this repository.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

Important Mapping Notes

Skills vs commands

Older examples often show a commands folder for custom slash commands. Current Claude Code docs say custom commands have been merged into skills. If you are starting fresh, use the skills folder pattern unless you specifically need legacy compatibility.

Hooks live in settings

Hooks are configured through settings JSON, not as separate standalone files in the project tree. Use the /hooks command to inspect them, but edit the JSON to create or change them.

Project vs local scope

Keep team-shared standards in project files. Keep your personal overrides in local files such as CLAUDE.local.md and settings.local.json.

Simple Starter Content

Starter .claude/CLAUDE.md
# Project instructions

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Lint: pnpm lint
- Test: pnpm test

## Standards
- Keep UI components clean and readable
- Preserve the existing design system
- Prefer minimal, production-ready diffs
Starter design-review skill
---
name: design-review
description: Review a page and propose polished UI updates
---

Review the current page for:
- spacing
- hierarchy
- typography
- contrast
- alignment
- CTA clarity

Return:
1. visual assessment
2. issues found
3. recommended improvements
4. updated code
Claude project folder setup walkthrough