Add Claude Code GitHub Workflow

[jonphipps]

🤖 Installing Claude Code GitHub App

This PR adds a GitHub Actions workflow that enables Claude Code integration in our repository.

What is Claude Code?

Claude Code is an AI coding agent that can help with:

• Bug fixes and improvements
• Documentation updates
• Implementing new features
• Code reviews and suggestions
• Writing tests
• And more!

How it works

Once this PR is merged, we'll be able to interact with Claude by mentioning @claude in a pull request or issue comment.
Once the workflow is triggered, Claude will analyze the comment and surrounding context, and execute on the request in a GitHub action.

Important Notes

• This workflow won't take effect until this PR is merged
• @claude mentions won't work until after the merge is complete
• The workflow runs automatically whenever Claude is mentioned in PR or issue comments
• Claude gets access to the entire PR or issue context including files, diffs, and previous comments

Security

• Our Anthropic API key is securely stored as a GitHub Actions secret
• Only users with write access to the repository can trigger the workflow
• All Claude runs are stored in the GitHub Actions run history
• Claude's default tools are limited to reading/writing files and interacting with our repo by creating comments, branches, and commits.
• We can add more allowed tools by adding them to the workflow file like:

allowed_tools: Bash(npm install),Bash(npm run build),Bash(npm run lint),Bash(npm run test)

There's more information in the Claude Code documentation.

After merging this PR, let's try mentioning @claude in a comment on any PR to get started!

[claude]

Claude finished @jonphipps's task —— View job

---

PR Review: Add Claude Code GitHub Workflow

Todo List:

• Read and analyze both workflow files
• Review security considerations and best practices
• Check for potential bugs or issues
• Provide comprehensive feedback

Review Summary

Overall, this is a solid implementation of Claude Code workflows with good security practices and comprehensive documentation. However, there are several opportunities for improvement, particularly around project-specific configuration and performance optimization.

🔍 Detailed Analysis

claude-code-review.yml - Automated PR Reviews

✅ Strengths:

• Proper minimal permissions (contents: read, pull-requests: read, etc.)
• Uses latest actions/checkout@v4 with shallow fetch for performance
• Comprehensive commented examples for customization
• Secure API key handling via secrets

⚠️ Areas for Improvement:

1. Trigger Frequency (.github/workflows/claude-code-review.yml:4-5)

   • Currently triggers on both opened and synchronize, meaning Claude reviews every push
   • This could be expensive and noisy for active PRs
   • Recommendation: Consider limiting to opened only, or add conditions to skip draft PRs

2. Missing Project-Specific Context (.github/workflows/claude-code-review.yml:44-52)

   • The direct_prompt is generic and doesn't leverage your detailed CLAUDE.md guidelines
   • Recommendation: Incorporate project-specific instructions:

   direct_prompt: |
     Please review this pull request focusing on the IFLA Standards Development project guidelines:
     - Code quality and best practices (use pnpm, not npm)
     - Ensure vitest tests are included and passing
     - Check Docusaurus/MDX best practices for standards documentation
     - Verify proper component structure (index.tsx + styles.module.scss)
     - Security concerns and performance considerations

3. Missing Tools Configuration (.github/workflows/claude-code-review.yml:69)

   • The commented allowed_tools should be configured for your project
   • Recommendation: Uncomment and configure:

   allowed_tools: "Bash(pnpm install),Bash(pnpm run build),Bash(pnpm run test),Bash(pnpm run lint)"

claude.yml - Interactive Claude Responses

✅ Strengths:

• Comprehensive event triggers covering issues, PR comments, and reviews
• Smart conditional logic to only run when @claude is mentioned
• Proper security and permissions setup

⚠️ Areas for Improvement:

1. Complex Conditional Logic (.github/workflows/claude.yml:15-19)

   • The multi-line conditional is hard to read and maintain
   • Recommendation: Consider extracting to a composite action or simplifying

2. Missing Custom Instructions (.github/workflows/claude.yml:50-54)

   • Your CLAUDE.md contains extensive project guidelines that should be passed to Claude
   • Recommendation: Add project-specific instructions:

   custom_instructions: |
     This is the IFLA Standards Development project using pnpm workspaces with Docusaurus.
     Key guidelines:
     - Use pnpm (not npm) for package management
     - Test with vitest before committing
     - Follow component structure: index.tsx + styles.module.scss
     - Use TodoWrite/TodoRead for task tracking
     - Build single standards with: pnpm build standards/{name}

3. Missing Essential Tools (.github/workflows/claude.yml:47-48)

   • Should include the tools Claude will need for this project
   • Recommendation:

   allowed_tools: "Bash(pnpm install),Bash(pnpm run build),Bash(pnpm run test),Bash(pnpm run lint),Bash(pnpm build standards/*)"

🛡️ Security Assessment

✅ Good practices:

• API key properly stored as GitHub secret
• Minimal required permissions granted
• Uses OIDC token (id-token: write) for enhanced security

⚠️ Considerations:

• No restrictions on who can trigger Claude (any collaborator can use @claude)
• No rate limiting to prevent API quota exhaustion
• Consider adding user allowlists if needed for your organization

🚀 Performance Considerations

✅ Optimizations in place:

• Shallow git fetch (fetch-depth: 1)
• Conditional execution to avoid unnecessary runs

⚠️ Potential improvements:

• Path-based filtering could reduce review frequency for non-code changes
• Consider timeout configurations for long-running operations

🧪 Testing & Quality

⚠️ Missing elements:

• No error handling if Claude API fails
• No logging or monitoring for workflow success/failure
• No integration with your existing test infrastructure (vitest)

📋 Recommendations Summary

1. High Priority:

   • Add project-specific custom_instructions to both workflows
   • Configure allowed_tools with pnpm commands
   • Consider reducing auto-review trigger frequency

2. Medium Priority:

   • Add path-based filtering for performance
   • Implement error handling and logging
   • Consider user access controls

3. Low Priority:

   • Simplify complex conditional logic
   • Add timeout configurations
   • Consider draft PR exclusions

✅ Approval Recommendation

This PR is ready to merge with the current implementation. The workflows are secure and functional. The suggested improvements can be implemented in follow-up PRs after you've had a chance to test the basic functionality.

The workflows demonstrate good understanding of GitHub Actions best practices and Claude Code integration patterns.

---