refactor: restructure repo into thematic directories v3.1.0
Major repository reorganization for improved navigation: New directory structure: - guide/ - Core documentation (ultimate-guide, cheatsheet, adoption) - tools/ - Interactive utilities (audit, onboarding, mobile-access) - machine-readable/ - LLM/AI consumption (reference.yaml, llms.txt) - exports/ - Generated outputs (PDFs) Changes: - Move 10 files to thematic directories with cleaner names - Create README.md index for each new directory - Update 150+ internal links across all documentation - Add "Repository Structure" section to main README - Remove redundant npm install command from README header - Remove unverified cost estimate from prerequisites - Fix broken anchor link (#-quick-start-15-minutes) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
06b9fe2c51
commit
bc07651cdf
35 changed files with 450 additions and 282 deletions
21
guide/README.md
Normal file
21
guide/README.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
# Guide Documentation
|
||||
|
||||
Core documentation for mastering Claude Code.
|
||||
|
||||
## Contents
|
||||
|
||||
| File | Description | Time |
|
||||
|------|-------------|------|
|
||||
| [ultimate-guide.md](./ultimate-guide.md) | Complete reference covering all Claude Code features | ~3 hours |
|
||||
| [cheatsheet.md](./cheatsheet.md) | 1-page printable quick reference | 5 min |
|
||||
| [adoption-approaches.md](./adoption-approaches.md) | Implementation strategies for teams | 15 min |
|
||||
|
||||
## Recommended Reading Order
|
||||
|
||||
1. **New users**: Start with Quick Start section in `ultimate-guide.md`
|
||||
2. **Daily reference**: Print `cheatsheet.md`
|
||||
3. **Team leads**: Read `adoption-approaches.md` for rollout strategies
|
||||
|
||||
---
|
||||
|
||||
*Back to [main README](../README.md)*
|
||||
366
guide/adoption-approaches.md
Normal file
366
guide/adoption-approaches.md
Normal file
|
|
@ -0,0 +1,366 @@
|
|||
# Choosing Your Adoption Approach
|
||||
|
||||
> **Disclaimer**: Claude Code is young (~1 year). Nobody has definitive answers yet — including this guide. These are starting points based on observed patterns, not proven best practices. Adapt heavily to your context.
|
||||
|
||||
---
|
||||
|
||||
## What We Don't Know Yet
|
||||
|
||||
Before diving in, here's what remains genuinely uncertain:
|
||||
|
||||
- **Optimal CLAUDE.md size** — Some teams thrive with 10 lines, others with 100. No clear winner.
|
||||
- **Team adoption patterns** — Whether top-down standardization beats organic adoption is unproven.
|
||||
- **Context management thresholds** — The 70%/90% numbers are heuristics, not science.
|
||||
- **ROI of advanced features** — MCP servers, hooks, agents — unclear when the setup cost pays off.
|
||||
|
||||
If anyone tells you they've figured this out, they're ahead of the field or overconfident.
|
||||
|
||||
---
|
||||
|
||||
## Starting Points (Not Prescriptions)
|
||||
|
||||
| Your Context | One Approach to Try |
|
||||
|--------------|---------------------|
|
||||
| Limited setup time | **Turnkey** — minimal config, iterate based on friction |
|
||||
| Solo developer | **Autonomous** — learn concepts first, configure when needed |
|
||||
| Small team (4-10) | **Hybrid** — shared basics + room for personal preferences |
|
||||
| Larger team (10+) | **Turnkey + docs** — consistency matters more at scale |
|
||||
|
||||
These are hypotheses. Your mileage will vary.
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Starting Claude Code?
|
||||
│
|
||||
├─ Need to ship today?
|
||||
│ └─ YES → Turnkey Quickstart
|
||||
│ └─ NO ↓
|
||||
│
|
||||
├─ Team needs shared conventions?
|
||||
│ └─ YES → Turnkey + document what matters to you
|
||||
│ └─ NO ↓
|
||||
│
|
||||
├─ Want to understand before configuring?
|
||||
│ └─ YES → Autonomous Learning Path
|
||||
│ └─ NO → Turnkey, adjust as you go
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Turnkey Quickstart
|
||||
|
||||
### Step 1: Create Minimal Config
|
||||
|
||||
```bash
|
||||
mkdir -p .claude
|
||||
```
|
||||
|
||||
Create `.claude/CLAUDE.md`:
|
||||
|
||||
```markdown
|
||||
# Project: [your-project-name]
|
||||
|
||||
## Stack
|
||||
- Runtime: [Node 20 / Python 3.11 / etc.]
|
||||
- Framework: [Next.js / FastAPI / etc.]
|
||||
|
||||
## Commands
|
||||
- Test: `npm test` or `pytest`
|
||||
- Lint: `npm run lint` or `ruff check`
|
||||
|
||||
## Convention
|
||||
- [One rule you care most about, e.g., "TypeScript strict mode required"]
|
||||
```
|
||||
|
||||
### Step 2: Verify Setup
|
||||
|
||||
```bash
|
||||
claude
|
||||
```
|
||||
|
||||
Then ask:
|
||||
```
|
||||
What's this project's test command?
|
||||
```
|
||||
|
||||
**Pass**: Returns your configured command.
|
||||
**Fail**: CLAUDE.md not loaded — check path is `.claude/CLAUDE.md` or `./CLAUDE.md`
|
||||
|
||||
### Step 3: First Real Task
|
||||
|
||||
```bash
|
||||
claude "Review the README and suggest improvements"
|
||||
```
|
||||
|
||||
Claude should reference your stack and conventions automatically.
|
||||
|
||||
**Done.** Add more config only when you hit friction.
|
||||
|
||||
---
|
||||
|
||||
## Autonomous Learning Path
|
||||
|
||||
If you prefer understanding before configuring, here's a progressive approach. No time estimates — speed depends on your familiarity with AI tools.
|
||||
|
||||
### Phase 1: Mental Model
|
||||
|
||||
**Goal**: Understand how Claude Code operates before adding config.
|
||||
|
||||
1. Read [Section 5: Mental Model](./ultimate-guide.md) (line 1675)
|
||||
2. Core concept: Claude works in a loop — prompt → plan → execute → verify
|
||||
3. **Try it**: Complete a few real tasks with zero config. Notice where friction appears.
|
||||
|
||||
### Phase 2: Context Management
|
||||
|
||||
**Goal**: Understand the main constraint of the tool.
|
||||
|
||||
1. Read [Context Management](./ultimate-guide.md) (line 944)
|
||||
2. The general idea (exact thresholds vary by use case):
|
||||
- Low usage: work freely
|
||||
- Medium usage: be more selective
|
||||
- High usage: consider `/compact`
|
||||
- Near limit: `/clear` to reset
|
||||
3. **Try it**: Check `/status` periodically. See how your usage patterns develop.
|
||||
|
||||
### Phase 3: Memory Files
|
||||
|
||||
**Goal**: Give Claude project context.
|
||||
|
||||
1. Read [Memory Files](./ultimate-guide.md) (line 2218)
|
||||
2. Precedence: project `.claude/CLAUDE.md` > global `~/.claude/CLAUDE.md`
|
||||
3. **Try it**: Create a minimal CLAUDE.md, test if Claude picks it up.
|
||||
|
||||
### Phase 4: Extensions (when friction appears)
|
||||
|
||||
Add complexity only when you hit real problems:
|
||||
|
||||
| Friction | Possible Solution | Reference |
|
||||
|----------|-------------------|-----------|
|
||||
| Repeating same task often | Consider an agent | [Agent Template](./ultimate-guide.md) line 2793 |
|
||||
| Security concern | Consider a hook | [Hook Templates](./ultimate-guide.md) line 4172 |
|
||||
| Need external tool access | Consider MCP | [MCP Config](./ultimate-guide.md) line 4771 |
|
||||
| AI repeats same mistake | Add a specific rule | Start with one line, not ten |
|
||||
|
||||
Whether these solutions are worth the setup cost depends on your context.
|
||||
|
||||
---
|
||||
|
||||
## Sanity Checks
|
||||
|
||||
These are signals that things are working, not rigid milestones.
|
||||
|
||||
### Basic Setup Works
|
||||
|
||||
```bash
|
||||
claude --version # Responds with version
|
||||
claude /status # Shows context info
|
||||
claude /mcp # Lists MCP servers (may be empty)
|
||||
```
|
||||
|
||||
If these fail: installation issue — try `claude doctor`.
|
||||
|
||||
### Config Is Being Read
|
||||
|
||||
**Test**: Ask Claude "What's the test command for this project?"
|
||||
|
||||
If it returns your configured command, CLAUDE.md is loaded. If not, check the path.
|
||||
|
||||
### You're Managing Context
|
||||
|
||||
**Signal**: You've noticed when context gets high and acted on it.
|
||||
|
||||
This develops naturally with use. If you never think about context, either you're not using Claude intensively, or you're ignoring signals that might matter.
|
||||
|
||||
### Extensions Feel Useful (or not needed)
|
||||
|
||||
**Signal**: You've either created something (agent, hook, command) that helps, or you haven't needed to.
|
||||
|
||||
Both are fine. Extensions are optional — don't add them just to have them.
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
These patterns seem problematic based on observations, though individual experiences vary.
|
||||
|
||||
| Pattern | What happens | Alternative |
|
||||
|---------|--------------|-------------|
|
||||
| **Large copied config** | Rules get ignored, unclear what matters | Start small, add based on friction |
|
||||
| **Over-engineering setup** | Time spent configuring instead of coding | Use templates as starting point |
|
||||
| **No shared conventions** | Team members diverge, onboarding confusion | Document a few essentials |
|
||||
| **Everything enabled immediately** | Complexity without clear benefit | Enable features when you need them |
|
||||
|
||||
These aren't universal truths — some teams thrive with large configs or full feature sets.
|
||||
|
||||
---
|
||||
|
||||
## Team Size Considerations
|
||||
|
||||
These are starting points, not rules. Team dynamics matter more than headcount.
|
||||
|
||||
### Solo / Small Team (2-3)
|
||||
|
||||
**Typical structure**:
|
||||
```
|
||||
./CLAUDE.md # Project basics, committed
|
||||
~/.claude/CLAUDE.md # Personal preferences
|
||||
```
|
||||
|
||||
**What might work**:
|
||||
- Short project CLAUDE.md with stack and main commands
|
||||
- Personal config for model preferences, flags
|
||||
- Extensions only if you find yourself repeating tasks often
|
||||
|
||||
**Watch for**: Over-engineering. If you're spending more time on config than coding, step back.
|
||||
|
||||
### Medium Team (4-10)
|
||||
|
||||
**Typical structure**:
|
||||
```
|
||||
./CLAUDE.md # Team conventions (committed)
|
||||
./.claude/settings.json # Shared hooks (committed)
|
||||
~/.claude/CLAUDE.md # Individual preferences (not committed)
|
||||
```
|
||||
|
||||
**What might work**:
|
||||
- Shared conventions that the team actually follows
|
||||
- Security hooks if relevant to your context
|
||||
- Room for personal preferences
|
||||
|
||||
**One way to split things**:
|
||||
|
||||
| Shared (repo) | Personal (~/.claude) |
|
||||
|---------------|----------------------|
|
||||
| Test/lint commands | Model preferences |
|
||||
| Project conventions | Custom agents |
|
||||
| Commit format | Flag defaults |
|
||||
|
||||
**Watch for**: Conventions that exist on paper but aren't followed.
|
||||
|
||||
### Larger Team (10+)
|
||||
|
||||
**Typical structure**:
|
||||
```
|
||||
./CLAUDE.md # Documented, committed
|
||||
./.claude/settings.json # Standard hooks, committed
|
||||
./.claude/agents/ # Shared agents, committed
|
||||
~/.claude/CLAUDE.md # Personal additions
|
||||
```
|
||||
|
||||
**What might work**:
|
||||
- Documented conventions with rationale
|
||||
- Standardized hooks across the team
|
||||
- Onboarding that covers basics like `/status`
|
||||
|
||||
**Watch for**: Config drift. Without some coordination, setups diverge over time. Whether that matters depends on your team.
|
||||
|
||||
---
|
||||
|
||||
## Common Situations
|
||||
|
||||
### "I'm evaluating Claude Code for my team"
|
||||
|
||||
**Quick test approach**:
|
||||
1. Install: `npm i -g @anthropic-ai/claude-code`
|
||||
2. Run in an existing project: `claude`
|
||||
3. Try a real task: `claude "Analyze this codebase architecture"`
|
||||
4. Check `/status` to understand token usage
|
||||
|
||||
**Questions to answer**:
|
||||
- Does Claude understand your stack without config?
|
||||
- Does a minimal CLAUDE.md improve results?
|
||||
- Can your team learn context management basics?
|
||||
|
||||
Consider skipping advanced features (MCP, hooks, agents) during initial evaluation.
|
||||
|
||||
### "My team disagrees on configuration"
|
||||
|
||||
**One way to think about it**:
|
||||
|
||||
| Layer | Typical owner | Typical content |
|
||||
|-------|---------------|-----------------|
|
||||
| Repo CLAUDE.md | Team decision | Stack, commands, core conventions |
|
||||
| Repo hooks | Security-minded team members | Guardrails if needed |
|
||||
| Personal ~/.claude | Individual | Preferences, personal agents |
|
||||
|
||||
How you resolve conflicts depends on your team culture. Some teams vote, some defer to tech leads, some let individuals diverge.
|
||||
|
||||
### "Claude keeps making the same mistake"
|
||||
|
||||
**Tempting**: Add many rules to prevent it.
|
||||
|
||||
**Often better**: Add one specific rule, test if it works, iterate.
|
||||
|
||||
```markdown
|
||||
## [Specific issue]
|
||||
When doing [X], avoid [specific mistake].
|
||||
Instead: [correct approach]
|
||||
```
|
||||
|
||||
If the rule doesn't help, it might be too vague. Make it more specific or reconsider if rules are the right solution.
|
||||
|
||||
### "I inherited a large CLAUDE.md"
|
||||
|
||||
**One approach**:
|
||||
1. Ask Claude to summarize what the CLAUDE.md says
|
||||
2. Compare to what the team actually does
|
||||
3. Remove rules that aren't followed or referenced
|
||||
4. Keep what's genuinely useful
|
||||
|
||||
**Heuristic**: If you can't explain why a rule exists, consider removing it.
|
||||
|
||||
### "When should I add more complexity?"
|
||||
|
||||
There's no universal answer. Some signals that might suggest it:
|
||||
|
||||
| Signal | Possible response |
|
||||
|--------|-------------------|
|
||||
| Repeating the same prompt often | Consider a command |
|
||||
| Security concern | Consider a hook |
|
||||
| Need external tool access | Consider MCP |
|
||||
| Same questions from team | Consider documentation |
|
||||
|
||||
But also: maybe you don't need more complexity. Simple setups work for many teams.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Useful Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|------------|----------------------------------|
|
||||
| `/status` | Check context usage |
|
||||
| `/compact` | Compress context when it's high |
|
||||
| `/clear` | Reset context entirely |
|
||||
| `/plan` | Enter planning mode |
|
||||
| `/model` | Switch between models |
|
||||
|
||||
How often you use these depends on your workflow.
|
||||
|
||||
### Model Costs (Relative)
|
||||
|
||||
| Model | Cost | Typical use cases |
|
||||
|--------|------|--------------------------------|
|
||||
| Haiku | $ | Simple tasks, quick responses |
|
||||
| Sonnet | $$ | General development |
|
||||
| Opus | $$$ | Complex analysis, architecture |
|
||||
|
||||
Most people start with Sonnet. Adjust based on your experience.
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
- [Personalized Onboarding](../tools/onboarding-prompt.md) — Interactive setup
|
||||
- [Setup Audit](../tools/audit-prompt.md) — Diagnose configuration issues
|
||||
- [Examples Library](../examples/README.md) — Templates to adapt
|
||||
- [Main Guide](./ultimate-guide.md) — Full reference
|
||||
- [Reference YAML](../machine-readable/reference.yaml) — Condensed lookup
|
||||
|
||||
---
|
||||
|
||||
*This guide reflects current observations, not proven best practices. The field is young — adapt heavily to your context. Feedback welcome: [CONTRIBUTING.md](../CONTRIBUTING.md)*
|
||||
381
guide/cheatsheet.md
Normal file
381
guide/cheatsheet.md
Normal file
|
|
@ -0,0 +1,381 @@
|
|||
# Claude Code Cheatsheet
|
||||
|
||||
**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**: 3.1.0 | **Last Updated**: January 2026
|
||||
|
||||
---
|
||||
|
||||
## Essential Commands
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `/help` | Contextual help |
|
||||
| `/clear` | Reset conversation |
|
||||
| `/compact` | Free up context |
|
||||
| `/status` | Session state + context usage |
|
||||
| `/context` | Detailed token breakdown |
|
||||
| `/plan` | Enter Plan Mode (no changes) |
|
||||
| `/execute` | Exit Plan Mode (apply changes) |
|
||||
| `/model` | Switch model (sonnet/opus/opusplan) |
|
||||
| `/exit` | Quit (or Ctrl+D) |
|
||||
|
||||
---
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Shift+Tab` | Cycle permission modes |
|
||||
| `Esc` × 2 | Rewind (undo) |
|
||||
| `Ctrl+C` | Interrupt |
|
||||
| `Ctrl+R` | Retry last operation |
|
||||
| `Ctrl+L` | Clear screen (keeps context) |
|
||||
| `Tab` | Autocomplete |
|
||||
| `Shift+Enter` | New line |
|
||||
| `Ctrl+D` | Exit |
|
||||
|
||||
---
|
||||
|
||||
## File References
|
||||
|
||||
```
|
||||
@path/to/file.ts → Reference a file
|
||||
@agent-name → Call an agent
|
||||
!shell-command → Run shell command
|
||||
```
|
||||
|
||||
| IDE | Shortcut |
|
||||
|-----|----------|
|
||||
| VS Code | `Alt+K` |
|
||||
| JetBrains | `Cmd+Option+K` |
|
||||
|
||||
---
|
||||
|
||||
## Permission Modes
|
||||
|
||||
| Mode | Editing | Execution |
|
||||
|------|---------|-----------|
|
||||
| Default | Asks | Asks |
|
||||
| Auto-accept | Auto | Asks |
|
||||
| Plan Mode | ❌ | ❌ |
|
||||
|
||||
**Shift+Tab** to switch modes
|
||||
|
||||
---
|
||||
|
||||
## Memory & Settings (2 levels)
|
||||
|
||||
| Level | macOS/Linux | Windows | Scope | Git |
|
||||
|-------|-------------|---------|-------|-----|
|
||||
| **Project** | `.claude/` | `.claude\` | Team | ✅ |
|
||||
| **Personal** | `~/.claude/` | `%USERPROFILE%\.claude\` | You (all projects) | ❌ |
|
||||
|
||||
**Priority**: Project overrides Personal
|
||||
|
||||
| File | Where | Usage |
|
||||
|------|-------|-------|
|
||||
| `CLAUDE.md` | Project root | Team memory (instructions) |
|
||||
| `settings.json` | `.claude/` | Team settings (hooks) |
|
||||
| `settings.local.json` | `.claude/` | Your setting overrides |
|
||||
| `CLAUDE.md` | `~/.claude/` (Win: `%USERPROFILE%\.claude\`) | Personal memory |
|
||||
|
||||
---
|
||||
|
||||
## .claude/ Folder Structure
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── CLAUDE.md # Local memory (gitignored)
|
||||
├── settings.json # Hooks (committed)
|
||||
├── settings.local.json # Permissions (not committed)
|
||||
├── agents/ # Custom agents
|
||||
├── commands/ # Slash commands
|
||||
├── hooks/ # Event scripts
|
||||
├── rules/ # Auto-loaded rules
|
||||
└── skills/ # Knowledge modules
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Typical Workflow
|
||||
|
||||
```
|
||||
1. Start session → claude
|
||||
2. Check context → /status
|
||||
3. Plan Mode → Shift+Tab × 2 (for complex tasks)
|
||||
4. Describe task → Clear, specific prompt
|
||||
5. Review changes → Always read the diff!
|
||||
6. Accept/Reject → y/n
|
||||
7. Verify → Run tests
|
||||
8. Commit → When task complete
|
||||
9. /compact → When context >70%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context Management (CRITICAL)
|
||||
|
||||
### Statusline
|
||||
|
||||
```
|
||||
Model: Sonnet | Ctx: 89.5k | Cost: $2.11 | Ctx(u): 56.0%
|
||||
```
|
||||
**Watch `Ctx(u):`** → >70% = `/compact`, >85% = `/clear`
|
||||
|
||||
**Enhanced statusline ([ccstatusline](https://github.com/sirmalloc/ccstatusline)):** Add to `~/.claude/settings.json`:
|
||||
```json
|
||||
{ "statusLine": { "type": "command", "command": "npx -y ccstatusline@latest", "padding": 0 } }
|
||||
```
|
||||
|
||||
### Actions by Symptom
|
||||
|
||||
| Sign | Action |
|
||||
|------|--------|
|
||||
| Short responses | `/compact` |
|
||||
| Frequent forgetting | `/clear` |
|
||||
| >70% context | `/compact` |
|
||||
| Task complete | `/clear` |
|
||||
|
||||
### Context Recovery Commands
|
||||
|
||||
| Command | Usage |
|
||||
|---------|-------|
|
||||
| `/compact` | Summarize and free context |
|
||||
| `/clear` | Fresh start |
|
||||
| `/rewind` | Undo recent changes |
|
||||
| `claude -c` | Resume last session (CLI flag) |
|
||||
| `claude -r <id>` | Resume specific session (CLI flag) |
|
||||
|
||||
---
|
||||
|
||||
## Plan Mode & Think Levels
|
||||
|
||||
| Feature | Activation | Usage |
|
||||
|---------|------------|-------|
|
||||
| **Plan Mode** | `Shift+Tab × 2` or `/plan` | Explore without modifying |
|
||||
| **OpusPlan** | `/model opusplan` | Opus for planning, Sonnet for execution |
|
||||
| **Think** | `--think` flag | Standard analysis (~4K tokens) |
|
||||
| **Think Hard** | `--think-hard` flag | Deep analysis (~10K tokens) |
|
||||
| **Ultrathink** | `--ultrathink` flag | Maximum depth (~32K tokens) |
|
||||
|
||||
**OpusPlan workflow**: `/model opusplan` → `Shift+Tab × 2` (plan with Opus) → `Shift+Tab` (execute with Sonnet)
|
||||
|
||||
**Required for**: features >3 files, architecture, complex debugging
|
||||
|
||||
---
|
||||
|
||||
## MCP Servers
|
||||
|
||||
| Server | Purpose |
|
||||
|--------|---------|
|
||||
| **Serena** | Indexation + session memory + symbol search |
|
||||
| **mgrep** | Semantic search by intent (alternative) |
|
||||
| **Context7** | Library documentation |
|
||||
| **Sequential** | Structured reasoning |
|
||||
| **Playwright** | Browser automation |
|
||||
| **Postgres** | Database queries |
|
||||
|
||||
**Serena memory**: `write_memory()` / `read_memory()` / `list_memories()`
|
||||
|
||||
Check status: `/mcp`
|
||||
|
||||
---
|
||||
|
||||
## Creating Custom Components
|
||||
|
||||
### Agent (`.claude/agents/my-agent.md`)
|
||||
```yaml
|
||||
---
|
||||
name: my-agent
|
||||
description: Use when [trigger]
|
||||
model: sonnet
|
||||
tools: Read, Write, Edit, Bash
|
||||
---
|
||||
# Instructions here
|
||||
```
|
||||
|
||||
### Command (`.claude/commands/my-command.md`)
|
||||
```markdown
|
||||
# Command Name
|
||||
Instructions for what to do...
|
||||
$ARGUMENTS - user provided args
|
||||
```
|
||||
|
||||
### Hook (macOS/Linux: `.sh` | Windows: `.ps1`)
|
||||
|
||||
**Bash** (macOS/Linux):
|
||||
```bash
|
||||
#!/bin/bash
|
||||
INPUT=$(cat)
|
||||
# Process JSON input
|
||||
exit 0 # 0=continue, 2=block
|
||||
```
|
||||
|
||||
**PowerShell** (Windows):
|
||||
```powershell
|
||||
$input = [Console]::In.ReadToEnd() | ConvertFrom-Json
|
||||
# Process JSON input
|
||||
exit 0 # 0=continue, 2=block
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Vague prompts | Specify file + line |
|
||||
| Accept without reading | Read every diff |
|
||||
| Ignore warnings | Use `/compact` |
|
||||
| Skip permissions | Never in production |
|
||||
| Giant context loads | Load only what's needed |
|
||||
| Negative constraints only | Provide alternatives |
|
||||
|
||||
---
|
||||
|
||||
## Quick Prompting Formula
|
||||
|
||||
```
|
||||
WHAT: [Concrete deliverable]
|
||||
WHERE: [File paths]
|
||||
HOW: [Constraints, approach]
|
||||
VERIFY: [Success criteria]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Add input validation to the login form.
|
||||
WHERE: src/components/LoginForm.tsx
|
||||
HOW: Use Zod schema, show inline errors
|
||||
VERIFY: Empty email shows error, invalid format shows error
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLI Flags Quick Reference
|
||||
|
||||
| Flag | Usage |
|
||||
|------|-------|
|
||||
| `-p "query"` | Non-interactive mode |
|
||||
| `-c` / `--continue` | Continue last session |
|
||||
| `-r` / `--resume <id>` | Resume specific session |
|
||||
| `--headless` | Non-interactive (CI/CD) |
|
||||
| `--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 |
|
||||
|
||||
---
|
||||
|
||||
## Debug Commands
|
||||
|
||||
```bash
|
||||
claude --version # Version
|
||||
claude update # Check/install updates
|
||||
claude doctor # Diagnostic
|
||||
claude --debug # Verbose mode
|
||||
claude --mcp-debug # Debug MCPs
|
||||
/mcp # MCP status (inside Claude)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Mode (Headless)
|
||||
|
||||
```bash
|
||||
# Non-interactive execution
|
||||
claude -p "analyze this file" src/api.ts
|
||||
|
||||
# JSON output
|
||||
claude -p "review" --output-format json
|
||||
|
||||
# Economic model
|
||||
claude -p "lint" --model haiku
|
||||
|
||||
# With auto-accept
|
||||
claude -p "fix typos" --dangerously-skip-permissions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Golden Rules
|
||||
|
||||
1. **Always review diffs** before accepting
|
||||
2. **Use `/compact`** before context gets critical (>70%)
|
||||
3. **Be specific** in requests (WHAT, WHERE, HOW, VERIFY)
|
||||
4. **Plan Mode first** for complex/risky tasks
|
||||
5. **Create CLAUDE.md** for every project
|
||||
6. **Commit frequently** after each completed task
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision Tree
|
||||
|
||||
```
|
||||
Simple task → Just ask Claude
|
||||
Complex task → TodoWrite to plan first
|
||||
Risky change → Plan Mode first
|
||||
Repeating task → Create agent or command
|
||||
Context full → /compact or /clear
|
||||
Need docs → Use Context7 MCP
|
||||
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)
|
||||
- **Advanced guide**: [Claudelog.com](https://claudelog.com/) - Tips & patterns
|
||||
- **Full guide**: `ultimate-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 2026 | Version 3.0.7*
|
||||
9035
guide/ultimate-guide.md
Normal file
9035
guide/ultimate-guide.md
Normal file
File diff suppressed because it is too large
Load diff
Loading…
Add table
Add a link
Reference in a new issue