# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Vibes monorepo using vertical slice architecture, designed to build multiple types of applications while keeping the structure simple and maintainable.

## Key Specifications

1. **Architecture**: Vertical slice architecture - features contain all layers (UI, API, logic, data)
2. **Build System**: pnpm workspaces
3. **Development Practices**: Feature-first development with clear boundaries

## Project Structure

```
├── apps/               # Application entry points (web, api, mobile)
├── features/           # Vertical feature slices
├── shared/            # Shared utilities and components
├── tools/             # Build and development tools
├── ai-docs/           # AI-related documentation
└── docs/              # General documentation
```

## Common Commands

```bash
# Feature development
./vibe create <feature>  # Create a new feature
./vibe add <app>        # Add a new app

# Development
pnpm dev               # Start all apps in development mode
pnpm build             # Build all packages
pnpm test              # Run tests
pnpm typecheck         # Type checking

# Or use the vibe command for everything
./vibe dev
./vibe build
./vibe test
```

## Development Workflow

1. **Creating Features**: Use `./vibe create [feature-name]`
2. **Adding Apps**: Use `./vibe add [app-type]`
3. **Shared Code**: Only truly generic code goes in `shared/`

## Architecture Principles

1. Features are self-contained vertical slices
2. Minimal cross-feature dependencies
3. Simple structure that's easy to understand
4. Framework-agnostic features where possible
5. Clear separation of concerns within each feature

## AI Assistant Integration

When working with this codebase using AI tools (Claude, Cursor, Copilot, etc.), the project is designed to be AI-friendly:

### AI Navigation
- **Quick Reference**: Check `/ai-docs/navigation.md` for common AI commands
- **Patterns Guide**: See `/ai-docs/patterns.md` for code patterns
- **Project Config**: `.ai/config.json` contains project metadata
- **Feature Map**: `/ai-docs/feature-map.json` shows feature structure

### AI-Friendly Features
1. **Structured Comments**: Look for `AI-` prefixed comments for navigation hints
2. **Feature Metadata**: Each feature has `.ai-metadata.json` 
3. **Pattern Recognition**: Consistent structure across all features
4. **Clear Exports**: Barrel exports make dependencies obvious

### Common AI Tasks
- "Create a new feature" → Run `./tools/create-feature.sh`
- "Find authentication code" → Check `features/user-auth/`
- "Add API endpoint" → Look in `features/*/api/routes/`
- "Create UI component" → Add to `features/*/ui/components/`

### Best Practices for AI Development
1. Follow the vertical slice pattern - keep related code together
2. Use TypeScript interfaces for clear contracts
3. Export everything through index.ts files
4. Add AI-friendly comments for complex logic
5. Check existing patterns before creating new code