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>
This commit is contained in:
Florian BRUNIAUX
parent
29d922af72
commit
87994bb797
6 changed files with 958 additions and 0 deletions
572
IMPROVEMENT_RECOMMENDATIONS.md
Normal file
572
IMPROVEMENT_RECOMMENDATIONS.md
Normal file
|
|
@ -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
|
||||
<div align="center">
|
||||
|
||||
| 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% |
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
**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 <key>
|
||||
claude config set <key> <val>
|
||||
claude config add <key> <vals> # 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
|
||||
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Collapsible Tables for Dense Content (30 min)
|
||||
|
||||
**What:** Use `<details>` tags or tables for long sections.
|
||||
|
||||
**Where:** Troubleshooting, environment variables, MCP server list.
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
<details>
|
||||
<summary><b>Environment Variables Reference (click to expand)</b></summary>
|
||||
|
||||
| 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` |
|
||||
...
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
**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\<you>\AppData\Roaming\npm`
|
||||
- **Node.js:** `C:\Program Files\nodejs`
|
||||
- **Claude data:** `C:\Users\<you>\.claude\`
|
||||
- **Claude config:** `C:\Users\<you>\.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.
|
||||
|
|
@ -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
|
||||
|
||||
```
|
||||
|
|
|
|||
203
examples/github-actions/README.md
Normal file
203
examples/github-actions/README.md
Normal file
|
|
@ -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.
|
||||
101
examples/github-actions/claude-issue-triage.yml
Normal file
101
examples/github-actions/claude-issue-triage.yml
Normal file
|
|
@ -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
|
||||
})
|
||||
31
examples/github-actions/claude-pr-auto-review.yml
Normal file
31
examples/github-actions/claude-pr-auto-review.yml
Normal file
|
|
@ -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
|
||||
26
examples/github-actions/claude-security-review.yml
Normal file
26
examples/github-actions/claude-security-review.yml
Normal file
|
|
@ -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"
|
||||
Loading…
Add table
Add a link
Reference in a new issue