From 87994bb797544dba6aa87b02ec335c7fb408de6a Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Sat, 10 Jan 2026 15:26:18 +0100 Subject: [PATCH] feat(guide): add thinking keywords, GitHub Actions examples, and improvement recommendations Documentation enhancements: - Add inline thinking keywords section (think, think hard, ultrathink) with usage examples - Create examples/github-actions/ directory with 3 ready-to-use workflows: * Auto PR review with inline comments * Security review on every PR * Issue triage with label suggestions - Add comprehensive IMPROVEMENT_RECOMMENDATIONS.md with prioritized action items Improvements based on zebbern/claude-code-guide analysis: - Enhanced troubleshooting guidance - Format enhancements (badges, collapsible tables, C-style comments) - Security/performance/workflow pitfalls sections - DeepSeek integration documentation - One-shot health check scripts Co-Authored-By: Claude Sonnet 4.5 --- IMPROVEMENT_RECOMMENDATIONS.md | 572 ++++++++++++++++++ english-ultimate-claude-code-guide.md | 25 + examples/github-actions/README.md | 203 +++++++ .../github-actions/claude-issue-triage.yml | 101 ++++ .../github-actions/claude-pr-auto-review.yml | 31 + .../github-actions/claude-security-review.yml | 26 + 6 files changed, 958 insertions(+) create mode 100644 IMPROVEMENT_RECOMMENDATIONS.md create mode 100644 examples/github-actions/README.md create mode 100644 examples/github-actions/claude-issue-triage.yml create mode 100644 examples/github-actions/claude-pr-auto-review.yml create mode 100644 examples/github-actions/claude-security-review.yml diff --git a/IMPROVEMENT_RECOMMENDATIONS.md b/IMPROVEMENT_RECOMMENDATIONS.md new file mode 100644 index 0000000..632f41b --- /dev/null +++ b/IMPROVEMENT_RECOMMENDATIONS.md @@ -0,0 +1,572 @@ +# Guide Improvement Recommendations + +Based on comprehensive analysis of zebbern/claude-code-guide, here are prioritized recommendations to enhance our Claude Code Ultimate Guide. + +## Priority 1: High-Impact Quick Wins โšก + +### 1.1 Add Status Overview Table (5 min) + +**What:** Add a visual status table at the top showing section completeness. + +**Where:** Right after the main title, before TOC. + +**Implementation:** +```markdown +
+ +| Section | Status | Coverage | +|---------|--------|----------| +| Installation & Setup | โœ… Complete | 100% | +| Core Concepts | โœ… Complete | 100% | +| Agents & Skills | โœ… Complete | 100% | +| MCP Integration | ๐Ÿ”„ Updating | 95% | +| Advanced Patterns | โœ… Complete | 100% | +| Troubleshooting | โœ… Complete | 100% | + +
+``` + +**Benefit:** Users immediately see what's covered and maturity level. + +--- + +### 1.2 Create One-Page Cheat Sheet (30 min) + +**What:** Ultra-condensed reference for daily use. + +**File:** `cheatsheet-en.md` (already exists but could be enhanced) + +**Format:** Single page with these sections: +```markdown +## Quick Reference Card + +### Essential Commands +claude # Start REPL +claude -p "query" # Print mode +claude --model sonnet # Model selection +claude --think # Extended reasoning + +### Config Management +claude config get +claude config set +claude config add # For arrays + +### MCP Quick Setup +claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents + +### Debugging +claude doctor +claude --debug +claude --verbose + +### Permission Control +--allowedTools "Edit,Read,Bash(git:*)" +--disallowedTools "WebFetch" +``` + +**Benefit:** Printable, scannable, perfect for new team members. + +--- + +### 1.3 Complete Command Line Flags Table (20 min) + +**What:** Comprehensive reference for all CLI flags. + +**Where:** Section 6 or new appendix. + +**Content:** Based on zebbern's table: +| Flag | Description | Example | +|------|-------------|---------| +| `-p, --print` | Print response and exit | `claude -p "query"` | +| `--output-format` | Output format (text/json/stream-json) | `--output-format json` | +| `--input-format` | Input format (text/stream-json) | `--input-format stream-json` | +| `--replay-user-messages` | Re-emit user messages in stream | `--replay-user-messages` | +| `--allowedTools` | Whitelist tools | `--allowedTools "Edit,Read"` | +| `--disallowedTools` | Blacklist tools | `--disallowedTools "WebFetch"` | +| `--mcp-config` | Load MCP from JSON | `--mcp-config ./mcp.json` | +| `--strict-mcp-config` | Only use specified MCP | `--strict-mcp-config` | +| `--append-system-prompt` | Add to system prompt | `--append-system-prompt "..."` | +| `--permission-mode` | Permission mode | `--permission-mode plan` | +| `--model` | Model selection | `--model sonnet` | +| `--add-dir` | Additional directories | `--add-dir ../apps ../lib` | +| `--continue` | Continue last conversation | `--continue` | +| `-r, --resume` | Resume session by ID | `--resume abc123` | +| `--dangerously-skip-permissions` | Skip all permissions | `--dangerously-skip-permissions` | + +**Benefit:** Complete reference for power users and automation. + +--- + +## Priority 2: Enhanced Troubleshooting ๐Ÿ”ง + +### 2.1 MCP Troubleshooting Section Enhancement (45 min) + +**What:** Add common MCP errors and solutions. + +**Where:** Expand section 10.4 "MCP Issues" + +**New subsections:** + +#### Common MCP Errors + +**Error 1: Tool Name Validation Failed** +``` +API Error 400: "tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}'" +``` +**Solution:** +- Server name: only letters, numbers, underscores, hyphens +- Max 64 characters +- No special characters or spaces + +**Error 2: MCP Server Not Found** +``` +MCP server 'my-server' not found +``` +**Solution:** +1. Check scope settings (local/user/project) +2. Run `claude mcp list` to verify +3. Ensure correct directory for local scope +4. Restart Claude Code + +**Error 3: Windows Path Issues** +``` +Error: Cannot find module 'C:UsersusernameDocuments' +``` +**Solution:** +```bash +# Wrong +claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Documents + +# Correct +claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents +# or +claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem "C:\\Users\\username\\Documents" +``` + +#### MCP Debugging Techniques + +**Enable Debug Mode:** +```bash +claude --mcp-debug +``` + +**View MCP Status:** +```bash +/mcp # Inside Claude Code +``` + +**View Log Files:** +```bash +# macOS/Linux +tail -f ~/Library/Logs/Claude/mcp*.log + +# Windows +type "%APPDATA%\Claude\logs\mcp*.log" +``` + +**Manual Server Test:** +```bash +# Test if server works standalone +npx -y @modelcontextprotocol/server-filesystem ~/Documents +``` + +--- + +### 2.2 One-Shot Health Check Scripts (15 min) + +**What:** Copy-paste diagnostic scripts. + +**Where:** Section 10 "Help & Troubleshooting" + +**Windows (PowerShell):** +```powershell +Write-Host "`n=== Node & npm ==="; node --version; npm --version +Write-Host "`n=== Where is claude? ==="; where claude +Write-Host "`n=== Try doctor ==="; try { claude doctor } catch { Write-Host "claude not on PATH" } +Write-Host "`n=== API key set? ==="; if ($env:ANTHROPIC_API_KEY) { "Yes" } else { "No" } +Write-Host "`n=== MCP Status ==="; claude mcp list +``` + +**macOS/Linux (bash/zsh):** +```bash +echo "=== Node & npm ==="; node --version; npm --version +echo "=== Where is claude? ==="; which claude || echo "claude not on PATH" +echo "=== Try doctor ==="; claude doctor || true +echo "=== API key set? ==="; [ -n "$ANTHROPIC_API_KEY" ] && echo Yes || echo No +echo "=== MCP Status ==="; claude mcp list +``` + +**Benefit:** Instant diagnosis for users reporting issues. + +--- + +### 2.3 Full Clean Reinstall Procedures (20 min) + +**What:** Nuclear option for corrupted installations. + +**Where:** Section 10 troubleshooting + +**Windows PowerShell Script:** +```powershell +# 1. Uninstall +npm uninstall -g @anthropic-ai/claude-code + +# 2. Remove shims +Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\claude*" -Force -ErrorAction SilentlyContinue +Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code" -Recurse -Force -ErrorAction SilentlyContinue + +# 3. Delete cache +Remove-Item -LiteralPath "$env:USERPROFILE\.claude\downloads\*" -Recurse -Force -ErrorAction SilentlyContinue +Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local" -Recurse -Force -ErrorAction SilentlyContinue + +# 4. Remove config (optional - backs up first) +Copy-Item "$env:USERPROFILE\.claude.json" "$env:USERPROFILE\.claude.json.backup" -ErrorAction SilentlyContinue +Remove-Item -LiteralPath "$env:USERPROFILE\.claude.json" -Force -ErrorAction SilentlyContinue + +# 5. Reinstall +npm install -g @anthropic-ai/claude-code +``` + +**macOS/Linux Script:** +```bash +#!/bin/bash +# 1. Uninstall +npm uninstall -g @anthropic-ai/claude-code + +# 2. Remove global bin files +rm -f "$(npm config get prefix)/bin/claude" +rm -rf "$(npm config get prefix)/lib/node_modules/@anthropic-ai/claude-code" + +# 3. Delete cache +rm -rf ~/.claude/downloads/* +rm -rf ~/.claude/local + +# 4. Backup and remove config (optional) +cp ~/.claude.json ~/.claude.json.backup 2>/dev/null || true +rm -f ~/.claude.json + +# 5. Reinstall +npm install -g @anthropic-ai/claude-code +``` + +**Benefit:** Last resort fix for mysterious issues. + +--- + +## Priority 3: Format Enhancements ๐Ÿ“ + +### 3.1 Add Visual Badges (10 min) + +**What:** Status badges at top of README. + +**Implementation:** +```markdown +![Claude Code Version](https://img.shields.io/badge/Claude%20Code-1.0+-blue) +![Status](https://img.shields.io/badge/Status-Active-brightgreen) +![License](https://img.shields.io/badge/License-MIT-orange) +![Last Updated](https://img.shields.io/badge/Updated-January%202026-blue) +``` + +--- + +### 3.2 Collapsible Tables for Dense Content (30 min) + +**What:** Use `
` tags or tables for long sections. + +**Where:** Troubleshooting, environment variables, MCP server list. + +**Example:** +```markdown +
+Environment Variables Reference (click to expand) + +| Variable | Purpose | Example | +|----------|---------|---------| +| `ANTHROPIC_API_KEY` | API authentication | `sk-ant-...` | +| `ANTHROPIC_MODEL` | Default model | `claude-sonnet-4-20250514` | +| `BASH_DEFAULT_TIMEOUT_MS` | Bash timeout | `60000` | +... + +
+``` + +**Benefit:** Reduces visual clutter while keeping info accessible. + +--- + +### 3.3 "C-Style Comment" Format for Multi-Variant Commands (15 min) + +**What:** Visual organization for OS-specific commands. + +**Example:** +```C +# Quick Start Installation +/*โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€*/ +/* Universal Method */ npm install -g @anthropic-ai/claude-code +/*โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€*/ +/* Windows (CMD) */ npm install -g @anthropic-ai/claude-code +/* Windows (PowerShell) */ irm https://claude.ai/install.ps1 | iex +/*โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€*/ +/* macOS */ brew install node && npm install -g @anthropic-ai/claude-code +/*โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€*/ +/* Linux (Debian/Ubuntu) */ sudo apt update && sudo apt install -y nodejs npm +/* */ npm install -g @anthropic-ai/claude-code +``` + +**Benefit:** Extremely scannable, looks professional. + +--- + +## Priority 4: Content Additions ๐Ÿ“š + +### 4.1 Security Best Practices - Do/Don't Format (30 min) + +**What:** Clear visual Do/Don't examples. + +**Where:** Section 8 Security + +**Format:** +```markdown +### Security Pitfalls + +**โŒ Don't:** +- Use `--dangerously-skip-permissions` on production systems +- Hard-code secrets in commands/config files +- Grant overly broad permissions (`Bash(*)`) +- Run with elevated privileges unnecessarily + +**โœ… Do:** +- Store secrets in environment variables +- Start from minimal permissions and expand gradually +- Audit regularly with `claude config list` +- Isolate risky operations in containers/VMs +``` + +--- + +### 4.2 Performance Pitfalls Section (20 min) + +**What:** Common performance mistakes. + +**Format:** +```markdown +### Performance Pitfalls + +**โŒ Don't:** +- Load entire monorepo when you only need one package +- Max out thinking/turn budgets for simple tasks +- Ignore session cleanup (old sessions accumulate) +- Use `--ultrathink` for trivial edits + +**โœ… Do:** +- Use `--add-dir` for focused context +- Right-size with `--max-turns` and `MAX_THINKING_TOKENS` +- Set `cleanupPeriodDays` to prune old sessions +- Match thinking level to task complexity +``` + +--- + +### 4.3 Workflow Pitfalls Section (20 min) + +**What:** Common workflow mistakes. + +**Format:** +```markdown +### Workflow Pitfalls + +**โŒ Don't:** +- Skip project context (`CLAUDE.md`) +- Use vague prompts ("fix this", "check my code") +- Ignore errors in logs +- Automate workflows without testing first + +**โœ… Do:** +- Maintain and update `CLAUDE.md` regularly +- Be specific and goal-oriented in prompts +- Monitor via logs/OpenTelemetry as appropriate +- Test automation in safe environments first +- Review agent outputs before committing +``` + +--- + +### 4.4 DeepSeek Integration (15 min) + +**What:** Alternative LLM provider integration. + +**Where:** Section 11 "Third-Party Integrations" + +**Content:** +```markdown +## 11.1 DeepSeek Integration + +Use DeepSeek's Claude-compatible API as a cost-effective alternative. + +### Setup + +1. **Prerequisites:** + - Claude Code installed: `npm install -g @anthropic-ai/claude-code` + - DeepSeek API key from [platform.deepseek.com](https://platform.deepseek.com) + +2. **Configure Environment:** + ```bash + export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic + export ANTHROPIC_AUTH_TOKEN=${YOUR_DEEPSEEK_API_KEY} + export ANTHROPIC_MODEL=deepseek-chat + export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat + ``` + +3. **Launch Claude:** + ```bash + claude + ``` + +### Cost Comparison + +| Provider | Model | Cost per 1M tokens | +|----------|-------|-------------------| +| Anthropic | Sonnet 4 | ~$3.00 | +| DeepSeek | deepseek-chat | ~$0.14 | + +**Savings: ~95% reduction** + +### Limitations + +- DeepSeek models have different capabilities than Claude +- Some advanced features may not work identically +- Performance/quality trade-offs exist + +### Resources + +- [DeepSeek API Documentation](https://api-docs.deepseek.com/guides/anthropic_api) +- [DeepSeek Platform](https://platform.deepseek.com) +``` + +--- + +## Priority 5: Documentation Structure ๐Ÿ—๏ธ + +### 5.1 Add Quick Navigation Links (10 min) + +**What:** Jump links at top of major sections. + +**Example:** +```markdown +## Section 6: Commands & Usage + +_Quick jump:_ [Slash Commands](#slash-commands) ยท [CLI Flags](#cli-flags) ยท [Cheat Sheet](#cheat-sheet) ยท [Environment Variables](#environment-variables) + +--- + +### 6.1 Slash Commands +... +``` + +--- + +### 5.2 Appendix: Useful Paths (10 min) + +**What:** Reference for file locations. + +**Content:** +```markdown +## Appendix A: File Locations Reference + +### Windows +- **npm global bin:** `C:\Users\\AppData\Roaming\npm` +- **Node.js:** `C:\Program Files\nodejs` +- **Claude data:** `C:\Users\\.claude\` +- **Claude config:** `C:\Users\\.claude.json` +- **Logs:** `%APPDATA%\Claude\logs\` + +### macOS/Linux +- **npm global bin:** `$(npm config get prefix)/bin` (often `/usr/local/bin`) +- **Claude data:** `~/.claude/` +- **Claude config:** `~/.claude.json` +- **Logs (macOS):** `~/Library/Logs/Claude/` +- **Logs (Linux):** `~/.local/share/claude/logs/` +``` + +--- + +## Implementation Roadmap + +### Phase 1: Quick Wins (2-3 hours) +1. โœ… Add thinking keywords inline syntax +2. โœ… Create GitHub Actions examples directory +3. Add status overview table +4. Create/enhance cheat sheet +5. Add CLI flags table +6. Add visual badges + +### Phase 2: Troubleshooting (3-4 hours) +1. MCP troubleshooting enhancement +2. One-shot health check scripts +3. Full clean reinstall procedures +4. Appendix: useful paths + +### Phase 3: Content Enrichment (4-5 hours) +1. Security pitfalls Do/Don't +2. Performance pitfalls +3. Workflow pitfalls +4. DeepSeek integration +5. Collapsible tables for dense content + +### Phase 4: Format Polish (2-3 hours) +1. C-style comment format for commands +2. Quick navigation links +3. Consistent emoji hierarchy +4. Table of contents update + +--- + +## Metrics for Success + +### User Experience +- **Time to first success:** < 15 minutes (installation โ†’ first task) +- **Time to find answer:** < 2 minutes (via cheat sheet or quick links) +- **Support ticket reduction:** Target 30% reduction via better troubleshooting + +### Content Quality +- **Coverage:** 100% of official features documented +- **Accuracy:** < 1% error rate in commands/examples +- **Freshness:** Updated within 7 days of new Claude Code releases + +### Community Engagement +- **GitHub Stars:** Track growth trend +- **Issues/PRs:** Measure community contributions +- **Fork activity:** Indicates usage/adaptation + +--- + +## What NOT to Change + +**Keep these strengths from our guide:** + +1. **Learning Path Structure** - Junior โ†’ Senior โ†’ Power User progression +2. **Trinity Pattern** - Unique advanced workflow +3. **OpusPlan Mode** - Cost optimization strategy +4. **Context Management Zones** - Clear guidance on usage levels +5. **Maturity Model** - 5-level progression framework +6. **Agent-Based Task Delegation** - Advanced orchestration +7. **Skill Inheritance Model** - Reusable expertise +8. **Git Archaeology Pattern** - Unique debugging approach +9. **Narrative Style** - Pedagogical, not just reference +10. **Real-world Examples** - Production scenarios, not toy examples + +--- + +## Conclusion + +These recommendations balance: +- **Immediate impact** (quick wins) with **long-term value** (structural improvements) +- **Reference utility** (cheat sheets, tables) with **learning journey** (narrative) +- **Completeness** (troubleshooting) with **scannability** (collapsible sections) + +**Core Philosophy:** +> zebbern's guide = comprehensive reference +> our guide = mastery journey +> **enhanced guide = both** + +By selectively adopting zebbern's strengths while preserving our unique pedagogical approach, we create the definitive Claude Code resource. diff --git a/english-ultimate-claude-code-guide.md b/english-ultimate-claude-code-guide.md index d3906e2..4dfa1c2 100644 --- a/english-ultimate-claude-code-guide.md +++ b/english-ultimate-claude-code-guide.md @@ -3932,6 +3932,31 @@ The most powerful Claude Code pattern combines three techniques: | `--think-hard` | Deep | ~10K | Architectural decisions | | `--ultrathink` | Maximum | ~32K | Critical redesign | +#### Inline Thinking Keywords + +You can also trigger extended thinking by adding keywords directly in your prompt: + +```bash +# Minimal boost - standard analysis +claude -p "Think. Outline a plan to refactor the auth module." + +# Medium boost - deeper consideration +claude -p "Think hard. Draft a migration plan from REST to gRPC." + +# Strong boost - thorough analysis +claude -p "Think harder. Evaluate trade-offs for our caching strategy." + +# Maximum boost - comprehensive reasoning +claude -p "Ultrathink. Propose a step-by-step strategy to fix flaky payment tests and add guardrails." +``` + +**How it works:** +- **think** โ†’ Claude spends more time planning before responding +- **think hard/harder** โ†’ Progressively deeper analysis with more consideration of alternatives +- **ultrathink** โ†’ Maximum pre-answer reasoning about implications, edge cases, and trade-offs + +**Higher levels increase latency and token usage** - use the smallest level that works for your task. + ### Example: Using the Trinity ``` diff --git a/examples/github-actions/README.md b/examples/github-actions/README.md new file mode 100644 index 0000000..88e5229 --- /dev/null +++ b/examples/github-actions/README.md @@ -0,0 +1,203 @@ +# GitHub Actions Workflows for Claude Code + +Ready-to-use GitHub Actions workflows that integrate Claude Code into your CI/CD pipeline. + +## Prerequisites + +1. **Install the Claude GitHub App** on your org/repo (required for Actions to comment on PRs/issues) +2. **Add API Key Secret**: In your repo, go to Settings โ†’ Secrets and variables โ†’ Actions โ†’ New repository secret + - Name: `ANTHROPIC_API_KEY` + - Value: Your Anthropic API key from [console.anthropic.com](https://console.anthropic.com) +3. **Copy Workflows**: Place these `.yml` files in `.github/workflows/` directory +4. **Test**: Open a test PR or issue to see them run + +## Available Workflows + +### 1. Auto PR Review (`claude-pr-auto-review.yml`) + +Creates a structured review with inline comments as soon as a PR opens or updates. + +**Features:** +- Automatic code review on PR open/update +- Inline comments on specific lines +- Reviews for correctness, readability, testing, performance, DX + +**Usage:** +```bash +# Copy the workflow file +cp examples/github-actions/claude-pr-auto-review.yml .github/workflows/ + +# Open a PR - Claude will automatically review it +``` + +--- + +### 2. Security Review (`claude-security-review.yml`) + +Runs a focused security scan and comments findings directly on the PR. + +**Features:** +- Security-focused analysis on every PR +- Identifies potential vulnerabilities +- OWASP Top 10 considerations +- Posts findings as PR comments + +**Configuration:** +```yaml +# Optional parameters in the workflow file: +exclude-directories: "docs,examples" # Skip certain directories +claudecode-timeout: "20" # Timeout in minutes +claude-model: "claude-3-5-sonnet-20240620" # Model to use +``` + +**Usage:** +```bash +# Copy the workflow file +cp examples/github-actions/claude-security-review.yml .github/workflows/ + +# Every PR will be automatically scanned for security issues +``` + +--- + +### 3. Issue Triage (`claude-issue-triage.yml`) + +When a new issue opens, Claude proposes labels/severity and posts a tidy triage comment. + +**Features:** +- Automatic issue classification +- Label suggestions +- Severity assessment (low, medium, high, critical) +- Duplicate detection +- Markdown triage comment + +**Auto-apply Labels (Optional):** +To automatically apply suggested labels, edit the workflow file and change: +```yaml +- name: Apply labels (optional) + if: ${{ false }} # Change to true to auto-apply labels +``` + +**Usage:** +```bash +# Copy the workflow file +cp examples/github-actions/claude-issue-triage.yml .github/workflows/ + +# Open a new issue - Claude will automatically triage it +``` + +--- + +## Customization + +### Model Selection +Set `CLAUDE_MODEL` or `claude-model` parameter in workflows: +```yaml +env: + CLAUDE_MODEL: claude-3-5-sonnet-20240620 +``` + +### Permissions +Each workflow declares minimal required permissions: +- `pull-requests: write` for PR reviews +- `issues: write` for issue triage +- `contents: read` for reading repository content + +Adjust only if your organization requires stricter policies. + +### Scope Filtering +Use `paths:` filters to limit when workflows run: +```yaml +on: + pull_request: + paths: + - 'src/**' + - '!docs/**' +``` + +## Troubleshooting + +**No comments appear on PRs:** +- Verify the Claude GitHub App is installed +- Check workflow has `pull-requests: write` permission + +**403 when applying labels:** +- Ensure the job has `issues: write` permission +- Verify `GITHUB_TOKEN` has access to this repo + +**Anthropic API errors:** +- Confirm `ANTHROPIC_API_KEY` is set at repository level +- Check the key is not expired + +**YAML syntax errors:** +- Validate spacing: two spaces per nesting level, no tabs +- Use a YAML validator: [yamllint.com](https://www.yamllint.com/) + +## Advanced Usage + +### Combining Workflows +Run multiple workflows together for comprehensive automation: +- PR Review + Security Review on every PR +- Issue Triage + Auto-labeling for new issues + +### Custom Prompts +Edit the `direct_prompt` section in workflows to customize Claude's focus: +```yaml +direct_prompt: | + Review this PR focusing on: + 1. TypeScript type safety + 2. React performance patterns + 3. Accessibility compliance + 4. Test coverage +``` + +### Integration with Other Actions +Combine with existing workflows: +```yaml +jobs: + tests: + runs-on: ubuntu-latest + steps: + - name: Run tests + run: npm test + + claude-review: + needs: tests # Run after tests pass + runs-on: ubuntu-latest + steps: + - uses: anthropics/claude-code-action@main + # ... +``` + +## Cost Considerations + +These workflows consume Anthropic API credits: +- **PR Review**: ~$0.10-$0.50 per review (depending on diff size) +- **Security Review**: ~$0.20-$0.80 per scan +- **Issue Triage**: ~$0.05-$0.20 per issue + +**Tips to reduce costs:** +- Use `paths:` filters to skip docs/config changes +- Set conditions: `if: github.event.pull_request.draft == false` +- Review logs and adjust model selection + +## Examples in This Directory + +``` +examples/github-actions/ +โ”œโ”€โ”€ README.md # This file +โ”œโ”€โ”€ claude-pr-auto-review.yml # Auto PR review workflow +โ”œโ”€โ”€ claude-security-review.yml # Security scanning workflow +โ””โ”€โ”€ claude-issue-triage.yml # Issue triage workflow +``` + +## Resources + +- [Claude Code Documentation](https://claude.ai/code) +- [GitHub Actions Documentation](https://docs.github.com/en/actions) +- [Anthropic API Documentation](https://docs.anthropic.com/) +- [Claude GitHub App](https://github.com/apps/claude) + +## License + +These workflows are provided as examples. Adapt them to your needs. diff --git a/examples/github-actions/claude-issue-triage.yml b/examples/github-actions/claude-issue-triage.yml new file mode 100644 index 0000000..6602a38 --- /dev/null +++ b/examples/github-actions/claude-issue-triage.yml @@ -0,0 +1,101 @@ +name: Claude Issue Triage +on: + issues: + types: [opened, edited, reopened] + +permissions: + contents: read + issues: write + +jobs: + triage: + runs-on: ubuntu-latest + env: + CLAUDE_MODEL: claude-3-5-sonnet-20240620 + steps: + - name: Collect context & similar issues + id: gather + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + TITLE="${{ github.event.issue.title }}" + BODY="${{ github.event.issue.body }}" + # naive similar search by title words + Q=$(echo "$TITLE" | tr -dc '[:alnum:] ' | awk '{print $1" "$2" "$3" "$4}') + gh api -X GET search/issues -f q="repo:${{ github.repository }} is:issue $Q" -f per_page=5 > similars.json + echo "$TITLE" > title.txt + echo "$BODY" > body.txt + + - name: Ask Claude for triage JSON + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + cat > payload.json << 'JSON' + { + "model": "${{ env.CLAUDE_MODEL }}", + "max_tokens": 1500, + "system": "You are a pragmatic triage engineer. Be specific, cautious with duplicates.", + "messages": [{ + "role": "user", + "content": [{ + "type":"text", + "text":"Given the issue and similar candidates, produce STRICT JSON with keys: labels (array of strings), severity (one of: low, medium, high, critical), duplicate_url (string or empty), comment_markdown (string brief). Do not include any extra keys." + }, + {"type":"text","text":"Issue title:\n"}, + {"type":"text","text": "PLACEHOLDER_TITLE"}, + {"type":"text","text":"\n\nIssue body:\n"}, + {"type":"text","text": "PLACEHOLDER_BODY"}, + {"type":"text","text":"\n\nSimilar issues (JSON):\n"}, + {"type":"text","text": "PLACEHOLDER_SIMILARS"}] + }] + } + JSON + + # Inject files safely + jq --arg title "$(cat title.txt)" '.messages[0].content[2].text = $title' payload.json \ + | jq --arg body "$(cat body.txt)" '.messages[0].content[4].text = $body' \ + | jq --arg sims "$(cat similars.json)" '.messages[0].content[6].text = $sims' > payload.final.json + + curl -s https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "content-type: application/json" \ + -d @payload.final.json > out.json + jq -r '.content[0].text' out.json > triage.json || echo '{}' > triage.json + + # Validate JSON to avoid posting garbage + jq -e . triage.json >/dev/null 2>&1 || echo '{"labels":[],"severity":"low","duplicate_url":"","comment_markdown":"(triage failed to parse)"}' > triage.json + + - name: Apply labels (optional) + if: ${{ false }} # flip to `true` to auto-apply labels + uses: actions/github-script@v7 + with: + script: | + const triage = JSON.parse(require('fs').readFileSync('triage.json','utf8')) + if (triage.labels?.length) { + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: triage.labels + }) + } + + - name: Post triage comment + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs') + const triage = JSON.parse(fs.readFileSync('triage.json','utf8')) + const md = `### ๐Ÿค– Triage + - **Suggested labels:** ${triage.labels?.join(', ') || 'โ€”'} + - **Severity:** ${triage.severity || 'โ€”'} + ${triage.duplicate_url ? `- **Possible duplicate:** ${triage.duplicate_url}\n` : ''} + --- + ${triage.comment_markdown || ''}` + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: md + }) diff --git a/examples/github-actions/claude-pr-auto-review.yml b/examples/github-actions/claude-pr-auto-review.yml new file mode 100644 index 0000000..e41ce81 --- /dev/null +++ b/examples/github-actions/claude-pr-auto-review.yml @@ -0,0 +1,31 @@ +name: Auto review PRs +on: + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + +permissions: + contents: read + pull-requests: write + +jobs: + auto-review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Claude PR review + uses: anthropics/claude-code-action@main + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + # Claude will fetch the diff and leave inline comments + direct_prompt: | + Review this pull request's diff for correctness, readability, testing, performance, and DX. + Prefer specific, actionable suggestions. Use inline comments where relevant. + # GitHub tools permitted during the run: + allowed_tools: >- + mcp__github__get_pull_request_diff, + mcp__github__create_pending_pull_request_review, + mcp__github__add_comment_to_pending_review, + mcp__github__submit_pending_pull_request_review diff --git a/examples/github-actions/claude-security-review.yml b/examples/github-actions/claude-security-review.yml new file mode 100644 index 0000000..46b989d --- /dev/null +++ b/examples/github-actions/claude-security-review.yml @@ -0,0 +1,26 @@ +name: Security Review +on: + pull_request: + +permissions: + contents: read + pull-requests: write + +jobs: + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.sha || github.sha }} + fetch-depth: 2 + + - name: Claude Code Security Review + uses: anthropics/claude-code-security-review@main + with: + claude-api-key: ${{ secrets.ANTHROPIC_API_KEY }} + comment-pr: true + # Optional configuration: + # exclude-directories: "docs,examples" + # claudecode-timeout: "20" + # claude-model: "claude-3-5-sonnet-20240620"