# CLAUDE.md Structure Reference

## Purpose

CLAUDE.md files provide context and instructions to Claude Code for your project or globally.

## File Locations

| Location | Purpose | Shared? |
|----------|---------|---------|
| `~/.claude/CLAUDE.md` | Global defaults | No |
| `./CLAUDE.md` | Project shared | Yes |
| `./.claude/CLAUDE.md` | Alt project location | Yes |
| `./CLAUDE.local.md` | Local overrides | No |

## Common Sections

### Project Context

```markdown
# Project Name

Brief description of what this project does.

## Architecture

- Technology stack
- Key components
- Dependencies
```

### Coding Standards

```markdown
## Coding Standards

- Language preferences (TypeScript > JavaScript)
- Formatting rules
- Naming conventions
```

### Commands/Workflows

```markdown
## Available Commands

| Command | Description |
|---------|-------------|
| /build | Build the project |
| /test | Run tests |
```

### Environment Setup

```markdown
## Development Setup

1. Install dependencies: `npm install`
2. Set environment variables: see `.env.example`
3. Run dev server: `npm run dev`
```

## Frontmatter (Optional)

CLAUDE.md can have YAML frontmatter:

```yaml
---
model: sonnet
allowed-tools: Read, Write, Bash
---
```

## @Imports

Reference other files:

```markdown
# Main CLAUDE.md

@./docs/architecture.md
@./CONTRIBUTING.md
```

The imported files are loaded and included in context.

## Best Practices

1. **Keep it focused**: Don't repeat generic info
2. **Update regularly**: Keep sync with project changes
3. **Use imports**: Split large files into modules
4. **Be specific**: Give concrete examples, not vague guidelines
5. **Local for secrets**: Use CLAUDE.local.md for sensitive paths

## Size Recommendations

| File | Recommended Size |
|------|------------------|
| Global CLAUDE.md | 1-2 KB |
| Project CLAUDE.md | 2-5 KB |
| With imports | Total 5-10 KB |

Larger files consume more context tokens.