ktg-plugin-marketplace/plugins/config-audit/skills/config-hierarchy/references/claude-md-structure.md

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

# Project Name

Brief description of what this project does.

## Architecture

- Technology stack
- Key components
- Dependencies

Coding Standards

## Coding Standards

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

Commands/Workflows

## Available Commands

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

Environment Setup

## 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:

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

@Imports

Reference other files:

# 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.