Awesome CLAUDE.md

A curated collection of CLAUDE.md examples, templates, and best practices for Claude Code.

CLAUDE.md is your secret weapon for customizing Claude Code's behavior. This repo helps you get the most out of it.

Contents

• What is CLAUDE.md?
• Quick Start
• Templates
• Best Practices
• Advanced Techniques
• Examples
• Tips & Tricks
• Contributing

What is CLAUDE.md?

CLAUDE.md is a special markdown file that Claude Code reads to understand your preferences, project context, and working style. It acts like a persistent system prompt that shapes how Claude assists you.

File Locations

Location	Scope	Use Case
~/.claude/CLAUDE.md	Global	Personal preferences across all projects
./CLAUDE.md	Project	Project-specific instructions
~/.claude/knowledge-base/CLAUDE.md	Knowledge base	Domain-specific context

Project-level files override global settings when both exist.

Quick Start

Create a minimal CLAUDE.md in your project:

# Project: My App

## Tech Stack
- TypeScript, React, Node.js
- PostgreSQL, Prisma ORM
- Jest for testing

## Code Style
- Use functional components with hooks
- Prefer named exports
- Write tests for all new features

## Commands
- `npm run dev` - Start dev server
- `npm test` - Run tests

That's it! Claude Code will now understand your project context.

Templates

🤖 AI Assistant / Secretary

Personal assistant configuration with task management, calendar integration, and communication preferences.

💻 Software Developer

Development-focused setup with coding standards, git workflow, and review guidelines.

🔬 Researcher

Academic/research configuration with paper management, citation preferences, and experiment tracking.

🚀 Startup / Small Team

Fast-paced environment setup with rapid prototyping preferences and deployment workflows.

📝 Writer / Content Creator

Writing-focused setup with style guides, tone preferences, and content workflows.

🎭 Multi-Persona

Switch between different AI personalities based on context (tmux session, git branch, etc.)

Best Practices

1. Be Specific About Preferences

❌ Bad:

Write good code.

✅ Good:

## Code Style
- Max line length: 100 characters
- Use early returns to reduce nesting
- Prefer composition over inheritance
- Always handle errors explicitly

2. Define Your Boundaries

Tell Claude what NOT to do:

## Don't
- Don't create new files unless explicitly asked
- Don't refactor unrelated code
- Don't add dependencies without asking
- Don't use emojis in code comments

3. Set Communication Style

## Communication
- Be concise - bullet points over paragraphs
- Skip the preamble - get to the point
- Don't ask for confirmation on routine tasks
- Challenge my assumptions when I'm wrong

4. Provide Context, Not Instructions

❌ Micromanaging:

When I ask you to write a function, first think about the inputs,
then think about the outputs, then write the code...

✅ Context-setting:

## Philosophy
We value readability over cleverness. Code is read 10x more than written.

5. Use Structured Sections

Organize with clear headers:

## Project Overview
## Tech Stack
## Code Style
## Git Workflow
## Testing Requirements
## Deployment
## Don't

Advanced Techniques

Dynamic Personas via tmux

Switch Claude's personality based on your tmux session:

## Persona Detection

Check tmux session name at conversation start:
- `secretary` → Professional assistant (formal)
- `dev` → Coding buddy (casual, technical)
- `research` → Academic assistant (precise, citation-focused)

See full persona template for implementation.

Project-Specific Overrides

## When working on /api/*
- Always validate input with Zod
- Return consistent error shapes
- Log all database queries in dev

## When working on /components/*
- Use CSS modules, not inline styles
- Every component needs a Storybook story
- Props must have TypeScript interfaces

Integration with Tools

## MCP Servers
- filesystem: For file operations
- github: For PR and issue management
- slack: For notifications

## Slash Commands
- /deploy - Deploy to staging
- /test - Run test suite
- /review - Start code review

Memory Management

## Memory
Store learned preferences in `CLAUDE-memory.md`:
- Communication preferences
- Past decisions and their rationale
- Project-specific terminology

Don't modify CLAUDE.md directly - use the memory file.

Examples

Real-world CLAUDE.md files:

• Minimal Starter - Just the essentials
• Full-Featured - Comprehensive setup
• Monorepo - Multi-package repository
• Open Source Maintainer - OSS project management

Tips & Tricks

🎯 Start Small

Don't write a 500-line CLAUDE.md on day one. Start with basics, add as you discover needs.

🔄 Iterate

Your CLAUDE.md should evolve. Review monthly and remove what's not working.

📊 Use Tables

Tables are scannable and prevent ambiguity:

| Priority | Response Time |
|----------|---------------|
| 🔴 High | Immediately |
| 🟡 Medium | Within the day |
| 🟢 Low | When convenient |

🚫 Avoid Conflicts

Don't give contradictory instructions:

# Conflicting (bad)
- Always write comprehensive tests
- Move fast, tests can come later

🧪 Test Your Config

After major changes, try common tasks and see if Claude behaves as expected.

💡 Use Examples

Instead of abstract rules, show examples:

## Commit Messages

Good:
- `fix(auth): handle expired token refresh`
- `feat(api): add pagination to /users endpoint`

Bad:
- `fixed stuff`
- `WIP`

Contributing

Contributions welcome! Please read the contribution guidelines first.

• 🐛 Found an issue? Open an issue
• 💡 Have a template to share? Submit a PR
• ⭐ Like this repo? Give it a star!

License

MIT - feel free to use these templates in your projects.

---

Like this repo? Follow me for more Claude Code tips!