project/
├── CLAUDE.md                    # Main project memory (root)
├── .claude/
│   ├── CLAUDE.md               # Alternative for project memory
│   ├── settings.json           # Hooks and configuration
│   ├── settings.local.json     # Local config (don't commit)
│   ├── skills/                 # Custom skills
│   │   └── my-skill/
│   │       └── SKILL.md
│   ├── commands/               # Custom slash commands
│   │   └── my-command.md
│   └── agents/                 # Specialized agents
│       └── my-agent.md
├── .mcp.json                    # MCP servers configuration
└── docs/
    └── architecture/           # Architecture documentation

CLAUDE.md Hierarchy

Files are loaded in this priority order:

~/.claude/CLAUDE.md - Global (applies to all sessions)
./CLAUDE.md - Project root (shared with team)
./.claude/CLAUDE.md - Alternative in .claude folder
./subdirectory/CLAUDE.md - Folder-specific (loaded on demand)

CLAUDE.md Configuration

The CLAUDE.md is the most important file for Claude Code. It's the agent's "constitution".

Recommended Template

# Project Name

## Description
[Brief description of the project and its purpose]

## Tech Stack
- **Frontend**: [React/Vue/Angular/etc.]
- **Backend**: [Node/Python/Go/etc.]
- **Database**: [PostgreSQL/MongoDB/etc.]
- **Infrastructure**: [AWS/GCP/Docker/etc.]

## Main Commands

### Development
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run test` - Run tests
- `npm run lint` - Check code

### Database
- `npm run db:migrate` - Run migrations
- `npm run db:seed` - Seed test data

## Project Structure

src/
├── components/     # Reusable components
├── pages/          # Main pages/views
├── services/       # Business logic and APIs
├── hooks/          # Custom hooks
├── utils/          # Utilities and helpers
├── types/          # Type definitions
└── stores/         # Global state (Zustand/Redux)

## Code Conventions

### Naming
- Components: PascalCase (`UserProfile.tsx`)
- Functions/variables: camelCase (`getUserData`)
- Constants: UPPER_SNAKE_CASE (`API_BASE_URL`)
- Utility files: kebab-case (`date-utils.ts`)

### Style
- Use ES Modules (import/export), NOT CommonJS (require)
- Prefer arrow functions for components
- Destructure props in components
- Use TypeScript strict mode

## Architectural Patterns

### State Management
[Describe how state is managed: Context, Zustand, Redux, etc.]

### Data Fetching
[Describe pattern: React Query, SWR, custom hooks, etc.]

### Error Handling
[Describe error boundaries strategy, try-catch, etc.]

## Testing

### Conventions
- Test files alongside code: `Component.test.tsx`
- Use `describe` to group related tests
- Name tests descriptively: "should render user name when logged in"

### Running Tests
- `npm test` - All tests
- `npm test -- --watch` - Watch mode
- `npm test -- path/to/file` - Specific test

## Important Rules

1. **DO NOT** modify files in `/core` without review
2. **ALWAYS** add tests for new functionality
3. **NEVER** commit credentials or .env files
4. **PREFER** composition over inheritance
5. **AVOID** any in TypeScript - use specific types

## Common Mistakes to Avoid

- Don't use `console.log` in production (use logger)
- Don't fetch directly in components (use hooks/services)
- Don't mutate state directly in React
- Don't ignore TypeScript errors with @ts-ignore

Creating Skills

Skills extend Claude's knowledge with domain-specific information.

Skill Structure

# Skill Name

> Brief one-line description

## Description

Detailed description of the skill's purpose.
Include keywords users would naturally mention.

**Triggers**: keyword1, keyword2, trigger phrase, etc.

---

## Skill Content

[Information, patterns, examples, best practices]

### Good vs Bad Examples

#### Bad
```code
// Code you should NOT write

Good

// Correct code


### Skills Location

.claude/skills/ ├── react-patterns/ │ └── SKILL.md ├── api-design/ │ └── SKILL.md ├── testing-strategies/ │ └── SKILL.md └── database-patterns/ └── SKILL.md


### Best Practices for Skills

1. **Keep focused**: Less than 500 lines per skill
2. **Rich trigger descriptions**: Claude uses semantic matching
3. **Include examples**: Show good and bad code
4. **Be specific**: Avoid generic info Claude already knows
5. **Update frequently**: Reflect project changes

---

## Custom Commands

Commands are prompt templates accessible via `/command-name`.

### Creating a Command

File: `.claude/commands/review-code.md`

```markdown
# Code Review

Perform a thorough code review of $ARGUMENTS considering:

## Review Checklist

### Code Quality
- [ ] Clear and descriptive naming
- [ ] Small functions with single responsibility
- [ ] No duplicated code
- [ ] Appropriate error handling

### Security
- [ ] No injection vulnerabilities
- [ ] Input validation
- [ ] No hardcoded credentials
- [ ] User data sanitization

### Performance
- [ ] No obvious memory leaks
- [ ] Optimized queries
- [ ] Lazy loading where applicable

### Testing
- [ ] Unit tests for business logic
- [ ] Integration tests for critical flows
- [ ] Edge cases covered

## Expected Output

Provide:
1. List of issues found (critical, warnings, suggestions)
2. Corrected code for each critical issue
3. Executive summary of overall quality

Variables in Commands

$ARGUMENTS - Arguments passed to command
$FILE - Current selected file
$SELECTION - Selected text

Recommended Commands

Command	Purpose
`/review`	Review code
`/test`	Generate tests
`/refactor`	Refactor code
`/docs`	Generate documentation
`/debug`	Analyze and debug
`/optimize`	Optimize performance
`/security`	Security audit

Hooks (Automation)

Hooks execute scripts in response to Claude Code events.

Configuration in settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "node .claude/hooks/pre-edit.js"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npm run lint:fix -- $FILE"
      }
    ],
    "UserPromptSubmit": [
      {
        "command": "node .claude/hooks/check-context.js"
      }
    ],
    "Stop": [
      {
        "command": "node .claude/hooks/on-complete.js"
      }
    ]
  }
}

Hook Types

Event	When it runs	Common use
`PreToolUse`	Before tool execution	Validate, block actions
`PostToolUse`	After tool execution	Format, lint, tests
`UserPromptSubmit`	On prompt submit	Enrich context
`Stop`	On task completion	Notifications, cleanup

Example: Protect main branch

// .claude/hooks/pre-edit.js
const { execSync } = require('child_process');

const branch = execSync('git branch --show-current').toString().trim();

if (branch === 'main' || branch === 'master') {
  console.log(JSON.stringify({
    block: true,
    message: 'Cannot edit directly on main branch. Create a branch first.'
  }));
  process.exit(0);
}

console.log(JSON.stringify({ block: false }));

Example: Auto-format after editing

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $FILE && npx eslint --fix $FILE"
      }
    ]
  }
}

MCP Servers

Model Context Protocol connects Claude with external services.

.mcp.json Configuration

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "puppeteer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

Popular MCP Servers

Server	Purpose
`server-github`	GitHub integration (PRs, issues)
`server-postgres`	PostgreSQL queries
`server-puppeteer`	Browser automation
`server-filesystem`	Controlled file access
`server-slack`	Slack integration
`server-notion`	Notion access
`server-linear`	Issue management with Linear

Advanced Workflows

Git Worktrees for Parallel Development

Run multiple Claude sessions simultaneously:

# Create worktrees
git worktree add ../project-feature-auth feature/auth
git worktree add ../project-feature-ui feature/ui
git worktree add ../project-refactor refactor/database

# Each worktree can have its own Claude session
cd ../project-feature-auth && claude
cd ../project-feature-ui && claude

Planning + Review Pattern

Claude A: Writes the implementation plan
Claude B: Reviews the plan as senior engineer (fresh context)
After corrections: "Update your CLAUDE.md so you don't repeat this mistake"

Inspection Checkpoints

Configure points where Claude must stop and show work:

## Required Checkpoints

Before implementing, ALWAYS show:
1. Proposed architecture with diagram
2. Files that will be modified
3. Tests that will be added
4. Potential breaking changes

WAIT for approval before writing code.

Useful Claude Code Commands

Command	Description
`/init`	Generate initial CLAUDE.md based on project
`/help`	View help and available commands
`/clear`	Clear conversation context
`/compact`	Summarize conversation to save context
`/config`	View/modify configuration
`/mcp`	Manage MCP servers
`/permissions`	Manage permissions

Initial Setup Checklist

Run /init to generate base CLAUDE.md
Review and customize CLAUDE.md with team conventions
Create .claude/skills/ folder with relevant skills
Configure frequent commands in .claude/commands/
Configure hooks in settings.json for automation
Add necessary MCP servers in .mcp.json
Document project architecture
Add .claude/settings.local.json to .gitignore
Commit shared configuration to repository

Troubleshooting

Claude doesn't find files

Verify CLAUDE.md has correct structure
Use relative paths from project root

Skills don't activate

Check that triggers in description are relevant
Verify location at .claude/skills/name/SKILL.md

Hooks don't execute

Verify script execution permissions
Check Claude Code logs for errors
Ensure matcher matches the tool

MCP servers don't connect

Verify environment variables
Run command manually to see errors
Check configuration in .mcp.json

Rules

This skill is authoritative for Claude Code configuration only — it does not govern project-level code architecture or language-specific patterns
CLAUDE.md at the user level (~/.claude/CLAUDE.md) applies globally to all sessions; project-level CLAUDE.md overrides or extends it for a specific project
Skills must be directories with a single SKILL.md entry point — never use flat .md files directly in the skills directory
Hooks in settings.json must be idempotent — hooks that fail loudly on every run (e.g., lint errors) will interrupt normal Claude Code operation
MCP server tokens and secrets must be stored as environment variables referenced by ${VAR_NAME} in .mcp.json; never hardcode credentials

claude-code-expert

Claude Code Expert

Patterns

More from fearovex/claude-config

image-ocr

sdd-propose

project-audit

solid-ddd

sdd-design

skill-creator