marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(guide): comprehensive improvements - troubleshooting, CLI ref, pitfalls, DeepSeek

Browse source 
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 2026-01-10 15:47:26 +01:00
parent 87994bb797
commit 2f84c2a769
5 changed files with 1261 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

17
README.md
View file

@ -23,11 +23,26 @@
## About This Guide
### Our Pedagogical Approach
Unlike reference manuals that simply list features, **this guide follows a learning journey** designed to take you from beginner to power user. We focus on:
- **Understanding why** before diving into how
- **Real-world patterns** you can use immediately
- **Progressive complexity** — start simple, master advanced techniques at your pace
- **Practical workflows** over theoretical concepts
Think of this as your **mentor for mastering Claude Code** — not just documentation.
### Origins & Philosophy
This guide is the result of **several months of daily practice and research** with Claude Code, Anthropic's AI coding assistant CLI. Whether you're exploring agentic development, LLM-powered coding workflows, or AI pair programming, this resource covers everything from basic setup to advanced MCP server orchestration.
I don't claim to be an "expert" — I'm simply sharing what I've learned along the way, humbly hoping to help my peers and evangelize good practices in AI-assisted development.
A significant source of inspiration for this work was [Claudelog.com](https://claudelog.com/), which I highly recommend for anyone wanting to go deeper.
**Key inspirations for this work:**
- [Claudelog.com](https://claudelog.com/) — Excellent tips, patterns & tutorials (highly recommended)
- [zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide) — Comprehensive reference & troubleshooting guide with cybersecurity focus
**Important note**: This guide was largely generated with the help of AI. As such, it likely contains errors, inaccuracies, or outdated information. I would be delighted to receive any feedback, corrections, or — even better — pull requests to improve it. Don't hesitate to [open an issue](../../issues) or submit a PR!

66
cheatsheet-en.md
View file

@ -1,11 +1,13 @@
# Claude Code Cheatsheet
**1 printable page** - Daily essentials
**1 printable page** - Daily essentials for maximum productivity
**Author**: Florian BRUNIAUX | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
**Written with**: Claude (Anthropic)
**Version**: 2.0 | **Last Updated**: January 2025
---
## Essential Commands
@ -244,6 +246,22 @@ VERIFY: Empty email shows error, invalid format shows error
---
## CLI Flags Quick Reference
| Flag | Usage |
|------|-------|
| `-p "query"` | Non-interactive mode |
| `--model sonnet` | Change model |
| `--add-dir ../lib` | Add directory |
| `--permission-mode plan` | Plan mode |
| `--dangerously-skip-permissions` | Auto-accept (⚠️ use carefully) |
| `--debug` | Debug output |
| `--mcp-debug` | Debug MCP servers |
| `--allowedTools "Edit,Read"` | Whitelist tools |
| `--disallowedTools "WebFetch"` | Blacklist tools |
---
## Debug Commands
```bash
@ -251,7 +269,7 @@ claude --version # Version
claude doctor # Diagnostic
claude --debug # Verbose mode
claude --mcp-debug # Debug MCPs
/mcp # MCP status
/mcp # MCP status (inside Claude)
```
---
@ -299,15 +317,51 @@ Deep analysis → Use --think or --ultrathink
---
## Common Issues Quick Fix
| Problem | Solution |
|---------|----------|
| "Command not found" | Check PATH, reinstall npm global |
| Context too high (>70%) | `/compact` immediately |
| Slow responses | `/compact` or `/clear` |
| MCP not working | `claude mcp list`, check config |
| Permission denied | Check `settings.local.json` |
| Hook blocking | Check hook exit code, review logic |
**Health Check Script** (save & run):
```bash
# macOS/Linux
which claude && claude doctor && claude mcp list
# Windows PowerShell
where.exe claude; claude doctor; claude mcp list
```
---
## Cost Optimization
| Model | Use For | Cost |
|-------|---------|------|
| Haiku | Simple fixes, reviews | $ |
| Sonnet | Most development | $$ |
| Opus | Architecture, complex bugs | $$$ |
| OpusPlan | Plan (Opus) + Execute (Sonnet) | $$ |
**Tip**: Use `--add-dir` to load only needed directories (saves tokens)
---
## Resources
- **Official docs**: [docs.anthropic.com/claude-code](https://docs.anthropic.com/en/docs/claude-code)
- **Inspired by**: [Claudelog.com](https://claudelog.com/) - Advanced tips & patterns
- **Full guide**: `english-ultimate-claude-code-guide.md`
- **Project memory**: `CLAUDE.md` at project root
- **Advanced guide**: [Claudelog.com](https://claudelog.com/) - Tips & patterns
- **Full guide**: `english-ultimate-claude-code-guide.md` (this repo)
- **Project memory**: Create `CLAUDE.md` at project root
- **DeepSeek (cost-effective)**: Configure via `ANTHROPIC_BASE_URL`
---
**Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
*Last updated: January 2025 | Version 1.0*
*Last updated: January 2025 | Version 2.0*

1032
english-ultimate-claude-code-guide.md
View file

File diff suppressed because it is too large Load diff

20
examples/github-actions/README.md
View file

@ -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`)

148
examples/github-actions/claude-pr-auto-review.yml
View file

@ -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.'
})