feat(guide): comprehensive improvements - troubleshooting, CLI ref, pitfalls, DeepSeek
MAJOR ENHANCEMENTS: ## README Updates - Add pedagogical approach section emphasizing learning journey over reference manual - Reference zebbern/claude-code-guide as key inspiration for troubleshooting - Clarify guide philosophy: mentor for mastering Claude Code ## Main Guide (english-ultimate-claude-code-guide.md) ### New Sections Added: 1. **Status Overview Table** - Section completeness at a glance 2. **Section 10.3: CLI Flags Complete Reference** - 19 flags with descriptions and examples - Common flag combinations - Safety guidelines table 3. **Section 10.4: Enhanced MCP Troubleshooting** - 3 common errors with solutions (tool validation, server not found, Windows paths) - MCP debugging techniques (logs, manual testing) - One-shot health check scripts (PowerShell + Bash) - Full clean reinstall procedures (Windows + macOS/Linux) 4. **Section 9.11: Common Pitfalls & Best Practices** - Security pitfalls (Do/Don't + working hook example) - Performance pitfalls (context strategy, thinking levels) - Workflow pitfalls (prompt format template) - Collaboration pitfalls (team coordination) - Cost optimization pitfalls (model selection table) - Learning pitfalls (progressive adoption checklist) 5. **Section 11: DeepSeek Integration** - Complete setup (Windows/macOS/Linux) - Cost comparison (98% savings) - Use cases and limitations - Provider switching strategies 6. **Appendix A: File Locations Reference** - Platform-specific paths (Windows/macOS/Linux) - Quick access commands - Environment variables reference - Recommended .gitignore ## Cheatsheet (cheatsheet-en.md) - Add CLI Flags Quick Reference table - Add Common Issues Quick Fix table - Add Health Check one-liners - Add Cost Optimization section - Update to version 2.0 ## GitHub Actions (examples/github-actions/) - **claude-pr-auto-review.yml**: Comprehensive review workflow - 8 focus areas (correctness, security, performance, etc.) - Priority-based feedback (🔴🟡🟢💡) - Smart file filtering - Draft PR detection - Error handling + fallback comments - **README.md**: Update workflow #1 documentation with new features ## Documentation Quality - All examples are practical and tested - Platform-specific instructions throughout - Do/Don't format for quick scanning - Cross-references to zebbern guide where appropriate - Maintains pedagogical tone established in original guide IMPACT: Guide now provides exceptional troubleshooting resources, complete CLI reference, real-world integration patterns, and cost-effective alternatives while maintaining focus on learning journey. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
87994bb797
commit
2f84c2a769
5 changed files with 1261 additions and 22 deletions
|
|
@ -15,12 +15,19 @@ Ready-to-use GitHub Actions workflows that integrate Claude Code into your CI/CD
|
|||
|
||||
### 1. Auto PR Review (`claude-pr-auto-review.yml`)
|
||||
|
||||
**Enhanced version** with comprehensive review criteria and smart filtering.
|
||||
|
||||
Creates a structured review with inline comments as soon as a PR opens or updates.
|
||||
|
||||
**Features:**
|
||||
- Automatic code review on PR open/update
|
||||
- 8 focus areas: Correctness, Security, Performance, Readability, Maintainability, Testing, Best Practices, Breaking Changes
|
||||
- Priority-based feedback: 🔴 Critical, 🟡 Important, 🟢 Suggestion, 💡 Tip
|
||||
- Smart file filtering (skips build artifacts, lock files)
|
||||
- Skips draft PRs to save costs
|
||||
- Summary review with risk assessment
|
||||
- Error handling and fallback notifications
|
||||
- Inline comments on specific lines
|
||||
- Reviews for correctness, readability, testing, performance, DX
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
|
|
@ -30,6 +37,17 @@ cp examples/github-actions/claude-pr-auto-review.yml .github/workflows/
|
|||
# Open a PR - Claude will automatically review it
|
||||
```
|
||||
|
||||
**Customization:**
|
||||
Add project-specific context by uncommenting the `append_system_prompt` section:
|
||||
```yaml
|
||||
append_system_prompt: |
|
||||
Project conventions:
|
||||
- Use TypeScript strict mode
|
||||
- Follow functional programming patterns
|
||||
- All functions must have JSDoc comments
|
||||
- Test coverage must be >80%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Security Review (`claude-security-review.yml`)
|
||||
|
|
|
|||
|
|
@ -1,31 +1,155 @@
|
|||
name: Auto review PRs
|
||||
name: Claude PR Auto-Review
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened, ready_for_review]
|
||||
# Skip draft PRs to save costs
|
||||
branches:
|
||||
- main
|
||||
- develop
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
issues: write
|
||||
|
||||
jobs:
|
||||
auto-review:
|
||||
claude-review:
|
||||
# Skip if PR is in draft mode
|
||||
if: github.event.pull_request.draft == false
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 1
|
||||
timeout-minutes: 10
|
||||
|
||||
- name: Claude PR review
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # Full history for better context
|
||||
ref: ${{ github.event.pull_request.head.sha }}
|
||||
|
||||
- name: Get changed files
|
||||
id: changed-files
|
||||
uses: tj-actions/changed-files@v41
|
||||
with:
|
||||
files: |
|
||||
**/*.ts
|
||||
**/*.tsx
|
||||
**/*.js
|
||||
**/*.jsx
|
||||
**/*.py
|
||||
**/*.java
|
||||
**/*.go
|
||||
files_ignore: |
|
||||
**/dist/**
|
||||
**/build/**
|
||||
**/*.min.js
|
||||
**/node_modules/**
|
||||
**/*.lock
|
||||
package-lock.json
|
||||
yarn.lock
|
||||
|
||||
- name: Claude Code PR Review
|
||||
uses: anthropics/claude-code-action@main
|
||||
if: steps.changed-files.outputs.any_changed == 'true'
|
||||
with:
|
||||
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
# Claude will fetch the diff and leave inline comments
|
||||
|
||||
# Use Sonnet for cost-effectiveness (can upgrade to Opus for complex PRs)
|
||||
model: claude-sonnet-4-20250514
|
||||
|
||||
# Comprehensive review prompt
|
||||
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:
|
||||
You are conducting a thorough code review of this pull request.
|
||||
|
||||
**Context:**
|
||||
- PR Title: ${{ github.event.pull_request.title }}
|
||||
- PR Description: ${{ github.event.pull_request.body }}
|
||||
- Author: ${{ github.event.pull_request.user.login }}
|
||||
- Changed files: ${{ steps.changed-files.outputs.all_changed_files }}
|
||||
|
||||
**Review Focus Areas:**
|
||||
|
||||
1. **Correctness**: Logic errors, edge cases, potential bugs
|
||||
2. **Security**: Vulnerabilities, input validation, authentication/authorization
|
||||
3. **Performance**: Inefficient algorithms, unnecessary operations, memory leaks
|
||||
4. **Readability**: Code clarity, naming conventions, comments
|
||||
5. **Maintainability**: Code duplication, modularity, coupling
|
||||
6. **Testing**: Test coverage, test quality, missing test cases
|
||||
7. **Best Practices**: Language idioms, framework conventions, design patterns
|
||||
8. **Breaking Changes**: API compatibility, migration requirements
|
||||
|
||||
**Instructions:**
|
||||
|
||||
- Fetch the PR diff and analyze all changes carefully
|
||||
- Leave inline comments on specific lines where issues are found
|
||||
- Use this format for inline comments:
|
||||
- 🔴 **Critical**: Must fix before merge (security, bugs, breaking changes)
|
||||
- 🟡 **Important**: Should fix (performance, maintainability)
|
||||
- 🟢 **Suggestion**: Nice to have (style, optimization)
|
||||
- 💡 **Tip**: Educational comment (best practice, alternative approach)
|
||||
|
||||
- For each issue:
|
||||
1. Explain what's wrong and why it matters
|
||||
2. Suggest specific code improvements
|
||||
3. If relevant, provide example code
|
||||
|
||||
- Also provide a summary review comment with:
|
||||
- Overall assessment (Approve / Request Changes / Comment)
|
||||
- Key strengths of the PR
|
||||
- Critical issues requiring attention
|
||||
- Estimated risk level (Low / Medium / High)
|
||||
|
||||
- Be constructive and respectful
|
||||
- Prioritize clarity and actionability over quantity
|
||||
- If code looks good, acknowledge what was done well
|
||||
|
||||
**Tools Available:**
|
||||
Use the GitHub MCP tools to:
|
||||
1. Fetch PR diff
|
||||
2. Add inline comments to pending review
|
||||
3. Submit the review with appropriate status
|
||||
|
||||
Begin your review now.
|
||||
|
||||
# GitHub MCP tools for PR interaction
|
||||
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
|
||||
mcp__github__submit_pending_pull_request_review,
|
||||
mcp__github__get_pull_request,
|
||||
mcp__github__list_commits,
|
||||
Read,
|
||||
Glob
|
||||
|
||||
# Optional: Add project context
|
||||
# append_system_prompt: |
|
||||
# Project conventions:
|
||||
# - Use TypeScript strict mode
|
||||
# - Follow functional programming patterns
|
||||
# - All functions must have JSDoc comments
|
||||
# - Test coverage must be >80%
|
||||
|
||||
- name: Comment on skipped review
|
||||
if: steps.changed-files.outputs.any_changed == 'false'
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
github.rest.issues.createComment({
|
||||
issue_number: context.issue.number,
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
body: '✅ **No reviewable code changes detected** - Only non-code files were modified (build artifacts, dependencies, etc.)'
|
||||
})
|
||||
|
||||
- name: Handle review failure
|
||||
if: failure()
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
github.rest.issues.createComment({
|
||||
issue_number: context.issue.number,
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
body: '⚠️ **Claude Code review failed** - Check the Actions log for details. A human reviewer should review this PR.'
|
||||
})
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue