# Claude Code Setup

Claude Code is an AI coding assistant that runs in your terminal or VSCode. This guide helps you get it configured for working on the Suno codebase.

## What is Claude Code?

Claude Code is Anthropic's official CLI and VSCode extension that provides an AI-powered coding assistant. It can:

- Read and understand your codebase
- Write and edit code files
- Run terminal commands
- Search through files
- Help debug issues
- Generate documentation

## Installation

### VSCode Extension (Recommended)

1. Open VSCode
2. Go to Extensions (Cmd+Shift+X)
3. Search for "Claude Code"
4. Click "Install"
5. Sign in with your Anthropic account

### CLI Installation

```bash
brew install anthropics/tap/claude-code
```

## Configuration

### Global Configuration

Create `~/.claude/CLAUDE.md` for global instructions that apply to all projects:

```markdown
# Global Claude Code Configuration

## Python Conventions
- Always use fully named parameters when calling functions
- Be explicit with multiline string concatenation (use +)
- Follow PEP 8 style guidelines

## Code Quality
- Run linters only on appropriate file types
- Add type hints where helpful
- Write clear docstrings for public functions

## File Operations
- Check for file existence before operations
- Use pathlib for cross-platform path handling
```

### Project-Specific Configuration

The Suno codebase already has project-specific configuration:

**File**: `.claude/CLAUDE.md` (in the project root)

Key configurations already set up:
- Python coding conventions
- Wiki management rules
- Project-specific patterns

import { Callout } from 'nextra/components'

<Callout type="info">
  **Note**: CLAUDE.md files in subdirectories (outside the primary directory where Claude is running) can be inconsistent. Claude may not always read them. Keep important project-wide instructions in the root `.claude/CLAUDE.md` file.
</Callout>

## Suno Wiki Integration

Claude Code is configured to work with the Suno Wiki:

### Reading the Wiki

Claude can automatically reference wiki pages when you ask questions:

```
You: "How do I deploy a Modal worker?"
Claude: [Reads /suno_wiki/src/content/backend/modal/deployment.mdx]
```

### Updating the Wiki

Claude will proactively ask if you want to document:

- New features or systems built during the session
- Problems solved
- Architecture decisions
- Configuration changes
- Infrastructure updates

**Important**: Claude won't automatically update the wiki - it will always ask first.

## Best Practices

### Starting a Session

When you start working on a task:

1. **Provide context**: "I'm working on music generation in studio_api"
2. **Be specific**: "Help me understand how the Chirp V4 worker processes audio"
3. **Reference files**: "Look at studio_api/bots/generate/api.py"

### Asking Questions

**Good questions**:
- "How does the music generation flow work end-to-end?"
- "Where are errors from the client handled?"
- "What's the difference between Redis and Valkey in our stack?"

**Less effective**:
- "Tell me about the code"
- "What does this do?" (without context)

### Code Generation

When asking Claude to write code:

**Be specific**:
```
"Add a new API endpoint in studio_api that returns a user's top 10 clips by play count"
```

**Provide constraints**:
```
"Add pagination support using Django Ninja's pagination utilities.
Use TanStack Query on the frontend."
```

### File Navigation

Claude can navigate the codebase efficiently:

```
You: "Find all Modal workers that use H100 GPUs"
Claude: [Searches suno_utils/worker/ for GPU configurations]
```

```
You: "Where do we handle Stripe webhooks?"
Claude: [Searches for stripe webhook handlers]
```

## Common Workflows

### Understanding Existing Code

```
You: "Explain how video generation works"
Claude:
1. Reads studio_api/video_generation/video_gen.py
2. Reads relevant Modal workers
3. Explains the flow with code references
```

### Debugging Issues

```
You: "Users are reporting slow generation times"
Claude:
1. Checks Modal worker configurations
2. Reviews queue depths in Redis
3. Examines Datadog metrics (if provided)
4. Suggests optimizations
```

### Adding Features

```
You: "Add a new field to track clip genre"
Claude:
1. Updates Django model
2. Creates migration
3. Updates API serializer
4. Updates frontend types
5. Asks if you want to update the wiki
```

### Documentation

```
You: "Document the DynamoDB item-info table structure"
Claude:
1. Reads dynamodb/item_info_handler.py
2. Analyzes item types and fields
3. Creates wiki page with examples
4. Asks for your approval before writing
```

## Features Specific to Suno

### Context Awareness

Claude knows about:
- **Modal**: Understands Modal deployment patterns
- **Django**: Knows Django patterns and conventions
- **PostgreSQL, Redis, DynamoDB**: Understands our multi-datastore architecture
- **Next.js**: Knows our frontend patterns

### Wiki Management

Claude follows these rules:

1. **Reference First**: Checks wiki before asking clarifying questions
2. **Proactive Updates**: Suggests adding/updating wiki content
3. **Requires Consent**: Never updates wiki without explicit permission
4. **Living Document**: Encourages keeping wiki up-to-date

### Code Conventions

Claude follows Suno conventions:

**Python**:
- Uses fully named parameters: `function(param_name=value)`
- Explicit string concatenation: `"string" + " another"`
- Django ORM best practices
- Type hints where appropriate

**TypeScript/React**:
- TanStack Query for server state
- Tailwind for styling (preferred)
- Type-safe API client usage

## Tips & Tricks

### Speed Up Responses

**Use specific file paths**:
```
"Look at studio_api/bots/models.py lines 100-150"
```

**Narrow the scope**:
```
"Search for 'generate_music' in suno_utils/worker/"
```

### Batch Operations

**Request multiple changes at once**:
```
"Add BPM filtering to the search API:
1. Update the search schema
2. Add Elasticsearch query filter
3. Update frontend search component
4. Add tests"
```

### Learning the Codebase

**Ask architectural questions**:
```
"What's the data flow for a music generation request?"
"Why do we use DynamoDB for audio features instead of PostgreSQL?"
"How does Modal integrate with our Django backend?"
```
## Getting Help

### Claude Code Issues

- Check [docs.claude.com](https://docs.claude.com/claude-code)
- Report issues at [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)
- Ask in #eng-help Slack channel

### Improving Responses

If Claude isn't being helpful:

1. **Provide more context**: "I'm trying to optimize Modal workers"
2. **Be more specific**: "Look at modal_runner_chirp_v4_engine.py line 150"
3. **Show examples**: "Like how we did it in this file: ..."
4. **Correct misunderstandings**: "No, we use Valkey not Redis for that"

## Advanced Features

### MCP (Model Context Protocol)

Claude Code supports MCP servers for extended functionality:

- **Database introspection**: Query schemas directly
- **API testing**: Make HTTP requests to endpoints
- **Custom tools**: Add project-specific tools

See the Claude Code docs for MCP server setup.

### Custom Commands

Create custom slash commands in `.claude/commands/`:

```bash
# .claude/commands/pr-review.md
Reviews a pull request
```
## Quick Reference

### Common Commands

```bash
# Read a file
"Show me studio_api/bots/models.py"

# Search codebase
"Find all references to GeneratedClip"

# Run tests
"Run pytest on the generate module"

# Git operations
"Create a PR for this feature"
"Show me the git diff"

# Documentation
"Add this to the wiki"
```

### File Paths

Key directories:
- **Backend**: `studio_api/studio_api/`
- **Frontend**: `ui/app-ui/src/`
- **Workers**: `suno_utils/suno_utils/worker/`
- **Wiki**: `suno_wiki/src/content/`
- **Infrastructure**: `suno-cdk/`