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 <noreply@anthropic.com>
2026-01-10 15:26:18 +01:00 · 2026-01-10 15:26:18 +01:00 · 87994bb797
commit 87994bb797
parent 29d922af72
6 changed files with 958 additions and 0 deletions
--- a/examples/github-actions/README.md
+++ 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.
--- a/examples/github-actions/claude-issue-triage.yml
+++ 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
+            })
--- a/examples/github-actions/claude-pr-auto-review.yml
+++ 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
--- a/examples/github-actions/claude-security-review.yml
+++ 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"