# Claude Code Workflows

The **Claude Code workflows** provide AI-powered code review, PR description generation, and interactive assistance through GitHub Actions. These reusable workflows integrate [Claude Code](https://claude.ai/code) directly into your development workflow, enabling automated code reviews, intelligent PR summaries, and on-demand AI assistance.

The workflows are designed to be platform-agnostic and support customization for different tech stacks (Android, iOS, backend, frontend, etc.) through configurable inputs.

## Available Workflows

### 1. Interactive AI Assistant (`claude-pr-action.yml`)

Enables on-demand AI assistance via `@claude` mentions in PR comments. Team members can ask Claude to perform tasks like code explanations, refactoring suggestions, or implementing changes.

### 2. PR Description Generator (`claude-pr-describe.yml`)

Automatically generates comprehensive PR descriptions when a PR is opened with an empty body. The AI analyzes all changes and creates a structured description following your repository's PR template.

### 3. Automated Code Review (`claude-pr-review.yml`)

Performs intelligent code reviews on pull requests, providing inline comments on potential issues and a summary review with risk assessment. Can be triggered automatically on PR events or when a specific GitHub team is requested for review.

## Quick Start

### Prerequisites

1. **Anthropic API Key**: Obtain an API key from [Anthropic](https://console.anthropic.com/)
2. **GitHub Token**: Use the default `GITHUB_TOKEN` or create a PAT with appropriate permissions
3. Add your Anthropic API key to your repository secrets as `ANTHROPIC_API_KEY`

### Setup Instructions

Create workflow files in your repository's `.github/workflows/` directory:

#### 1. Interactive AI Assistant

Create `.github/workflows/claude.yml`:

```yaml
name: Claude

on:
  issue_comment:
    types: [created]

jobs:
  claude:
    uses: suno-ai/ci/.github/workflows/claude-pr-action.yml@main
    with:
      system_prompt: "You are a principal iOS engineer."
      max_turns: 30
    secrets:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

**Usage**: Comment `@claude` followed by your request on any PR (e.g., "@claude explain this function" or "@claude refactor this method for better readability")

#### 2. PR Description Generator

Create `.github/workflows/claude-pr-describe.yml`:

```yaml
name: Claude | PR Describe

on:
  pull_request:
    types: [opened, edited, reopened, synchronize, ready_for_review]

jobs:
  describe:
    uses: suno-ai/ci/.github/workflows/claude-pr-describe.yml@main
    with:
      system_prompt: "You are a principal Android engineer."
      focus_areas: |
        - **Android Architecture**: MVI pattern, Hilt dependency injection, Jetpack Compose best practices
        - **Kotlin/Android Best Practices**: Coroutines usage, StateFlow/SharedFlow, lifecycle management
        - **UI/Compose**: Composable design, state hoisting, common-ui component usage
        - **Performance**: Memory leaks, ANRs, main thread blocking, efficient data structures
        - **Testing**: JUnit & MockK for unit tests, Compose testing for UI
    secrets:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

**Usage**: Open a PR with an empty description - the workflow will automatically generate one based on your changes.

#### 3. Automated Code Review

Create `.github/workflows/claude-pr-review.yml`:

```yaml
name: Claude | PR Review

on:
  pull_request:
    types:
      [
        review_requested,
        opened,
        synchronize,
        reopened,
        ready_for_review,
        review_request_removed,
      ]

jobs:
  review:
    uses: suno-ai/ci/.github/workflows/claude-pr-review.yml@main
    with:
      system_prompt: "You are a principal iOS engineer."
      focus_areas: |
        - **iOS Architecture**: TCA pattern, proper reducer structure, SwiftUI best practices
        - **Swift/iOS Best Practices**: async/await usage, @ObservableState, dependency injection
        - **UI/SwiftUI**: Component composition, state management, ComponentLibrary usage
        - **Performance**: Memory leaks, retain cycles, inefficient operations
        - **Testing**: Coverage, proper mocking, TCA TestStore tests
      review_team_slug: "claude-code-review"
    secrets:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

**Usage**:

- Reviews are triggered automatically when PRs are opened or updated
- Request a review from the configured GitHub team (e.g., `@org/claude-code-review`) to trigger a review
- Reviews are automatically cancelled when the team review request is removed

## Configuration Options

### Common Inputs (All Workflows)

| Input           | Description                                                     | Default                                  | Required |
| --------------- | --------------------------------------------------------------- | ---------------------------------------- | -------- |
| `system_prompt` | AI role/persona (e.g., "You are a principal Android engineer.") | "You are a principal software engineer." | No       |
| `max_turns`     | Maximum number of AI conversation turns                         | 30 (15 for descriptions)                 | No       |
| `allowed_tools` | Comma-separated list of tools the AI can use                    | Standard PR tools                        | No       |

### PR Description Generator Inputs

| Input         | Description                                                          | Default             | Required |
| ------------- | -------------------------------------------------------------------- | ------------------- | -------- |
| `focus_areas` | Platform-specific focus areas for code review (markdown bullet list) | Generic focus areas | No       |
| `label_name`  | Label to add after description is generated                          | "ai-description"    | No       |
| `label_color` | Label color (hex without #)                                          | "e4008a"            | No       |

### Code Review Inputs

| Input              | Description                                                 | Default              | Required |
| ------------------ | ----------------------------------------------------------- | -------------------- | -------- |
| `focus_areas`      | Platform-specific review focus areas (markdown bullet list) | Generic focus areas  | No       |
| `review_team_slug` | GitHub team slug for triggering reviews                     | "claude-code-review" | No       |
| `label_name`       | Label to add after review is complete                       | "ai-review"          | No       |
| `label_color`      | Label color (hex without #)                                 | "fe019a"             | No       |

## Platform-Specific Examples

### Android Project

```yaml
# claude-pr-review.yml
jobs:
  review:
    uses: suno-ai/ci/.github/workflows/claude-pr-review.yml@main
    with:
      system_prompt: "You are a principal Android engineer."
      focus_areas: |
        - **Android Architecture**: MVI pattern, Hilt dependency injection, Jetpack Compose best practices
        - **Kotlin/Android Best Practices**: Coroutines usage, StateFlow/SharedFlow, lifecycle management
        - **UI/Compose**: Composable design, state hoisting, common-ui component usage
        - **Performance**: Memory leaks, ANRs, main thread blocking, efficient data structures
        - **Testing**: JUnit & MockK for unit tests, Compose testing for UI
      allowed_tools: "mcp__github__create_pending_pull_request_review,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review,mcp__github__get_pull_request_diff,mcp__github__get_pull_request_files,mcp__github__update_pull_request,mcp__github__get_file_contents,mcp__github__get_pull_request,Read,Glob,Grep,LS,Bash(git:*),Bash(./gradlew:*),Bash(gh:*)"
    secrets:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

### iOS Project

```yaml
# claude-pr-review.yml
jobs:
  review:
    uses: suno-ai/ci/.github/workflows/claude-pr-review.yml@main
    with:
      system_prompt: "You are a principal iOS engineer."
      focus_areas: |
        - **iOS Architecture**: TCA pattern, proper reducer structure, SwiftUI best practices
        - **Swift/iOS Best Practices**: async/await usage, @ObservableState, dependency injection
        - **UI/SwiftUI**: Component composition, state management, ComponentLibrary usage
        - **Performance**: Memory leaks, retain cycles, inefficient operations
        - **Testing**: Coverage, proper mocking, TCA TestStore tests
      allowed_tools: "mcp__github__create_pending_pull_request_review,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review,mcp__github__get_pull_request_diff,mcp__github__get_pull_request_files,mcp__github__update_pull_request,mcp__github__get_file_contents,mcp__github__get_pull_request,Read,Glob,Grep,LS,Bash(git:*),Bash(xcodebuild:*),Bash(swift:*),Bash(gh:*)"
    secrets:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

### Backend Project (Node.js)

```yaml
# claude-pr-review.yml
jobs:
  review:
    uses: suno-ai/ci/.github/workflows/claude-pr-review.yml@main
    with:
      system_prompt: "You are a senior backend engineer specializing in Node.js."
      focus_areas: |
        - **Backend Architecture**: API design, service layer patterns, dependency injection
        - **TypeScript Best Practices**: Type safety, async/await usage, error handling
        - **Performance**: Database query optimization, caching strategies, async operations
        - **Security**: Input validation, authentication, authorization, SQL injection prevention
        - **Testing**: Unit tests, integration tests, API contract testing
      allowed_tools: "mcp__github__create_pending_pull_request_review,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review,mcp__github__get_pull_request_diff,mcp__github__get_pull_request_files,mcp__github__update_pull_request,mcp__github__get_file_contents,mcp__github__get_pull_request,Read,Glob,Grep,LS,Bash(git:*),Bash(npm:*),Bash(node:*),Bash(gh:*)"
    secrets:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

## Advanced Configuration

### Using with Review Teams

To trigger reviews via GitHub team requests:

1. Create a GitHub team (e.g., `@your-org/claude-code-review`)
2. Configure the workflow with the team slug:

```yaml
with:
  review_team_slug: "claude-code-review"
```

3. Request a review from the team on any PR to trigger the AI review

### Managing Old Reviews

The code review workflow includes built-in support for resolving outdated reviews. When a new review is triggered, the workflow automatically marks previous reviews from `claude[bot]` as outdated using the `resolve-reviews` action. This keeps your PR clean and ensures reviewers focus on the latest feedback.

The workflow also includes a `cancel` job that resolves reviews when the review team request is removed.

### Custom Labels

Customize labels to match your workflow:

```yaml
with:
  label_name: "ai-reviewed"
  label_color: "0e8a16" # Green label
```

### Platform-Specific Build Tools

Add platform-specific tools to `allowed_tools`:

- **Android**: `Bash(./gradlew:*)`
- **iOS**: `Bash(xcodebuild:*)`, `Bash(swift:*)`
- **Node.js**: `Bash(npm:*)`, `Bash(node:*)`
- **Python**: `Bash(python:*)`, `Bash(pip:*)`
- **Ruby**: `Bash(bundle:*)`, `Bash(ruby:*)`

## Best Practices

1. **System Prompt**: Set a specific role that matches your tech stack for better-quality reviews
2. **Focus Areas**: Customize focus areas to match your architecture patterns and coding standards
3. **Additional Focus Areas**: Use this for platform-specific concerns in the impact assessment
4. **Allowed Tools**: Start with defaults and add platform-specific tools as needed
5. **Review Teams**: Use dedicated GitHub teams to control who can trigger reviews
6. **Labels**: Use consistent labeling to track AI-generated content

## Permissions

The workflows require the following GitHub token permissions:

- `contents: write` - To checkout code and make changes
- `pull-requests: write` - To comment on PRs and submit reviews
- `id-token: write` - For OIDC authentication
- `actions: read` - To read workflow information

These are automatically configured in the reusable workflows.

## Troubleshooting

### Reviews Not Triggering

- Verify the PR is not in draft mode
- Check that the PR author is not a bot
- Ensure `ANTHROPIC_API_KEY` is correctly set in repository secrets
- Verify the team slug matches your GitHub team's slug

### AI Not Finding Issues

- Customize `focus_areas` to match your codebase patterns
- Ensure `allowed_tools` includes necessary file reading tools
- Increase `max_turns` if the AI needs more time to analyze

### Rate Limits

- Adjust `max_turns` to reduce API usage
- Use concurrency limits to prevent multiple reviews running simultaneously (already configured in workflows)

## Examples in Production

See these repositories for real-world usage:

- Android: `suno-ai/app-android` (example reference)
- iOS: `suno-ai/app-ios` (example reference)

## Support

For issues or questions:

1. Check the [Claude Code documentation](https://docs.claude.com/en/docs/claude-code)
2. Review the [anthropics/claude-code-action](https://github.com/anthropics/claude-code-action) repository
3. Open an issue in this repository