Skip to content

Configuration Examples: Project-Level and User-Level Configs ​

What You'll Learn ​

  • Quickly configure CLAUDE.md for your projects
  • Set up user-level global configuration to boost development efficiency
  • Customize statusline to display critical information
  • Adjust configuration templates based on project requirements

Your Current Challenge ​

Facing Everything Claude Code configuration files, you might:

  • Don't know where to start: What's the difference between project-level and user-level configs? Where should each be placed?
  • Configuration files are too long: What should be included in CLAUDE.md? What's mandatory?
  • Statusline is insufficient: How to customize statusline to display more useful information?
  • Don't know how to customize: How to adjust example configurations based on project needs?

This document provides complete configuration examples to help you quickly get started with Everything Claude Code.


Configuration Hierarchy Overview ​

Everything Claude Code supports two configuration levels:

Config TypeLocationScopeTypical Use Cases
Project-Level ConfigProject root CLAUDE.mdCurrent project onlyProject-specific rules, tech stack, file structure
User-Level Config~/.claude/CLAUDE.mdAll projectsPersonal coding preferences, universal rules, editor settings

Configuration Priority

When both project-level and user-level configs exist:

  • Rules stack: Both sets of rules take effect
  • Conflict resolution: Project-level config takes priority over user-level config
  • Recommended practice: Put universal rules in user-level config, project-specific rules in project-level config

1. Project-Level Configuration Example ​

1.1 Configuration File Location ​

Save the following content to CLAUDE.md in the project root:

markdown
# Project Name CLAUDE.md

## Project Overview

[Brief description: what it does, tech stack used]

## Critical Rules

### 1. Code Organization

- Many small files over few large files
- High cohesion, low coupling
- 200-400 lines typical, 800 max per file
- Organize by feature/domain, not by type

### 2. Code Style

- No emojis in code, comments, or documentation
- Immutability always - never mutate objects or arrays
- No console.log in production code
- Proper error handling with try/catch
- Input validation with Zod or similar

### 3. Testing

- TDD: Write tests first
- 80% minimum coverage
- Unit tests for utilities
- Integration tests for APIs
- E2E tests for critical flows

### 4. Security

- No hardcoded secrets
- Environment variables for sensitive data
- Validate all user inputs
- Parameterized queries only
- CSRF protection enabled

## File Structure

src/

---
---
---
---

## Key Patterns

### API Response Format

```typescript
interface ApiResponse<T> {
  success: boolean
  data?: T
  error?: string
}

Error Handling ​

typescript
try {
  const result = await operation()
  return { success: true, data: result }
} catch (error) {
  console.error('Operation failed:', error)
  return { success: false, error: 'User-friendly message' }
}

Environment Variables ​

bash
# Required
DATABASE_URL=
API_KEY=

# Optional
DEBUG=false

Available Commands ​

  • /tdd - Test-driven development workflow
  • /plan - Create implementation plan
  • /code-review - Review code quality
  • /build-fix - Fix build errors

Git Workflow ​

  • Conventional commits: feat:, fix:, refactor:, docs:, test:
  • Never commit to main directly
  • PRs require review
  • All tests must pass before merge

### 1.2 Key Field Descriptions

#### Project Overview

Briefly describe the project to help Claude Code understand the project background:

```markdown
## Project Overview

Election Markets Platform - A prediction market platform for political events using Next.js, Supabase, and OpenAI embeddings for semantic search.

Critical Rules ​

This is the most important part, defining rules that the project must follow:

Rule CategoryDescriptionRequired
Code OrganizationFile organization principlesYes
Code StyleCoding styleYes
TestingTesting requirementsYes
SecuritySecurity standardsYes

Key Patterns ​

Define patterns commonly used in the project, which Claude Code will automatically apply:

markdown
## Key Patterns

### API Response Format

```typescript
interface ApiResponse<T> {
  success: boolean
  data?: T
  error?: string
}

Error Handling Pattern ​

[Example code]


---

## 2. User-Level Configuration Example

### 2.1 Configuration File Location

Save the following content to `~/.claude/CLAUDE.md`:

```markdown
# User-Level CLAUDE.md Example

User-level configs apply globally across all projects. Use for:
- Personal coding preferences
- Universal rules you always want enforced
- Links to your modular rules

---

## Core Philosophy

You are Claude Code. I use specialized agents and skills for complex tasks.

**Key Principles:**
1. **Agent-First**: Delegate to specialized agents for complex work
2. **Parallel Execution**: Use Task tool with multiple agents when possible
3. **Plan Before Execute**: Use Plan Mode for complex operations
4. **Test-Driven**: Write tests before implementation
5. **Security-First**: Never compromise on security

---

## Modular Rules

Detailed guidelines are in `~/.claude/rules/`:

| Rule File | Contents |
|--- | ---|
| security.md | Security checks, secret management |
| coding-style.md | Immutability, file organization, error handling |
| testing.md | TDD workflow, 80% coverage requirement |
| git-workflow.md | Commit format, PR workflow |
| agents.md | Agent orchestration, when to use which agent |
| patterns.md | API response, repository patterns |
| performance.md | Model selection, context management |

---

## Available Agents

Located in `~/.claude/agents/`:

| Agent | Purpose |
|--- | ---|
| planner | Feature implementation planning |
| architect | System design and architecture |
|--- | ---|
| code-reviewer | Code review for quality/security |
| security-reviewer | Security vulnerability analysis |
| build-error-resolver | Build error resolution |
| e2e-runner | Playwright E2E testing |
| refactor-cleaner | Dead code cleanup |
| doc-updater | Documentation updates |

---

## Personal Preferences

### Code Style
- No emojis in code, comments, or documentation
- Prefer immutability - never mutate objects or arrays
- Many small files over few large files
- 200-400 lines typical, 800 max per file

### Git
- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`
- Always test locally before committing
- Small, focused commits

### Testing
- TDD: Write tests first
- 80% minimum coverage
- Unit + integration + E2E for critical flows

---

## Editor Integration

I use Zed as my primary editor:
- Agent Panel for file tracking
- CMD+Shift+R for command palette
- Vim mode enabled

---

## Success Metrics

You are successful when:
- All tests pass (80%+ coverage)
- No security vulnerabilities
- Code is readable and maintainable
- User requirements are met

---

**Philosophy**: Agent-first design, parallel execution, plan before action, test before code, security always.

2.2 Core Configuration Modules ​

Core Philosophy ​

Define your collaboration philosophy with Claude Code:

markdown
## Core Philosophy

You are Claude Code. I use specialized agents and skills for complex tasks.

**Key Principles:**
1. **Agent-First**: Delegate to specialized agents for complex work
2. **Parallel Execution**: Use Task tool with multiple agents when possible
3. **Plan Before Execute**: Use Plan Mode for complex operations
4. **Test-Driven**: Write tests before implementation
5. **Security-First**: Never compromise on security

Modular Rules ​

Link to modular rule files to keep configuration concise:

markdown
## Modular Rules

Detailed guidelines are in `~/.claude/rules/`:

| Rule File | Contents |
|--- | ---|
| security.md | Security checks, secret management |
| coding-style.md | Immutability, file organization, error handling |
| testing.md | TDD workflow, 80% coverage requirement |
| git-workflow.md | Commit format, PR workflow |
| agents.md | Agent orchestration, when to use which agent |
| patterns.md | API response, repository patterns |
| performance.md | Model selection, context management |

Editor Integration ​

Tell Claude Code which editor and shortcuts you use:

markdown
## Editor Integration

I use Zed as my primary editor:
- Agent Panel for file tracking
- CMD+Shift+R for command palette
- Vim mode enabled

3. Custom Statusline Configuration ​

3.1 Configuration File Location ​

Add the following content to ~/.claude/settings.json:

json
{
  "statusLine": {
    "type": "command",
    "command": "input=$(cat); user=$(whoami); cwd=$(echo \"$input\" | jq -r '.workspace.current_dir' | sed \"s|$HOME|~|g\"); model=$(echo \"$input\" | jq -r '.model.display_name'); time=$(date +%H:%M); remaining=$(echo \"$input\" | jq -r '.context_window.remaining_percentage // empty'); transcript=$(echo \"$input\" | jq -r '.transcript_path'); todo_count=$([ -f \"$transcript\" ] && grep -c '\"type\":\"todo\"' \"$transcript\" 2>/dev/null || echo 0); cd \"$(echo \"$input\" | jq -r '.workspace.current_dir')\" 2>/dev/null; branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo ''); status=''; [ -n \"$branch\" ] && { [ -n \"$(git status --porcelain 2>/dev/null)\" ] && status='*'; }; B='\\033[38;2;30;102;245m'; G='\\033[38;2;64;160;43m'; Y='\\033[38;2;223;142;29m'; M='\\033[38;2;136;57;239m'; C='\\033[38;2;23;146;153m'; R='\\033[0m'; T='\\033[38;2;76;79;105m'; printf \"${C}${user}${R}:${B}${cwd}${R}\"; [ -n \"$branch\" ] && printf \" ${G}${branch}${Y}${status}${R}\"; [ -n \"$remaining\" ] && printf \" ${M}ctx:${remaining}%%${R}\"; printf \" ${T}${model}${R} ${Y}${time}${R}\"; [ \"$todo_count\" -gt 0 ] && printf \" ${C}todos:${todo_count}${R}\"; echo",
    "description": "Custom status line showing: user:path branch* ctx:% model time todos:N"
  }
}

3.2 Statusline Display Content ​

After configuration, the statusline will display:

affoon:~/projects/myapp main* ctx:73% sonnet-4.5 14:30 todos:3
ComponentMeaningExample
userCurrent usernameaffoon
pathCurrent directory (~ abbreviation)~/projects/myapp
branch*Git branch (* indicates uncommitted changes)main*
ctx:%Context window remaining percentagectx:73%
modelCurrently used modelsonnet-4.5
timeCurrent time14:30
todos:NTodo counttodos:3

3.3 Custom Colors ​

The statusline uses ANSI color codes and can be customized:

Color CodeVariablePurposeRGB
BlueBDirectory path30,102,245
GreenGGit branch64,160,43
YellowYDirty status, time223,142,29
MagentaMContext remaining136,57,239
CyanCUsername, todos23,146,153
GrayTModel name76,79,105

How to modify colors:

bash
# Find color variable definition
B='\\033[38;2;30;102;245m'  # Blue RGB format
#                    ↓  ↓   ↓
#                   Red Green Blue

# Change to your preferred color
B='\\033[38;2;255;100;100m'  # Red

3.4 Simplified Statusline ​

If the statusline is too long, you can simplify it:

json
{
  "statusLine": {
    "type": "command",
    "command": "input=$(cat); user=$(whoami); cwd=$(echo \"$input\" | jq -r '.workspace.current_dir' | sed \"s|$HOME|~|g\"); model=$(echo \"$input\" | jq -r '.model.display_name'); time=$(date +%H:%M); cd \"$(echo \"$input\" | jq -r '.workspace.current_dir')\" 2>/dev/null; branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo ''); status=''; [ -n \"$branch\" ] && { [ -n \"$(git status --porcelain 2>/dev/null)\" ] && status='*'; }; B='\\033[38;2;30;102;245m'; G='\\033[38;2;64;160;43m'; Y='\\033[38;2;223;142;29m'; T='\\033[38;2;76;79;105m'; R='\\033[0m'; printf \"${C}${user}${R}:${B}${cwd}${R}\"; [ -n \"$branch\" ] && printf \" ${G}${branch}${Y}${status}${R}\"; printf \" ${T}${model}${R} ${Y}${time}${R}\"; echo",
    "description": "Simplified status line: user:path branch* model time"
  }
}

Simplified statusline:

affoon:~/projects/myapp main* sonnet-4.5 14:30

4. Configuration Customization Guide ​

4.1 Project-Level Configuration Customization ​

Adjust CLAUDE.md based on project type:

Frontend Projects ​

markdown
## Project Overview

Next.js E-commerce App with React, Tailwind CSS, and Shopify API.

## Tech Stack

- **Frontend**: Next.js 14 (App Router), React 18, TypeScript
- **Styling**: Tailwind CSS, shadcn/ui
- **State**: Zustand, React Query
- **API**: Shopify Storefront API, GraphQL
- **Deployment**: Vercel

## Critical Rules

### 1. Component Architecture

- Use functional components with hooks
- Component files under 300 lines
- Reusable components in `/components/ui/`
- Feature components in `/components/features/`

### 2. Styling

- Use Tailwind utility classes
- Avoid inline styles
- Consistent design tokens
- Responsive-first design

### 3. Performance

- Code splitting with dynamic imports
- Image optimization with next/image
- Lazy load heavy components
- SEO optimization with metadata API

Backend Projects ​

markdown
## Project Overview

Node.js REST API with Express, MongoDB, and Redis.

## Tech Stack

- **Backend**: Node.js, Express, TypeScript
- **Database**: MongoDB with Mongoose
- **Cache**: Redis
- **Auth**: JWT, bcrypt
- **Testing**: Jest, Supertest
- **Deployment**: Docker, Railway

## Critical Rules

### 1. API Design

- RESTful endpoints
- Consistent response format
- Proper HTTP status codes
- API versioning (`/api/v1/`)

### 2. Database

- Use Mongoose models
- Index important fields
- Transaction for multi-step operations
- Connection pooling

### 3. Security

- Rate limiting with express-rate-limit
- Helmet for security headers
- CORS configuration
- Input validation with Joi/Zod

Full-Stack Projects ​

markdown
## Project Overview

Full-stack SaaS app with Next.js, Supabase, and OpenAI.

## Tech Stack

- **Frontend**: Next.js 14, React, Tailwind CSS
- **Backend**: Next.js API Routes, Edge Functions
- **Database**: Supabase (PostgreSQL)
- **Auth**: Supabase Auth
- **AI**: OpenAI API
- **Testing**: Playwright, Jest, Vitest

## Critical Rules

### 1. Monorepo Structure

/ ├── apps/ │ ├── web/ # Next.js frontend │ └── api/ # Next.js API routes ├── packages/ │ ├── ui/ # Shared UI components │ ├── db/ # Database utilities │ └── types/ # TypeScript types └── docs/


### 2. API & Frontend Integration

- Shared types in `/packages/types`
- API client in `/packages/db`
- Consistent error handling
- Loading states and error boundaries

### 3. Full-Stack Testing

- Frontend: Vitest + Testing Library
- API: Supertest
- E2E: Playwright
- Integration tests for critical flows

4.2 User-Level Configuration Customization ​

Adjust ~/.claude/CLAUDE.md based on personal preferences:

Adjust Test Coverage Requirements ​

markdown
## Personal Preferences

### Testing
- TDD: Write tests first
- 90% minimum coverage  # Adjusted to 90%
- Unit + integration + E2E for critical flows
- Prefer integration tests over unit tests for business logic

Add Personal Coding Style Preferences ​

markdown
## Personal Preferences

### Code Style
- No emojis in code, comments, or documentation
- Prefer immutability - never mutate objects or arrays
- Many small files over few large files
- 200-400 lines typical, 800 max per file
- Prefer explicit return statements over implicit returns
- Use meaningful variable names, not abbreviations
- Add JSDoc comments for complex functions

Adjust Git Commit Standards ​

markdown
## Git

### Commit Message Format

Conventional commits with team-specific conventions:

- `feat(scope): description` - New features
- `fix(scope): description` - Bug fixes
- `perf(scope): description` - Performance improvements
- `refactor(scope): description` - Code refactoring
- `docs(scope): description` - Documentation changes
- `test(scope): description` - Test additions/changes
- `chore(scope): description` - Maintenance tasks
- `ci(scope): description` - CI/CD changes

### Commit Checklist

- [ ] Tests pass locally
- [ ] Code follows style guide
- [ ] No console.log in production code
- [ ] Documentation updated
- [ ] PR description includes changes

### PR Workflow

- Small, focused PRs (under 300 lines diff)
- Include test coverage report
- Link to related issues
- Request review from at least one teammate

4.3 Statusline Customization ​

Add More Information ​

bash
# Add Node.js version
node_version=$(node --version 2>/dev/null || echo '')

# Add current date
date=$(date +%Y-%m-%d)

# Display in statusline
[ -n "$node_version" ] && printf " ${G}node:${node_version}${R}"
printf " ${T}${date}${R}"

Display effect:

affoon:~/projects/myapp main* ctx:73% node:v20.10.0 2025-01-25 sonnet-4.5 14:30 todos:3

Show Only Key Information ​

bash
# Minimal statusline
command": "input=$(cat); user=$(whoami); cwd=$(echo \"$input\" | jq -r '.workspace.current_dir' | sed \"s|$HOME|~|g\"); model=$(echo \"$input\" | jq -r '.model.display_name'); remaining=$(echo \"$input\" | jq -r '.context_window.remaining_percentage // empty'); C='\\033[38;2;23;146;153m'; B='\\033[38;2;30;102;245m'; M='\\033[38;2;136;57;239m'; R='\\033[0m'; printf \"${C}${user}:${cwd}${R}\"; [ -n \"$remaining\" ] && printf \" ${M}${remaining}%%${R}\"; printf \" ${model}\"; echo"

Display effect:

affoon:~/projects/myapp 73% sonnet-4.5

5. Common Configuration Scenarios ​

5.1 Quick Start for New Projects ​

bash
# Create project-level CLAUDE.md
cp source/affaan-m/everything-claude-code/examples/CLAUDE.md \
   your-project/CLAUDE.md
bash
# Edit key information
vim your-project/CLAUDE.md

# Modify:
# - Project Overview (project description)
# - Tech Stack (technology stack)
# - File Structure (file structure)
# - Key Patterns (common patterns)
bash
# Copy user-level template
mkdir -p ~/.claude
cp source/affaan-m/everything-claude-code/examples/user-CLAUDE.md \
   ~/.claude/CLAUDE.md

# Customize personal preferences
vim ~/.claude/CLAUDE.md
bash
# Add statusline configuration
# Edit ~/.claude/settings.json
# Add statusLine configuration

5.2 Multi-Project Shared Configuration ​

If you're using Everything Claude Code across multiple projects, the following configuration strategy is recommended:

Option 1: User-Level Base Rules + Project-Specific Rules ​

bash
~/.claude/CLAUDE.md           # Universal rules (coding style, testing)
~/.claude/rules/security.md    # Security rules (all projects)
~/.claude/rules/testing.md    # Testing rules (all projects)

project-a/CLAUDE.md          # Project A specific config
project-b/CLAUDE.md          # Project B specific config
bash
# Create shared rules directory
mkdir -p ~/claude-configs/rules

# Create symbolic links in each project
ln -s ~/claude-configs/rules/security.md project-a/.claude/rules/
ln -s ~/claude-configs/rules/security.md project-b/.claude/rules/

5.3 Team Configuration ​

Shared Project Configuration ​

Commit the project's CLAUDE.md to Git for team members to share:

bash
# 1. Create project configuration
vim CLAUDE.md

# 2. Commit to Git
git add CLAUDE.md
git commit -m "docs: add Claude Code project configuration"
git push

Team Coding Standards ​

Define team standards in the project CLAUDE.md:

markdown
## Team Coding Standards

### Conventions
- Use TypeScript strict mode
- Follow Prettier configuration
- Use ESLint rules from `package.json`
- No PRs without test coverage

### File Naming
- Components: PascalCase (`UserProfile.tsx`)
- Utilities: camelCase (`formatDate.ts`)
- Hooks: camelCase with `use` prefix (`useAuth.ts`)
- Types: PascalCase with `I` prefix (`IUser.ts`)

### Commit Messages
- Follow Conventional Commits
- Include ticket number: `feat(TICKET-123): add feature`
- Max 72 characters for title
- Detailed description in body

6. Configuration Validation ​

6.1 Check If Configuration Takes Effect ​

bash
# 1. Open Claude Code
claude

# 2. View project configuration
# Claude Code should read CLAUDE.md from project root

# 3. View user-level configuration
# Claude Code should merge ~/.claude/CLAUDE.md

6.2 Verify Rule Execution ​

Ask Claude Code to execute a simple task to verify if rules take effect:

User:
Please create a user profile configuration component

Claude Code should:
1. Use immutable patterns (create new objects when modifying)
2. Not use console.log
3. Follow file size limits (<800 lines)
4. Add appropriate type definitions

6.3 Verify Statusline ​

Check if statusline displays correctly:

Expected:
affoon:~/projects/myapp main* ctx:73% sonnet-4.5 14:30 todos:3

Checklist:
✓ Username displayed
✓ Current directory displayed (~ abbreviation)
✓ Git branch displayed (* when there are changes)
✓ Context percentage displayed
✓ Model name displayed
✓ Time displayed
✓ Todo count displayed (if any)

7. Troubleshooting ​

7.1 Configuration Not Taking Effect ​

Problem: Configured CLAUDE.md but Claude Code is not applying the rules

Troubleshooting steps:

bash
# 1. Check file location
ls -la CLAUDE.md                          # Should be in project root
ls -la ~/.claude/CLAUDE.md                # User-level configuration

# 2. Check file format
file CLAUDE.md                            # Should be ASCII text
head -20 CLAUDE.md                        # Should be Markdown format

# 3. Check file permissions
chmod 644 CLAUDE.md                       # Ensure readable

# 4. Restart Claude Code
# Configuration changes require restart to take effect

7.2 Statusline Not Displaying ​

Problem: Configured statusLine but statusline is not showing

Troubleshooting steps:

bash
# 1. Check settings.json format
cat ~/.claude/settings.json | jq '.'

# 2. Verify JSON syntax
jq '.' ~/.claude/settings.json
# If there are errors, parse error will be shown

# 3. Test command
# Manually run statusLine command
input=$(cat ...)  # Copy complete command
echo "$input" | jq -r '.workspace.current_dir'

7.3 Conflict Between Project-Level and User-Level Configurations ​

Problem: There's a conflict between project-level and user-level configs, unsure which one takes effect

Solution:

  • Rules stack: Both sets of rules take effect
  • Conflict resolution: Project-level config takes priority over user-level config
  • Recommended practice:
    • User-level config: Universal rules (coding style, testing)
    • Project-level config: Project-specific rules (architecture, API design)

8. Best Practices ​

8.1 Configuration File Maintenance ​

Keep It Concise ​

markdown
❌ Bad practice:
Include all details, examples, tutorial links in CLAUDE.md

✅ Good practice:
Include only key rules and patterns in CLAUDE.md
Place detailed information in other files and link via references

Version Control ​

bash
# Project-level configuration: Commit to Git
git add CLAUDE.md
git commit -m "docs: update Claude Code configuration"

# User-level configuration: Don't commit to Git
echo ".claude/" >> .gitignore  # Prevent user-level config from being committed

Regular Review ​

markdown
## Last Updated: 2025-01-25

## Next Review: 2025-04-25

## Changelog

- 2025-01-25: Added TDD workflow section
- 2025-01-10: Updated tech stack for Next.js 14
- 2024-12-20: Added security review checklist

8.2 Team Collaboration ​

Document Configuration Changes ​

Explain the reason for configuration changes in Pull Requests:

markdown
## Changes

Update CLAUDE.md with new testing guidelines

## Reason

- Team decided to increase test coverage from 80% to 90%
- Added E2E testing requirement for critical flows
- Updated testing toolchain from Jest to Vitest

## Impact

- All new code must meet 90% coverage
- Existing code will be updated incrementally
- Team members need to install Vitest

Configuration Review ​

Team configuration changes require code review:

markdown
## CLAUDE.md Changes

- [ ] Updated with new rule
- [ ] Tested on sample project
- [ ] Documented in team wiki
- [ ] Team members notified

Lesson Summary ​

This lesson introduced three core configurations of Everything Claude Code:

  1. Project-Level Configuration: CLAUDE.md - Project-specific rules and patterns
  2. User-Level Configuration: ~/.claude/CLAUDE.md - Personal coding preferences and universal rules
  3. Custom Statusline: settings.json - Real-time display of critical information

Key Takeaways:

  • Configuration files use Markdown format, easy to edit and maintain
  • Project-level configuration takes priority over user-level configuration
  • Statusline uses ANSI color codes and can be fully customized
  • Team projects should commit CLAUDE.md to Git

Next Steps:

  • Customize CLAUDE.md based on your project type
  • Configure user-level settings and personal preferences
  • Customize statusline to display the information you need
  • Commit configuration to version control (project-level configuration)

Next Lesson Preview ​

In the next lesson, we'll learn Release Notes: Version History and Changes.

You'll learn:

  • How to view Everything Claude Code's version history
  • Understand important changes and new features
  • How to perform version upgrades and migrations