# CLAUDE.md

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

## Repository Purpose

This repository contains reusable GitHub Actions for AI-powered CI/CD workflows, specifically designed to integrate Claude Code into GitHub repositories. The actions enable automated code review, PR description generation, comment cleanup, and general AI-assisted tasks.

## Architecture Overview

The repository follows a standard GitHub Actions structure:

- `.github/workflows/` - Contains reusable workflows for Claude Code integration
- `.github/actions/` - Contains supporting composite actions
- All workflows use the `anthropics/claude-code-action@v1` as the core execution engine
- Workflows support both direct invocation and PR event triggers

## Action Types and Usage Patterns

### Core Actions

The repository provides reusable workflows (not composite actions) for Claude Code integration:

1. **claude-pr-action** (`.github/workflows/claude-pr-action.yml`) - Interactive AI assistant triggered via @claude mentions in PR comments
2. **claude-pr-review** (`.github/workflows/claude-pr-review.yml`) - Automated code review with GitHub review integration
3. **claude-pr-describe** (`.github/workflows/claude-pr-describe.yml`) - Automatic PR description generation

### Supporting Actions

1. **resolve-reviews** (`.github/actions/resolve-reviews/`) - Marks old AI reviews as outdated
2. **pull-request-add-label** (`.github/actions/pull-request-add-label/`) - Adds labels to PRs
3. **command-setup** (`.github/actions/command-setup/`) - Sets up slash command processing

### Common Input Patterns

All reusable workflows share these standard inputs:

- `system_prompt` - AI role/persona (e.g., "You are a principal iOS engineer.")
- `max_turns` - Maximum AI conversation turns (15-30 turns depending on workflow)
- `allowed_tools` - Comma-separated list of tools the AI can use
- `focus_areas` - Platform-specific focus areas (for review and describe workflows)

All workflows require the `anthropic_api_key` secret and optionally accept `github_token` secret (defaults to `github.token`).

### Tool Permissions Architecture

Workflows use specific tool allowlists based on their function:

- Review tools: `mcp__github__create_pending_pull_request_review`, `mcp__github__add_comment_to_pending_review`, `mcp__github__submit_pending_pull_request_review`
- Diff analysis: `mcp__github__get_pull_request_diff`, `mcp__github__get_pull_request_files`
- PR updates: `mcp__github__update_pull_request`, `mcp__github__get_pull_request`
- File operations: `Read`, `Glob`, `Grep`, `LS`
- Git operations: `Bash(git:*)`, `Bash(gh:*)`

## Development Guidelines

### Adding New Workflows

1. Create new workflow file in `.github/workflows/` with descriptive name (e.g., `claude-pr-*.yml`)
2. Use `workflow_call` trigger to make it reusable
3. Define specific `allowed_tools` list based on workflow requirements
4. Set appropriate default `max_turns` for the use case (15 for simple tasks, 30 for complex reviews)
5. Include proper job conditions to filter out bots and draft PRs
6. Add concurrency control to prevent duplicate runs

### Workflow Design Principles

- Use specific, focused tool permissions rather than broad access
- Set reasonable `max_turns` based on expected complexity
- Provide meaningful default prompts that work out-of-the-box
- Support platform-specific customization via inputs
- Include proper error handling and conditional execution
- Use sticky comments for better UX

## Reference Usage

### Reusable Workflows

The repository also provides reusable workflows for common Claude Code integration patterns. These workflows are designed to be platform-agnostic and support customization through inputs.

#### Claude Action (@claude mentions in PR comments)

Enables interactive AI assistance via `@claude` mentions in PR comments.

**Usage:**

```yaml
name: Claude

on:
  issue_comment:
    types: [created]

jobs:
  claude:
    uses: your-org/ci/.github/workflows/claude-pr-action.yml@main
    with:
      system_prompt: 'You are a principal iOS engineer.'  # Customize for your platform
      max_turns: 30
      allowed_tools: 'mcp__github__get_pull_request,mcp__github__get_pull_request_diff,Read,Glob,Grep,LS,Bash(git:*),Bash(gh:*)'
    secrets:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

**Inputs:**

- `system_prompt` (optional): AI role/persona (default: "You are a principal software engineer.")
- `max_turns` (optional): Maximum AI turns (default: 30)
- `allowed_tools` (optional): Comma-separated list of tools (default: standard PR tools)

#### PR Description Generation

Automatically generates PR descriptions when a PR is opened with an empty body.

**Usage:**

```yaml
name: Claude | PR Generate Description

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

jobs:
  generate-description:
    uses: your-org/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
    secrets:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

**Inputs:**

- `system_prompt` (optional): AI role/persona (default: "You are a principal software engineer.")
- `focus_areas` (optional): Platform-specific focus areas (markdown bullet list)
- `max_turns` (optional): Maximum AI turns (default: 15)
- `allowed_tools` (optional): Comma-separated list of tools
- `label_name` (optional): Label to add after completion (default: "ai-description")
- `label_color` (optional): Label color hex code (default: "e4008a")

#### PR Code Review

Performs automated code reviews when PRs are opened or when a specific team is requested for review.

**Usage:**

```yaml
name: Claude | PR Code Review

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

jobs:
  review:
    uses: your-org/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 }}
```

**Inputs:**

- `system_prompt` (optional): AI role/persona (default: "You are a principal software engineer.")
- `focus_areas` (optional): Platform-specific review focus areas (markdown bullet list)
- `max_turns` (optional): Maximum AI turns (default: 30)
- `allowed_tools` (optional): Comma-separated list of tools
- `review_team_slug` (optional): GitHub team slug for review requests (default: "claude-code-review")
- `label_name` (optional): Label to add after review (default: "ai-review")
- `label_color` (optional): Label color hex code (default: "fe019a")

**Key Features:**

- Automatically triggers on team review requests or new PRs without the `ai-review` label
- Includes a `cancel` job that resolves reviews when the review request is removed
- Automatically resolves old reviews from `claude[bot]` when new reviews are submitted
- Supports platform-specific focus areas and custom review guidelines

#### Platform-Specific Examples

**Android Configuration:**

```yaml
uses: your-org/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:*)'
```

**iOS Configuration:**

```yaml
uses: your-org/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:*)'
```

### Workflow Customization Guidelines

When adapting these workflows for your repository:

1. **System Prompt**: Set the appropriate role (e.g., "principal Android engineer", "senior backend developer")
2. **Focus Areas**: Customize to match your architecture patterns and technology stack
3. **Allowed Tools**: Add platform-specific build tools (e.g., `Bash(./gradlew:*)` for Android, `Bash(xcodebuild:*)` for iOS)
4. **Additional Focus Areas**: Highlight platform-specific concerns for impact assessment
5. **Review Team**: Configure your GitHub team slug for triggering reviews
6. **Labels**: Customize label names and colors to match your workflow

## Development Workflow

### Pre-commit Hooks

This repository uses pre-commit hooks to ensure code quality:

```bash
# Install pre-commit (first time setup)
pip install pre-commit
pre-commit install

# Run hooks manually on all files
pre-commit run --all-files
```

The pre-commit configuration includes:

- YAML syntax validation and linting
- JSON/TOML syntax checking
- Markdown linting with auto-fixing
- GitHub Actions workflow schema validation
- Secret detection scanning
- File formatting (trailing whitespace, line endings)

### CI Pipeline

The `.github/workflows/ci.yml` workflow runs on every push and PR:

1. **Code Quality Validation** - Runs all pre-commit hooks
2. **Action Validation** - Validates all `action.yml` files for required fields and YAML syntax
3. **Security Scanning** - Uses Trivy to scan for vulnerabilities

All checks must pass before code can be merged.

### Configuration Files

- `.pre-commit-config.yaml` - Pre-commit hook configuration
- `.yamllint.yml` - YAML linting rules (allows 120 char lines for GitHub Actions)
- `.markdownlint.json` - Markdown linting rules
- `.secrets.baseline` - Baseline for secret detection

## Dependencies

All workflows depend on:

- `anthropics/claude-code-action@v1` - Core AI execution engine
- `actions/checkout@v4` - For checking out repository code
- GitHub CLI (`gh`) - For label management and PR operations
- Repository secrets: `ANTHROPIC_API_KEY` (required), `GITHUB_TOKEN` (optional, defaults to `github.token`)

Development dependencies:

- `pre-commit` - Code quality automation
- Various linters and validators via pre-commit hooks