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

# 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

# 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

// Correct code

### Skills Location

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

{
  "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"
      }
    ]
  }
}

// .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 }));

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

{
  "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}"
      }
    }
  }
}

# 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

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