From dab11d260c32731c99b0f08fa768afeede896938 Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Mon, 19 Jan 2026 11:13:54 +0100 Subject: [PATCH] feat: reorganize learning commands under /learn namespace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move quiz.md → learn/quiz.md (/learn:quiz) - Add learn/teach.md (/learn:teach) for step-by-step concept explanations - Add learn/alternatives.md (/learn:alternatives) for approach comparisons - Update all references in guide, README, and reference.yaml Follows Claude Code namespaced commands convention: /namespace:command → .claude/commands/namespace/command.md Co-Authored-By: Claude Opus 4.5 --- examples/README.md | 4 +- examples/claude-md/learning-mode.md | 4 +- examples/commands/learn/alternatives.md | 192 ++++++++++++++++++++++++ examples/commands/{ => learn}/quiz.md | 10 +- examples/commands/learn/teach.md | 178 ++++++++++++++++++++++ guide/learning-with-ai.md | 27 ++-- machine-readable/reference.yaml | 4 +- 7 files changed, 400 insertions(+), 19 deletions(-) create mode 100644 examples/commands/learn/alternatives.md rename examples/commands/{ => learn}/quiz.md (92%) create mode 100644 examples/commands/learn/teach.md diff --git a/examples/README.md b/examples/README.md index 82b6660..3f79256 100644 --- a/examples/README.md +++ b/examples/README.md @@ -71,7 +71,9 @@ Ready-to-use templates for Claude Code configuration. | [git-worktree.md](./commands/git-worktree.md) | `/git-worktree` | Isolated git worktree setup | | [diagnose.md](./commands/diagnose.md) | `/diagnose` | Interactive troubleshooting assistant (FR/EN) | | [validate-changes.md](./commands/validate-changes.md) | `/validate-changes` | LLM-as-a-Judge pre-commit validation | -| [quiz.md](./commands/quiz.md) | `/quiz` | Self-testing for learning concepts | +| [learn/quiz.md](./commands/learn/quiz.md) | `/learn:quiz` | Self-testing for learning concepts | +| [learn/teach.md](./commands/learn/teach.md) | `/learn:teach` | Step-by-step concept explanations | +| [learn/alternatives.md](./commands/learn/alternatives.md) | `/learn:alternatives` | Compare different approaches | | [catchup.md](./commands/catchup.md) | `/catchup` | Restore context after /clear | | [security.md](./commands/security.md) | `/security` | Quick OWASP security audit | | [refactor.md](./commands/refactor.md) | `/refactor` | SOLID-based code improvements | diff --git a/examples/claude-md/learning-mode.md b/examples/claude-md/learning-mode.md index 4f58143..8663c5e 100644 --- a/examples/claude-md/learning-mode.md +++ b/examples/claude-md/learning-mode.md @@ -165,5 +165,7 @@ See [examples/hooks/bash/learning-capture.sh](../hooks/bash/learning-capture.sh) ## See Also - [Learning with AI Guide](../../guide/learning-with-ai.md) — Complete learning methodology -- [/quiz Command](../commands/quiz.md) — Test your understanding +- [/learn:quiz Command](../commands/learn/quiz.md) — Test your understanding +- [/learn:teach Command](../commands/learn/teach.md) — Step-by-step concept explanations +- [/learn:alternatives Command](../commands/learn/alternatives.md) — Compare different approaches - [Learning Capture Hook](../hooks/bash/learning-capture.sh) — Automated insight logging diff --git a/examples/commands/learn/alternatives.md b/examples/commands/learn/alternatives.md new file mode 100644 index 0000000..34bb1ed --- /dev/null +++ b/examples/commands/learn/alternatives.md @@ -0,0 +1,192 @@ +# Show Alternatives + +Compare different approaches to solve the same problem. + +## Usage + +``` +/learn:alternatives # Compare approaches for current code +/learn:alternatives auth # Compare authentication methods +/learn:alternatives state # Compare state management options +/learn:alternatives --detailed # Include code examples for each +``` + +## Instructions + +1. Identify the **problem being solved** (from context or argument) +2. Present **3-5 alternative approaches** +3. For each approach, explain: + - What it is (one sentence) + - When to use it + - Trade-offs (pros/cons) +4. Provide a **recommendation** based on context +5. Optionally show code examples for top choices + +## Response Format + +```markdown +## Problem: [What we're trying to solve] + +### Approach 1: [Name] + +**What**: [One-sentence description] + +**When to use**: +- [Scenario 1] +- [Scenario 2] + +**Pros**: [List] +**Cons**: [List] + +--- + +### Approach 2: [Name] +... + +--- + +## Comparison Table + +| Criteria | Approach 1 | Approach 2 | Approach 3 | +|----------|------------|------------|------------| +| Complexity | Low | Medium | High | +| Performance | ★★☆ | ★★★ | ★★☆ | +| Bundle size | Small | Medium | Large | +| Learning curve | Easy | Medium | Steep | + +## Recommendation + +**For your case**: [Recommended approach] because [reason based on context] + +**Consider instead if**: [Alternative scenarios] +``` + +## Comparison Criteria + +Standard criteria to evaluate (adjust based on problem): + +| Criteria | Description | +|----------|-------------| +| **Complexity** | How hard to implement and maintain | +| **Performance** | Runtime speed, memory usage | +| **Bundle size** | Impact on frontend bundle | +| **Learning curve** | Time to understand and use correctly | +| **Flexibility** | Ease of extending or modifying | +| **Community** | Documentation, ecosystem, support | +| **Testing** | How easy to test | +| **Type safety** | TypeScript support quality | + +## Depth Modes + +### Default +- 3-4 alternatives +- Brief description each +- Comparison table +- Recommendation + +### `--detailed` +- 4-5 alternatives +- Code example for each +- Detailed trade-offs +- Migration considerations +- Real-world case studies + +### `--quick` +- 2-3 alternatives +- One-line each +- Quick recommendation + +## Example Session + +``` +User: I'm using useState for form state. /learn:alternatives + +Claude: ## Problem: Managing Form State in React + +### Approach 1: Multiple useState + +**What**: Separate useState for each field + +**When to use**: +- Simple forms (< 5 fields) +- No complex validation +- No cross-field dependencies + +**Pros**: Simple, no dependencies, easy to understand +**Cons**: Verbose with many fields, scattered state + +--- + +### Approach 2: Single useState with Object + +**What**: One useState holding all fields as object + +**When to use**: +- Medium forms (5-10 fields) +- Need to reset entire form +- Want cleaner code + +**Pros**: Grouped state, easy reset, cleaner +**Cons**: Need spread operator, can cause unnecessary re-renders + +--- + +### Approach 3: useReducer + +**What**: Reducer pattern for complex state transitions + +**When to use**: +- Complex validation logic +- Multi-step forms +- Undo/redo functionality + +**Pros**: Predictable updates, handles complex logic, testable +**Cons**: More boilerplate, learning curve + +--- + +### Approach 4: Form Library (React Hook Form, Formik) + +**What**: Dedicated form state management library + +**When to use**: +- Large forms (10+ fields) +- Complex validation (async, cross-field) +- Performance critical (many fields) + +**Pros**: Optimized re-renders, validation built-in, less code +**Cons**: Dependency, learning curve, bundle size + +--- + +## Comparison Table + +| Criteria | useState | useReducer | React Hook Form | +|----------|----------|------------|-----------------| +| Complexity | Low | Medium | Medium | +| Performance | ★★☆ | ★★☆ | ★★★ | +| Bundle size | 0kb | 0kb | ~8kb | +| Validation | Manual | Manual | Built-in | +| Best for | Simple | Complex logic | Large forms | + +## Recommendation + +**For your case**: If this is a simple login/contact form, stick with **useState**. If you're building a multi-step checkout or admin form, consider **React Hook Form** for the validation and performance benefits. + +**Consider useReducer if**: You need undo/redo, complex state machines, or want reducer-style testing. +``` + +## Common Alternative Comparisons + +| Topic | Typical Alternatives | +|-------|---------------------| +| **State** | useState, useReducer, Zustand, Redux, Jotai | +| **Styling** | CSS Modules, Tailwind, styled-components, CSS-in-JS | +| **Data fetching** | fetch, axios, React Query, SWR | +| **Forms** | useState, React Hook Form, Formik | +| **Auth** | JWT, sessions, OAuth, magic links | +| **API design** | REST, GraphQL, tRPC, gRPC | +| **Testing** | Jest, Vitest, Testing Library, Cypress | +| **Databases** | PostgreSQL, MySQL, MongoDB, SQLite | + +$ARGUMENTS diff --git a/examples/commands/quiz.md b/examples/commands/learn/quiz.md similarity index 92% rename from examples/commands/quiz.md rename to examples/commands/learn/quiz.md index 1c90b9a..cecd49e 100644 --- a/examples/commands/quiz.md +++ b/examples/commands/learn/quiz.md @@ -5,9 +5,9 @@ Test understanding of recently written or accepted code. ## Usage ``` -/quiz # Quiz on last code worked with -/quiz error handling # Focus on specific aspect -/quiz --hard # More challenging questions +/learn:quiz # Quiz on last code worked with +/learn:quiz error handling # Focus on specific aspect +/learn:quiz --hard # More challenging questions ``` ## Instructions @@ -52,7 +52,7 @@ Test understanding of recently written or accepted code. ## Focus Areas -When focus is specified (e.g., `/quiz error handling`), prioritize questions about: +When focus is specified (e.g., `/learn:quiz error handling`), prioritize questions about: | Focus | Question Themes | |-------|-----------------| @@ -112,7 +112,7 @@ Summarize: ## Example Session ``` -User: /quiz +User: /learn:quiz Claude: Looking at your last code - the useEffect hook for data fetching. diff --git a/examples/commands/learn/teach.md b/examples/commands/learn/teach.md new file mode 100644 index 0000000..50a251f --- /dev/null +++ b/examples/commands/learn/teach.md @@ -0,0 +1,178 @@ +# Teach Me + +Step-by-step explanation of a concept with progressive depth. + +## Usage + +``` +/learn:teach React hooks # Learn about React hooks +/learn:teach async/await # Understand async patterns +/learn:teach SOLID principles # Learn design principles +/learn:teach --deep SQL joins # In-depth explanation +``` + +## Instructions + +1. Start with a **one-sentence definition** of the concept +2. Explain **why it matters** (real-world problem it solves) +3. Show a **minimal example** (simplest possible code) +4. Break down **each part** of the example with comments +5. Show a **practical example** (real-world use case) +6. Highlight **common mistakes** beginners make +7. Suggest **next concepts** to learn + +## Response Format + +```markdown +## [Concept Name] + +**In one sentence**: [Clear, simple definition] + +### Why It Matters + +[1-2 sentences on the problem this solves] + +### Minimal Example + +\`\`\`[language] +// Simplest possible demonstration +[code] +\`\`\` + +**Line by line**: +- Line 1: [explanation] +- Line 2: [explanation] +... + +### Practical Example + +\`\`\`[language] +// Real-world scenario +[code] +\`\`\` + +### Common Mistakes + +1. **[Mistake]**: [Why it's wrong and what to do instead] +2. **[Mistake]**: [Why it's wrong and what to do instead] + +### Key Takeaways + +- [Bullet point 1] +- [Bullet point 2] +- [Bullet point 3] + +### Learn Next + +- [Related concept 1] — [why it connects] +- [Related concept 2] — [why it connects] + +--- + +**Practice challenge**: [Small exercise to reinforce the concept] +``` + +## Depth Modes + +### Default +- One-sentence definition +- One minimal example +- One practical example +- 2-3 common mistakes + +### `--deep` +- Extended explanation with history/context +- Multiple examples of increasing complexity +- Edge cases and gotchas +- Performance considerations +- Comparison with alternatives +- Interview-relevant details + +### `--quick` +- Definition only +- Single example +- No extras + +## Adaptation Rules + +### For Beginners +- Use analogies from everyday life +- Avoid jargon (or explain it immediately) +- More comments in code +- Smaller code examples + +### For Intermediates +- Assume basic syntax knowledge +- Focus on "why" over "what" +- Include trade-offs +- Show idiomatic patterns + +### For Advanced Topics +- Reference official documentation +- Discuss internal implementation when relevant +- Include performance implications +- Mention related patterns + +## Example Session + +``` +User: /learn:teach useEffect + +Claude: ## useEffect + +**In one sentence**: useEffect lets you run side effects (data fetching, subscriptions, DOM changes) after React renders a component. + +### Why It Matters + +React components are pure functions that render UI. But real apps need to interact with the outside world—APIs, browser events, timers. useEffect is the bridge between React's declarative world and imperative side effects. + +### Minimal Example + +\`\`\`jsx +import { useEffect, useState } from 'react'; + +function Timer() { + const [seconds, setSeconds] = useState(0); + + useEffect(() => { + const id = setInterval(() => { + setSeconds(s => s + 1); + }, 1000); + + return () => clearInterval(id); // Cleanup + }, []); // Empty array = run once + + return
{seconds}s
; +} +\`\`\` + +**Line by line**: +- `useEffect(() => {...}, [])`: Run this function after first render +- `setInterval(...)`: Start a timer (side effect) +- `return () => clearInterval(id)`: Cleanup when component unmounts +- `[]`: Empty dependency array = only run on mount + +### Common Mistakes + +1. **Missing dependency array**: Without `[]`, effect runs on EVERY render +2. **Forgetting cleanup**: Intervals/subscriptions leak without return function +3. **Stale closures**: Using old state values instead of functional updates + +--- + +**Practice challenge**: Add a pause button that stops and resumes the timer. +``` + +## Topics Well-Suited for /learn:teach + +| Category | Examples | +|----------|----------| +| **React** | hooks, context, suspense, server components | +| **JavaScript** | closures, promises, event loop, prototypes | +| **TypeScript** | generics, mapped types, utility types | +| **Patterns** | SOLID, DI, composition, factories | +| **Backend** | REST, GraphQL, authentication, caching | +| **Database** | indexes, joins, transactions, normalization | +| **DevOps** | containers, CI/CD, infrastructure as code | + +$ARGUMENTS diff --git a/guide/learning-with-ai.md b/guide/learning-with-ai.md index 09479d7..0be2572 100644 --- a/guide/learning-with-ai.md +++ b/guide/learning-with-ai.md @@ -264,7 +264,7 @@ After I accept generated code, help me verify understanding. 3. What would break if we removed line X?" ``` -See [examples/commands/quiz.md](../examples/commands/quiz.md) for implementation. +See [/learn:quiz command](../examples/commands/learn/quiz.md) for a more comprehensive version. --- @@ -392,13 +392,15 @@ Full template: [examples/claude-md/learning-mode.md](../examples/claude-md/learn | Command | Purpose | When to Use | |---------|---------|-------------| | `/explain` | Explain existing code | Built-in — use on any confusing code | -| `/quiz` | Test your understanding | After implementing a new concept | -| `/alternatives` | Show other approaches | When you want to understand trade-offs | -| `/teach ` | Step-by-step explanation | When learning something new | +| `/learn:quiz` | Test your understanding | After implementing a new concept | +| `/learn:alternatives` | Show other approaches | When you want to understand trade-offs | +| `/learn:teach ` | Step-by-step explanation | When learning something new | -#### Creating /quiz +> **Note**: Commands use the `/learn:` namespace. Place files in `.claude/commands/learn/`. -Create `.claude/commands/quiz.md`: +#### Creating /learn:quiz + +Create `.claude/commands/learn/quiz.md`: ```markdown # Quiz Me @@ -419,7 +421,7 @@ Test my understanding of the code I just wrote or accepted. $ARGUMENTS (optional: focus area like "error handling" or "performance") ``` -Full template: [examples/commands/quiz.md](../examples/commands/quiz.md) +Full template: [examples/commands/learn/quiz.md](../examples/commands/learn/quiz.md) --- @@ -841,7 +843,9 @@ See [methodologies.md](./methodologies.md) for: ### Templates & Examples - [Learning Mode CLAUDE.md](../examples/claude-md/learning-mode.md) — Configuration template -- [/quiz Command](../examples/commands/quiz.md) — Self-testing slash command +- [/learn:quiz Command](../examples/commands/learn/quiz.md) — Self-testing slash command +- [/learn:teach Command](../examples/commands/learn/teach.md) — Step-by-step concept explanations +- [/learn:alternatives Command](../examples/commands/learn/alternatives.md) — Compare different approaches - [Learning Capture Hook](../examples/hooks/bash/learning-capture.sh) — Automated insight logging ### External Resources @@ -887,9 +891,10 @@ Applying known skills: 30% struggle, 70% AI ### Claude Code Commands for Learning ``` -/explain — Understand existing code -/quiz — Test your understanding -/teach — Learn something new +/explain — Understand existing code +/learn:quiz — Test your understanding +/learn:teach — Learn something new +/learn:alternatives — Compare approaches ``` --- diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 14d53a8..ee886ea 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -33,7 +33,9 @@ deep_dive: learning_30day_plan: "guide/learning-with-ai.md:710" learning_red_flags: "guide/learning-with-ai.md:770" learning_mode_template: "examples/claude-md/learning-mode.md" - quiz_command: "examples/commands/quiz.md" + learn_quiz_command: "examples/commands/learn/quiz.md" + learn_teach_command: "examples/commands/learn/teach.md" + learn_alternatives_command: "examples/commands/learn/alternatives.md" learning_capture_hook: "examples/hooks/bash/learning-capture.sh" # Architecture internals (guide/architecture.md) architecture_master_loop: "guide/architecture.md:60"