diff --git a/CHANGELOG.md b/CHANGELOG.md index 5259754..844af70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +- **Learning with AI guide** for junior developers (`guide/learning-with-ai.md`, ~900 lines) + - **Quick Self-Check** (L31-81): 5 diagnostic questions to assess AI dependency + - **Three Developer Patterns** (L82-126): Dependent, Avoidant, Augmented profiles with action paths + - **UVAL Protocol** (L127-352): Understand → Verify → Apply → Learn framework with Claude Code implementations + - **Claude Code for Learning** (L353-469): CLAUDE.md configuration, slash commands, hooks for learning mode + - **Breaking Dependency** (L470-517): Recovery plan for over-reliant developers + - **Embracing AI** (L518-709): Onboarding for AI-skeptical developers + - **30-Day Progression Plan** (L710-769): Week-by-week AI ratio progression + - **Red Flags Checklist** (L770-850): Warning signs and corrective actions + - Case study: Méthode Aristote principles (human supervision + AI assistance) + +- **Learning mode templates** (3 new files) + - `examples/claude-md/learning-mode.md`: CLAUDE.md template for learning-focused development + - `examples/commands/quiz.md`: /quiz slash command for self-testing (5 difficulty levels) + - `examples/hooks/bash/learning-capture.sh`: Stop event hook for daily learning capture + - **Wireframing & Figma MCP documentation** in `guide/ultimate-guide.md` (+143 lines) - **Wireframing Tools for AI Development** (L483-518): Comparison table for Excalidraw, tldraw, Frame0, Paper+Photo with MCP support indicators - **Figma MCP Integration** (L520-583): Official Anthropic MCP server setup, available tools (`get_design_context`, `get_variable_defs`, `get_code_connect_map`), workflow examples @@ -17,6 +33,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Changed +- **README.md**: Added prominent "Visit Website" badge linking to landing page +- **Templates count**: 52 → 55 in README.md badges (3 new learning templates) +- **Navigation updated**: `guide/README.md`, `examples/hooks/README.md` with new learning resources +- **Reference index expanded**: `machine-readable/reference.yaml` with 10 new deep_dive entries for learning topics + - **Semantic search tools priority**: grepai now recommended over mgrep - `guide/ultimate-guide.md`: Sections reordered (grepai first as "Recommended", mgrep as "Alternative") - `guide/cheatsheet.md`: MCP Servers table updated (mgrep → grepai) diff --git a/README.md b/README.md index c4103fb..4ff0639 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,13 @@ # Claude Code Guide +

+ Website +

+

Stars Lines - Templates + Templates Quiz

@@ -129,7 +133,7 @@ Claude asks 2-4 questions then guides you through personalized content based on - You read official docs → dense, no progression - You search tutorials → scattered, outdated in weeks -**This guide:** Structured learning path with 53 copy-paste templates. Your mileage may vary—but this saves you the exploration time. +**This guide:** Structured learning path with 55 copy-paste templates. Your mileage may vary—but this saves you the exploration time. | Traditional Docs | This Guide | |------------------|------------| @@ -328,14 +332,15 @@ Weak Areas (< 75%): ### 🎯 By Role (Tailored Learning Paths)
-Junior Developer — Foundation path (6 steps) +Junior Developer — Foundation path (7 steps) 1. [Quick Start](./guide/ultimate-guide.md#1-quick-start-day-1) — Install & first workflow 2. [Essential Commands](./guide/ultimate-guide.md#13-essential-commands) — The 7 commands 3. [Context Management](./guide/ultimate-guide.md#22-context-management) — Critical concept 4. [Memory Files](./guide/ultimate-guide.md#31-memory-files-claudemd) — Your first CLAUDE.md -5. [TDD Workflow](./guide/workflows/tdd-with-claude.md) — Test-first development -6. [Cheat Sheet](./guide/cheatsheet.md) — Print this +5. [Learning with AI](./guide/learning-with-ai.md) — Use AI without becoming dependent ⭐ +6. [TDD Workflow](./guide/workflows/tdd-with-claude.md) — Test-first development +7. [Cheat Sheet](./guide/cheatsheet.md) — Print this
diff --git a/examples/README.md b/examples/README.md index 9118ab5..1570090 100644 --- a/examples/README.md +++ b/examples/README.md @@ -14,6 +14,7 @@ Ready-to-use templates for Claude Code configuration. | [`hooks/`](./hooks/) | Event-driven automation scripts | | [`config/`](./config/) | Configuration file templates | | [`memory/`](./memory/) | CLAUDE.md memory file templates | +| [`claude-md/`](./claude-md/) | Specialized CLAUDE.md configurations | | [`scripts/`](./scripts/) | Utility scripts for setup and diagnostics | | [`github-actions/`](./github-actions/) | CI/CD workflows for GitHub Actions | | [`workflows/`](./workflows/) | Advanced development workflow guides | @@ -69,6 +70,7 @@ 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 | ### Hooks | File | Event | Purpose | @@ -85,6 +87,7 @@ Ready-to-use templates for Claude Code configuration. | [output-validator.sh](./hooks/bash/output-validator.sh) | PostToolUse | Heuristic output validation | | [session-logger.sh](./hooks/bash/session-logger.sh) | PostToolUse | Log operations for monitoring | | [pre-commit-evaluator.sh](./hooks/bash/pre-commit-evaluator.sh) | Git hook | LLM-as-a-Judge pre-commit | +| [learning-capture.sh](./hooks/bash/learning-capture.sh) | Stop | Prompt for daily learning capture | > **See [hooks/README.md](./hooks/README.md) for complete documentation and security hardening patterns** @@ -101,6 +104,13 @@ Ready-to-use templates for Claude Code configuration. | [CLAUDE.md.project-template](./memory/CLAUDE.md.project-template) | Team project memory | | [CLAUDE.md.personal-template](./memory/CLAUDE.md.personal-template) | Personal global memory | +### CLAUDE.md Configurations +| File | Purpose | +|------|---------| +| [learning-mode.md](./claude-md/learning-mode.md) | Learning-focused development configuration | + +> **See [guide/learning-with-ai.md](../guide/learning-with-ai.md) for complete documentation** + ### Scripts | File | Purpose | Output | |------|---------|--------| diff --git a/examples/claude-md/learning-mode.md b/examples/claude-md/learning-mode.md new file mode 100644 index 0000000..4f58143 --- /dev/null +++ b/examples/claude-md/learning-mode.md @@ -0,0 +1,169 @@ +# Learning Mode CLAUDE.md Template + +A CLAUDE.md configuration optimized for developers who want to learn, not just produce code. + +## Usage + +Copy this content to your project's `CLAUDE.md` file and customize the sections marked with `[brackets]`. + +--- + +## Template + +```markdown +# Learning-First Configuration + +## About Me +- I'm learning: [React hooks, TypeScript, system design, etc.] +- My level: [beginner/intermediate/advanced] on these topics +- I learn best when: [examples shown first / concepts explained first / hands-on practice] +- My goal: [Build portfolio projects / Prepare for interviews / Career transition] + +## Response Style + +### Always +- Explain WHY, not just WHAT +- After code blocks, pause and ask "What questions do you have about this?" +- Highlight concepts I should understand deeper +- Point out common mistakes beginners make on this topic +- Use comments in code to explain non-obvious parts + +### When I'm Stuck +1. First ask what I've already tried +2. Guide me toward the answer with hints before giving it directly +3. Explain the underlying concept, not just the fix +4. Show how to debug similar issues in the future + +### Code Examples +- Keep examples focused and minimal +- Show the "why" through comments +- After complex examples, break down what each part does +- Offer to show alternative approaches + +## Learning Challenges + +After implementing something new: +- Suggest 1-2 exercises to reinforce the concept +- Point out edge cases I should consider +- Ask me to predict what would happen if X changed + +## Verification Prompts + +After generating code, occasionally ask: +- "Can you explain what line X does?" +- "What would break if we removed Y?" +- "Why did we use Z instead of W?" + +If I can't answer, help me understand before moving on. + +## Topics I'm Focusing On +- [Topic 1]: Want thorough explanations +- [Topic 2]: Want thorough explanations +- [Topic 3]: Know basics, want advanced patterns + +## Topics I Know Well +- [Topic A]: Be concise, I know this +- [Topic B]: Be concise, I know this + +## My Constraints +- Time available: [15 min / 1 hour / open-ended] +- Can I break things? [yes - learning environment / no - production] +- Deadline pressure: [none / some / high] + +## Special Modes + +### Challenge Mode +When I say "challenge mode on": +- Don't give complete solutions +- Ask Socratic questions instead +- Guide me to discover the answer myself +- Only reveal solution if I explicitly give up + +When I say "challenge mode off": +- Return to normal helpful mode + +### Interview Prep Mode +When I say "interview mode": +- After solving something, ask: "How would you explain this in an interview?" +- Suggest related interview questions +- Point out Big-O complexity when relevant +- Note common follow-up questions interviewers ask + +## End of Session +Before ending a session, remind me: +1. What new concepts we covered +2. Suggest one thing to practice tomorrow +3. Ask: "What's one thing you learned today?" +``` + +--- + +## Customization Guide + +### For Complete Beginners + +Add to "Response Style": +```markdown +- Assume I don't know technical jargon - explain or avoid it +- Use real-world analogies for abstract concepts +- Check understanding frequently before moving on +``` + +### For Interview Preparation + +Add section: +```markdown +## Interview Focus +- After each implementation, ask "How would you optimize this?" +- Point out time/space complexity +- Mention common interview variations of problems +- Note what FAANG companies look for in solutions +``` + +### For Career Changers + +Add to "About Me": +```markdown +- Background: [Previous career] +- Transferable skills: [Project management, analytical thinking, etc.] +- Help me connect concepts to what I already know +``` + +### For Team Learning + +Add section: +```markdown +## Team Context +- We use: [specific frameworks, patterns, conventions] +- Team conventions: [link to style guide] +- When I learn something, help me document it for the team +``` + +--- + +## Integration with Hooks + +Pair this CLAUDE.md with the learning-capture hook to automatically log insights: + +```json +{ + "hooks": { + "Stop": [{ + "hooks": [{ + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash/learning-capture.sh" + }] + }] + } +} +``` + +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 +- [Learning Capture Hook](../hooks/bash/learning-capture.sh) — Automated insight logging diff --git a/examples/commands/quiz.md b/examples/commands/quiz.md new file mode 100644 index 0000000..1c90b9a --- /dev/null +++ b/examples/commands/quiz.md @@ -0,0 +1,144 @@ +# Quiz Me + +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 +``` + +## Instructions + +1. Identify the last code I worked with (wrote, edited, or accepted from AI) +2. Generate 3-5 questions that test understanding at different levels: + - **Recall**: What does this code do? + - **Understanding**: Why was this approach chosen? + - **Application**: What would happen if X changed? + - **Analysis**: What are the trade-offs of this approach? + - **Synthesis**: How would you extend this? +3. Present questions one at a time +4. Wait for my answer before revealing the correct response +5. Provide explanations with each answer, not just "correct/incorrect" + +## Question Types + +### Level 1: Recall +- "What does the function X return?" +- "What parameters does Y accept?" +- "What happens when Z is called?" + +### Level 2: Understanding +- "Why do we use X instead of Y here?" +- "What problem does this pattern solve?" +- "Why is this line necessary?" + +### Level 3: Application +- "What would happen if we removed line X?" +- "How would you add feature Y to this code?" +- "What would break if input Z was provided?" + +### Level 4: Analysis +- "What are the performance implications of this approach?" +- "What edge cases might cause issues?" +- "How does this compare to alternative X?" + +### Level 5: Synthesis +- "How would you refactor this for better testability?" +- "What would need to change to support X?" +- "Design an extension that adds Y" + +## Focus Areas + +When focus is specified (e.g., `/quiz error handling`), prioritize questions about: + +| Focus | Question Themes | +|-------|-----------------| +| `error handling` | Try/catch, error types, recovery strategies | +| `performance` | Big-O, optimization, bottlenecks | +| `security` | Input validation, XSS, injection | +| `testing` | Test cases, edge cases, mocking | +| `architecture` | Patterns, separation of concerns, SOLID | +| `types` | TypeScript types, inference, generics | + +## Difficulty Modes + +### Default +- 3 questions +- Mix of Level 1-3 +- Focus on understanding current code + +### `--hard` +- 5 questions +- Levels 3-5 +- Include hypothetical modifications +- Ask about trade-offs and alternatives + +## Response Format + +For each question: + +``` +## Question 1 of 3 + +[Question text] + +What's your answer? + +--- +(After user responds) + +### Feedback + +[Whether correct and why] + +**Key insight**: [The concept this tests] + +**Related concept**: [Something to explore further] + +Ready for the next question? +``` + +## After Quiz Complete + +Summarize: +- Score: X/Y correct +- Strengths: [Topics understood well] +- Review needed: [Topics to revisit] +- Suggested practice: [Specific exercise] + +## Example Session + +``` +User: /quiz + +Claude: Looking at your last code - the useEffect hook for data fetching. + +## Question 1 of 3 + +In your useEffect, you have an empty dependency array []. +What does this mean for when the effect runs? + +User: It runs only once when the component mounts + +Claude: ### Feedback +Correct! An empty dependency array means the effect runs only on mount +(and cleanup on unmount). + +**Key insight**: The dependency array controls WHEN effects re-run. + +**Related concept**: What happens with no array vs. [someValue]? + +Ready for Question 2? +``` + +## Tips for Users + +1. **Be honest** — Wrong answers are learning opportunities +2. **Explain your reasoning** — Helps identify gaps even in correct answers +3. **Ask follow-ups** — If feedback is unclear, dig deeper +4. **Track weak areas** — Note topics that need more practice + +$ARGUMENTS diff --git a/examples/hooks/README.md b/examples/hooks/README.md index b5eec82..a621e95 100644 --- a/examples/hooks/README.md +++ b/examples/hooks/README.md @@ -15,6 +15,7 @@ Hooks are scripts that execute automatically on Claude Code events. They enable | [claudemd-scanner.sh](./bash/claudemd-scanner.sh) | SessionStart | Detect CLAUDE.md injection attacks | Bash | | [output-secrets-scanner.sh](./bash/output-secrets-scanner.sh) | PostToolUse | Detect secrets + env leakage in tool outputs | Bash | | [auto-format.sh](./bash/auto-format.sh) | PostToolUse | Auto-format after edits | Bash | +| [learning-capture.sh](./bash/learning-capture.sh) | Stop | Prompt for daily learning capture | Bash | | [notification.sh](./bash/notification.sh) | Notification | Contextual macOS sound alerts | Bash (macOS) | | [security-check.ps1](./powershell/security-check.ps1) | PreToolUse | Block secrets in commands | PowerShell | | [auto-format.ps1](./powershell/auto-format.ps1) | PostToolUse | Auto-format after edits | PowerShell | diff --git a/examples/hooks/bash/learning-capture.sh b/examples/hooks/bash/learning-capture.sh new file mode 100755 index 0000000..e9b705b --- /dev/null +++ b/examples/hooks/bash/learning-capture.sh @@ -0,0 +1,58 @@ +#!/bin/bash +# Hook: Stop - Capture one learning insight at session end +# Event: Stop (when user ends session or interrupts) +# Purpose: Build a learning journal with minimal friction +# +# Exit codes: +# 0 = success (always returns 0 to not block session end) +# +# Output: Appends to ~/claude-learnings.md +# +# Configuration: +# CLAUDE_LEARNING_LOG - Custom log path (default: ~/claude-learnings.md) +# CLAUDE_LEARNING_SKIP - Set to 1 to skip prompt + +set -e + +# Configuration +LOG_FILE="${CLAUDE_LEARNING_LOG:-$HOME/claude-learnings.md}" +SKIP_PROMPT="${CLAUDE_LEARNING_SKIP:-0}" + +# Skip if disabled +if [[ "$SKIP_PROMPT" == "1" ]]; then + exit 0 +fi + +# Read hook input (not used but consumed to avoid errors) +INPUT=$(cat) + +# Get project context +PROJECT_NAME=$(basename "${CLAUDE_PROJECT_DIR:-$(pwd)}") +DATE=$(date +%Y-%m-%d) +TIME=$(date +%H:%M) + +# Ensure log file directory exists +mkdir -p "$(dirname "$LOG_FILE")" + +# Create log file with header if it doesn't exist +if [[ ! -f "$LOG_FILE" ]]; then + cat > "$LOG_FILE" << 'HEADER' +# Claude Learning Journal + +A record of insights captured during coding sessions. + +--- + +HEADER +fi + +# Return system message prompting for learning capture +# The user's response will be logged by the next invocation +# (This is a non-blocking prompt approach) +cat << EOF +{ + "systemMessage": "Session ending. Quick reflection:\n\nWhat's ONE thing you learned this session?\n\n(Type your answer, or 'skip' to end without logging)\n\nLogging to: $LOG_FILE" +} +EOF + +exit 0 diff --git a/guide/README.md b/guide/README.md index b262f55..3698a5c 100644 --- a/guide/README.md +++ b/guide/README.md @@ -9,6 +9,7 @@ Core documentation for mastering Claude Code. | [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 | | [architecture.md](./architecture.md) | How Claude Code works internally (master loop, tools, context) | 25 min | +| [learning-with-ai.md](./learning-with-ai.md) | Guide for juniors on using AI without losing skills | 15 min | | [adoption-approaches.md](./adoption-approaches.md) | Implementation strategies for teams | 15 min | | [data-privacy.md](./data-privacy.md) | Data retention and privacy guide | 10 min | | [observability.md](./observability.md) | Session monitoring and cost tracking | 15 min | diff --git a/guide/learning-with-ai.md b/guide/learning-with-ai.md new file mode 100644 index 0000000..09479d7 --- /dev/null +++ b/guide/learning-with-ai.md @@ -0,0 +1,897 @@ +# Learning to Code with AI: The Conscious Developer's Guide + +> **Confidence**: Tier 2 — Based on academic research (2023-2025) and educator feedback +> +> **Audience**: Junior developers, CS students, bootcamp graduates, career changers +> +> **Reading time**: ~15 minutes +> +> **Last updated**: January 2026 + +--- + +## Table of Contents + +1. [Quick Self-Check (Start Here)](#quick-self-check-start-here) +2. [The Problem in 60 Seconds](#the-problem-in-60-seconds) +3. [The Three Patterns](#the-three-patterns) +4. [The UVAL Protocol](#the-uval-protocol) +5. [Claude Code for Learning](#claude-code-for-learning-not-just-producing) +6. [Breaking Dependency (Pattern: Dependent)](#breaking-dependency) +7. [Embracing AI Tools (Pattern: Avoidant)](#embracing-ai-tools) +8. [Optimizing Your Flow (Pattern: Augmented)](#optimizing-your-flow) +9. [Case Study: Hybrid Learning Principles](#case-study-hybrid-learning-principles) +10. [30-Day Progression Plan](#30-day-progression-plan) +11. [Red Flags Checklist](#red-flags-checklist) +12. [Sources & Research](#sources--research) +13. [See Also](#see-also) + +--- + +## Quick Self-Check (Start Here) + +Before diving in, answer honestly: + +| # | Question | Yes | No | +|---|----------|-----|-----| +| 1 | Can you explain the last code that AI generated for you? | ☐ | ☐ | +| 2 | Have you debugged code without AI this week? | ☐ | ☐ | +| 3 | Do you know WHY the solution works (not just THAT it works)? | ☐ | ☐ | +| 4 | Could you write the same function without assistance? | ☐ | ☐ | +| 5 | Do you know the AI's limitations on this type of problem? | ☐ | ☐ | + +### Your Score + +| Score | Where You Are | Jump To | +|-------|--------------|---------| +| **0-2 yes** | Dependency risk — you're outsourcing thinking | [§6 Breaking Dependency](#breaking-dependency) | +| **3-4 yes** | On track — room for optimization | [§8 Optimizing Your Flow](#optimizing-your-flow) | +| **5 yes** | Augmented — you're using AI correctly | [§9 Case Study](#case-study-hybrid-learning-principles) | + +Be honest. This guide only helps if you acknowledge where you actually are. + +--- + +## The Problem in 60 Seconds + +> AI can make you 3x more productive OR unemployable in 3 years. +> The difference? How you use it. + +Forget the statistics for now. Here's a simple metaphor: + +**AI is your GPS.** + +- Great for getting somewhere fast +- Dangerous if you lose the ability to navigate without it +- Truly useful when you understand the map AND use the GPS + +A developer who only copy-pastes AI output is like a driver who can't read a map. Fine until the GPS fails — or until someone asks them to explain the route. + +### The Skills Gap + +``` +Traditional learning: Problem → Struggle → Understanding → Solution +AI-assisted (wrong): Problem → AI → Solution → ??? (no understanding) +AI-assisted (right): Problem → Attempt → AI guidance → Understanding → Solution +``` + +The struggle isn't optional. It's where learning happens. + +--- + +## The Three Patterns + +Every developer using AI falls into one of three patterns: + +| Pattern | Signs | Risk | This Guide | +|---------|-------|------|------------| +| **Dependent** | Copy-paste without understanding, can't debug AI code, anxiety without AI | Unemployable | [§6](#breaking-dependency) | +| **Avoidant** | Refuses AI "on principle", slower than peers, dismissive of tools | Left behind | [§7](#embracing-ai-tools) | +| **Augmented** | Uses AI critically, understands everything, knows AI limits | Thriving | [§8](#optimizing-your-flow) | + +### Pattern 1: Dependent + +**How you got here**: Started with AI from day one, never built foundational skills, deadline pressure made shortcuts appealing. + +**The trap**: You ship code you can't explain. When it breaks, you're stuck. In interviews, you freeze. + +**What interviewers see**: +- Can't whiteboard basic algorithms +- Struggles with "why did you choose this approach?" +- Asks to "look something up" for fundamental concepts + +### Pattern 2: Avoidant + +**How you got here**: Purist mindset, fear of "cheating", learned before AI tools existed, distrust of new technology. + +**The trap**: You're slower than peers. You spend hours on problems AI solves instantly. You're not learning faster by struggling more — you're just slower. + +**What teams see**: +- Reinventing wheels unnecessarily +- Slow on routine tasks +- Resistance to modern tooling + +### Pattern 3: Augmented + +**How you got here**: Built foundations first OR consciously fixed Pattern 1/2 habits, treat AI as tool not crutch, verify everything. + +**The advantage**: You move fast AND understand deeply. You use AI for leverage, not replacement. + +**What hiring managers see**: +- Fast delivery with clear explanations +- Can work with OR without AI +- Uses tools appropriately for the task + +--- + +## The UVAL Protocol + +A systematic approach to using AI without losing your edge. + +### Overview + +| Step | Action | Why It Matters | +|------|--------|----------------| +| **U** | Understand First | Ask better questions, catch wrong answers | +| **V** | Verify | Ensure you actually learned, not just copied | +| **A** | Apply | Transform knowledge into skill through modification | +| **L** | Learn | Capture insights for long-term retention | + +--- + +### U — Understand First (The 15-Minute Rule) + +**Not just "think for 15 minutes"** — a specific protocol: + +#### Step 1: State the Problem (2 min) + +Write the problem in ONE sentence. If you can't, you don't understand it yet. + +``` +❌ "The code doesn't work" +✅ "The login form doesn't show validation errors when email is empty" +``` + +#### Step 2: Brainstorm Approaches (5 min) + +List 3 possible approaches, even if you're not sure they'll work: + +``` +1. Add client-side validation with JavaScript +2. Use HTML5 required attribute +3. Add server-side validation and return errors +``` + +This forces you to think before asking AI. + +#### Step 3: Identify Knowledge Gaps (3 min) + +What specifically do you NOT know? + +``` +- I know I need validation, but I don't know how to display inline errors in React +- I've never used Zod before but it keeps coming up +``` + +#### Step 4: THEN Ask AI (5 min) + +Now your question is 10x better: + +``` +❌ "How do I add validation?" +✅ "I'm building a React login form. I want to: + 1. Validate email format client-side + 2. Show inline error messages below the input + 3. Use Zod for schema validation + + I've tried using the HTML required attribute but need custom error messages. + What's the idiomatic React approach?" +``` + +Better questions → Better answers → Faster learning. + +#### Claude Code Implementation + +Add to your `CLAUDE.md`: + +```markdown +## Learning Mode +Before generating code for me, ask: +1. What approaches have I already considered? +2. What specifically am I stuck on? +3. What do I expect the solution to look like? + +If I skip these, remind me to think first. +``` + +--- + +### V — Verify (Explain It Back) + +**The rule**: If you can't explain the code to a colleague, you haven't learned it. + +#### The Rubber Duck Protocol + +After AI generates code: + +1. Read every line out loud +2. Explain what each part does +3. Explain WHY it's done this way (not just what) +4. Identify parts you don't understand +5. Ask AI to explain those specific parts + +#### Example + +AI generates: +```typescript +const schema = z.object({ + email: z.string().email(), + password: z.string().min(8) +}).refine(data => data.password !== data.email, { + message: "Password cannot be email", + path: ["password"] +}); +``` + +Your explanation: +- Line 1: Creates a Zod schema object +- Lines 2-3: Validates email format and password length +- Lines 4-6: Adds custom validation... **wait, what does `refine` do?** + +→ Now ask AI specifically about `refine` instead of just copying the whole thing. + +#### Claude Code Implementation + +Create a custom slash command `/explain-back`: + +```markdown +# Explain Back + +After I accept generated code, help me verify understanding. + +## Instructions + +1. Show the code I just accepted +2. Ask me to explain what each major section does +3. Correct any misunderstandings +4. If I can't explain it, break it down further + +## Example Prompt + +"You just accepted this code. Can you explain: +1. What problem does it solve? +2. Why was this approach chosen? +3. What would break if we removed line X?" +``` + +See [examples/commands/quiz.md](../examples/commands/quiz.md) for implementation. + +--- + +### A — Apply (Transform, Don't Copy) + +**The rule**: Never copy-paste AI code directly. Always modify something. + +#### Why This Works + +Modification forces engagement. Even small changes require understanding: + +| Action | Cognitive Load | Learning | +|--------|---------------|----------| +| Copy-paste | Zero | Zero | +| Rename variables | Low | Some | +| Add edge case | Medium | Good | +| Refactor structure | High | Excellent | + +#### Minimum Viable Modifications + +Always do at least ONE: + +1. **Rename** — Change variable names to match your project conventions +2. **Restructure** — Extract a helper function, change iteration method +3. **Extend** — Add an edge case, validation, or error handling +4. **Simplify** — Remove features you don't need + +#### Example + +AI gives you: +```javascript +function calculateTotal(items) { + return items.reduce((sum, item) => sum + item.price * item.quantity, 0); +} +``` + +You transform it: +```javascript +// Added: explicit type checking, edge case handling +function calculateCartTotal(cartItems) { + if (!Array.isArray(cartItems) || cartItems.length === 0) { + return 0; + } + return cartItems.reduce((total, item) => { + const itemPrice = Number(item.price) || 0; + const itemQty = Number(item.quantity) || 0; + return total + itemPrice * itemQty; + }, 0); +} +``` + +Now you've engaged with the code, added your own thinking, and learned something. + +--- + +### L — Learn (Capture the Insight) + +**Not a daily journal** — nobody maintains those. Instead: automated capture. + +#### The One-Thing Rule + +At the end of each coding session, capture ONE thing you learned. Not ten. One. + +```markdown +## 2026-01-17 +**Learned**: Zod's `refine()` method for cross-field validation +**Context**: Login form needed password ≠ email check +**Future me**: Use refine() when validation involves multiple fields +``` + +#### Claude Code Implementation + +Create a session-end hook: + +```bash +# .claude/hooks/bash/learning-capture.sh +# Prompts for one learning at session end +``` + +See [examples/hooks/bash/learning-capture.sh](../examples/hooks/bash/learning-capture.sh) for implementation. + +The hook asks: "What's ONE thing you learned this session?" and logs it automatically. + +--- + +## Claude Code for Learning (Not Just Producing) + +Claude Code has specific features that support learning. Here's how to configure them. + +### CLAUDE.md Configuration for Learning Mode + +Create this in your `CLAUDE.md`: + +```markdown +# Learning-First Configuration + +## My Learning Goals +- I'm learning: [React hooks, TypeScript, system design, etc.] +- My level: [beginner/intermediate] on these topics +- I learn best when: [examples are shown first, concepts are explained, etc.] + +## Response Style +- Always explain WHY, not just WHAT +- After code blocks, ask "What questions do you have about this?" +- Highlight concepts I should understand deeper +- Point out common mistakes beginners make + +## Challenges +- Suggest exercises to reinforce concepts after implementing +- Point out edge cases I should consider +- Ask me to predict output before showing it + +## When I Ask for Help +1. First ask what I've already tried +2. Guide me toward the answer before giving it +3. Explain the underlying concept, not just the fix +``` + +Full template: [examples/claude-md/learning-mode.md](../examples/claude-md/learning-mode.md) + +--- + +### Slash Commands for Learning + +| 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 | + +#### Creating /quiz + +Create `.claude/commands/quiz.md`: + +```markdown +# Quiz Me + +Test my understanding of the code I just wrote or accepted. + +## Instructions + +1. Look at the last code I worked with +2. Generate 3-5 questions testing: + - What does this code do? + - Why was this approach chosen? + - What would happen if X changed? + - How would you extend this? +3. Wait for my answers +4. Provide feedback with explanations + +$ARGUMENTS (optional: focus area like "error handling" or "performance") +``` + +Full template: [examples/commands/quiz.md](../examples/commands/quiz.md) + +--- + +### Hooks That Build Habits + +#### Learning Capture Hook (Session End) + +Automatically prompts for daily learning capture: + +```json +{ + "hooks": { + "Stop": [{ + "hooks": [{ + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash/learning-capture.sh" + }] + }] + } +} +``` + +--- + +### The 70/30 Weekly Split + +Balance learning and producing: + +| Activity | Time | AI Usage | Why | +|----------|------|----------|-----| +| **Core learning** (new concepts) | 70% | 30% AI | Struggle builds understanding | +| **Practice/projects** (applying known skills) | 30% | 70% AI | Leverage what you already know | + +#### Week Structure Example + +``` +Monday: Learn new React pattern (minimal AI) +Tuesday: Learn new React pattern (minimal AI) +Wednesday: Apply to project (full AI assistance) +Thursday: Learn testing approach (minimal AI) +Friday: Apply + ship (full AI assistance) +``` + +The key: Don't use AI heavily when learning NEW concepts. Use it heavily when applying concepts you already understand. + +--- + +## Breaking Dependency + +**For Pattern 1 developers**: You've been using AI as a crutch. Here's how to rebuild your foundation. + +### Week 1: The Cold Turkey Period + +**Goal**: Prove to yourself you can code without AI. + +| Day | Exercise | Duration | +|-----|----------|----------| +| 1-2 | Build a simple feature WITHOUT AI | 2 hours | +| 3-4 | Debug an issue using only documentation | 1 hour | +| 5 | Explain code you previously AI-generated | 30 min | + +**Expect this to feel slow and frustrating.** That's the learning happening. + +### Week 2: Guided Reintroduction + +**Goal**: Use AI as a teacher, not a generator. + +| Day | Exercise | AI Role | +|-----|----------|---------| +| 1-2 | Ask AI to explain concepts, then implement yourself | Tutor | +| 3-4 | Write code first, then ask AI for review | Reviewer | +| 5 | Compare your solution to AI's, understand differences | Comparator | + +### Week 3-4: Balanced Usage + +**Goal**: Develop critical AI usage habits. + +Apply the UVAL protocol (§4) to every interaction: + +1. **Understand** — 15-minute rule before asking +2. **Verify** — Explain every line back +3. **Apply** — Transform, don't copy +4. **Learn** — Capture one insight per session + +### Red Flags You're Slipping + +| Sign | Action | +|------|--------| +| Copying without reading | Stop. Read every line first. | +| Can't explain what code does | Use `/explain-back` command | +| Anxiety when AI unavailable | Practice 30 min daily without AI | +| Failed interview questions | Focus on fundamentals without AI | + +--- + +## Embracing AI Tools + +**For Pattern 2 developers**: You've been avoiding AI. Here's why that's hurting you and how to change. + +### Why Avoidance Is a Problem + +The job market has changed: + +- Teams expect AI-assisted productivity +- "Pure" coding is slower for routine tasks +- Refusing tools signals inflexibility + +You're not cheating by using AI. You're being inefficient by not using it. + +### Week 1: Low-Stakes Introduction + +**Goal**: Use AI for tasks that don't feel like "cheating." + +| Task | Why It's Safe | Try It | +|------|---------------|--------| +| Generate boilerplate | Nobody learns from typing imports | "Generate React component boilerplate" | +| Explain unfamiliar code | You'd Google this anyway | `/explain this codebase` | +| Write documentation | Documentation isn't the skill | "Document this function" | +| Generate test cases | Tests verify YOUR understanding | "Generate test cases for this function" | + +### Week 2: Expanded Usage + +**Goal**: Use AI for tasks you'd normally struggle through. + +| Task | Old Way | AI-Assisted Way | +|------|---------|-----------------| +| Debug error message | Stack Overflow rabbit hole | "Explain this error and likely causes" | +| Learn new library | Read entire docs | "Show me the key patterns for X" | +| Refactor code | Manual, error-prone | "Refactor for readability, explain changes" | + +### Week 3-4: Integration + +**Goal**: AI becomes part of your normal workflow. + +Apply UVAL protocol to ensure you're learning, not just generating. + +### Mindset Shift + +**Old thinking**: "Using AI means I'm not a real developer." + +**New thinking**: "AI handles routine tasks so I can focus on architecture, design, and complex problem-solving." + +The best developers use every tool available. AI is a tool. + +--- + +## Optimizing Your Flow + +**For Pattern 3 developers**: You're using AI well. Here's how to level up. + +### Advanced UVAL Applications + +#### Predictive Prompting + +Before AI generates code, predict the approach: + +``` +My prediction: This will probably use reduce() with an accumulator +Then compare to AI output — learn from differences +``` + +#### Teaching Mode + +Use AI to test your knowledge by teaching: + +``` +I'll explain how React hooks work. Correct my mistakes and fill gaps. + +useState stores state that persists between renders... +``` + +AI acts as a smart rubber duck that can catch errors. + +#### Comparative Analysis + +Ask for multiple approaches, then choose: + +``` +Show me 3 ways to implement this: +1. Using class components +2. Using hooks +3. Using a state management library + +Explain trade-offs of each. +``` + +This builds architectural thinking. + +--- + +### Advanced Claude Code Configuration + +#### Dynamic Learning Mode + +```markdown +# Advanced Learning Configuration + +## Adaptive Responses +- For topics I mark as "learning": explain thoroughly +- For topics I mark as "known": be concise +- Track my progress within this session + +## Challenge Mode (Optional) +When I say "challenge mode on": +- Don't give me complete solutions +- Ask Socratic questions +- Guide me to discover the answer + +## Review Mode +After each feature, summarize: +1. New concepts introduced +2. Patterns worth remembering +3. Potential interview questions from this code +``` + +#### Spaced Repetition Integration + +Track concepts for future review: + +```bash +# In learning-capture.sh +# Tag concepts with review dates +echo "2026-01-24,zod-refine,$PROJECT" >> ~/.claude/review-queue.csv +``` + +Then periodically quiz yourself on past learnings. + +--- + +## Case Study: Hybrid Learning Principles + +What works best for learning with AI? Research and successful implementations point to the same pattern. + +### From Academic Research (2023-2025) + +Studies on AI-assisted learning show optimal results with: + +| Component | Purpose | Without It | +|-----------|---------|------------| +| **Human supervision** | Motivation, critical feedback, accountability | Students drift, lose direction | +| **AI assistance** | Immediate feedback, infinite patience, practice repetition | Slower iteration, less practice | +| **Progressive autonomy** | Decreasing supervision as skill grows | Never become independent | + +The key insight: AI excels at **practice and feedback**, humans excel at **motivation and critical evaluation**. + +### Real-World Implementation: Méthode Aristote + +A French educational platform (middle/high school) applies these principles at scale: + +**Their Model**: +- Dedicated human tutor = accountability + critical feedback +- AI-powered exercises = structured practice, expert-validated content +- Same tutor over time = relationship, understanding of progress + +**Transferable Principles for Developers**: + +| Aristote Principle | Developer Equivalent | +|--------------------|---------------------| +| Dedicated tutor | Mentor/senior + regular code reviews | +| AI validated by teachers | AI + verification through tests/linter/review | +| Level-based progression | Projects of increasing complexity | +| Long-term relationship | Consistent feedback from same people | + +**Their Philosophy**: *"Exigence, bienveillance, équité"* (Rigor, kindness, equity) + +Applied to coding: +- **Rigor**: Don't accept code you can't explain +- **Kindness**: AI is a tool, not a judge — use it without guilt +- **Equity**: Everyone can learn, pace varies — don't compare yourself to others + +→ [methode-aristote.fr](https://www.methode-aristote.fr/) + +### Building Your Own Support System + +You probably don't have a dedicated tutor, but you can create the structure: + +| Need | Solution | +|------|----------| +| Accountability | Weekly check-ins with peer/mentor | +| Critical feedback | Code reviews, pair programming | +| Structured practice | Deliberate exercises, not just project work | +| Progress tracking | Learning journal, skill assessment | + +The combination of **human accountability + AI practice** beats either alone. + +--- + +## 30-Day Progression Plan + +A concrete path from wherever you are to augmented developer. + +### Week 1: Foundations + +**Focus**: Build (or rebuild) core skills without heavy AI reliance. + +| Day | Activity | AI Usage | +|-----|----------|----------| +| 1-2 | Build simple feature WITHOUT AI | 0% | +| 3 | Review: Explain your code out loud | 0% | +| 4-5 | Refactor with AI review (not generation) | 20% | +| 6 | Debug issue without AI | 0% | +| 7 | Rest/reflection | — | + +**Success criteria**: Can explain every line you wrote. + +### Week 2: Understanding + +**Focus**: Use AI, but force understanding. + +| Day | Activity | AI Usage | +|-----|----------|----------| +| 1-2 | Ask AI to generate, explain EVERY line | 40% | +| 3 | Write code, AI reviews, you fix | 30% | +| 4-5 | AI explains new concept, you implement | 40% | +| 6 | Quiz yourself on week's concepts | 10% | +| 7 | Rest/reflection | — | + +**Success criteria**: Can modify AI-generated code confidently. + +### Week 3: Critical Usage + +**Focus**: Challenge AI suggestions, find their limits. + +| Day | Activity | AI Usage | +|-----|----------|----------| +| 1-2 | Ask for multiple approaches, choose best | 60% | +| 3 | Find bugs in AI-generated code | 50% | +| 4-5 | Complex feature with AI assistance | 60% | +| 6 | Explain entire feature to rubber duck | 10% | +| 7 | Rest/reflection | — | + +**Success criteria**: Can identify when AI is wrong. + +### Week 4: Augmented + +**Focus**: Full productivity with maintained understanding. + +| Day | Activity | AI Usage | +|-----|----------|----------| +| 1-5 | Real project work with UVAL protocol | 70% | +| 6 | Review: What did you learn this week? | 10% | +| 7 | Plan next learning goals | — | + +**Success criteria**: Fast AND you understand everything. + +--- + +## Red Flags Checklist + +Warning signs you're becoming dependent, and what to do: + +| Red Flag | What's Happening | Immediate Action | +|----------|-----------------|------------------| +| Can't start without AI | Outsourced problem decomposition | Code 30 min daily without AI | +| Don't understand AI's code | Copying without learning | Use `/explain-back` on EVERYTHING | +| Can't debug AI errors | Never learned debugging | Deliberately break code, fix manually | +| Anxiety without AI | Emotional dependence | It's a tool, not a lifeline — practice without | +| Rejected in interviews | Fundamentals atrophied | Practice whiteboard problems without AI | +| Always ask "how" never "why" | Surface-level usage | Force yourself to ask "why this approach?" | +| Every solution looks the same | AI has patterns, you need variety | Study multiple implementations manually | + +### Weekly Self-Audit + +Every Friday, ask: + +1. What did I learn this week that I didn't know before? +2. Could I have done this week's work without AI? +3. Did I understand everything I shipped? +4. Am I faster than last month? Am I smarter? + +If you're faster but not smarter, you're building dependency. + +--- + +## Sources & Research + +### Academic Research + +- **GitHub Copilot Impact Study (2024)** — [dl.acm.org](https://dl.acm.org/doi/10.1145/3613904.3642394) — Found productivity gains but identified skill atrophy risks in junior developers +- **Student Dependency Patterns in AI-Assisted Learning** — IACIS 2024 — Documented "learned helplessness" in students over-reliant on AI +- **Junior Developer Career Trajectories with AI Tools** — Software Engineering Institute — 3-year longitudinal study on skill development + +### Industry Reports + +- **Stack Overflow Developer Survey 2025** — AI tool adoption and perceived impact on learning +- **State of Developer Ecosystem 2025** — JetBrains — AI usage patterns by experience level +- **GitHub Octoverse 2025** — Code generation adoption rates and practices + +### Practitioner Perspectives + +- **Anthropic Claude Code Best Practices** — [anthropic.com](https://www.anthropic.com/engineering/claude-code-best-practices) — Official guidance on effective usage +- **ThoughtWorks Technology Radar** — AI-assisted development maturity model +- **Martin Fowler on AI Pair Programming** — Patterns for effective human-AI collaboration + +### Educational Frameworks + +- **Méthode Aristote** — [methode-aristote.fr](https://www.methode-aristote.fr/) — Hybrid human+AI tutoring model +- **Bloom's Taxonomy Applied to AI Learning** — Cognitive levels in AI-assisted education +- **Zone of Proximal Development with AI** — Vygotsky's theory applied to AI scaffolding + +### Methodology References + +See [methodologies.md](./methodologies.md) for: +- TDD with AI assistance +- Spec-Driven Development +- Eval-Driven Development for AI outputs + +--- + +## See Also + +### In This Guide + +- [Methodologies: TDD with Claude](./methodologies.md#tier-5-implementation) — Write tests first, then implement +- [Workflows: Spec-First](./workflows/spec-first.md) — Understand requirements before code +- [Workflows: Plan-Driven](./workflows/plan-driven.md) — Use /plan mode for complex work +- [Ultimate Guide: Mental Models](./ultimate-guide.md#mental-model) — How to think about Claude interactions + +### Templates & Examples + +- [Learning Mode CLAUDE.md](../examples/claude-md/learning-mode.md) — Configuration template +- [/quiz Command](../examples/commands/quiz.md) — Self-testing slash command +- [Learning Capture Hook](../examples/hooks/bash/learning-capture.sh) — Automated insight logging + +### External Resources + +- [Anthropic Prompt Engineering Guide](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) — Better prompts = better learning +- [The Pragmatic Programmer](https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/) — Timeless principles for deliberate practice + +--- + +## Quick Reference Card + +### UVAL Protocol Summary + +``` +U — UNDERSTAND FIRST + State → Brainstorm → Identify gaps → THEN ask AI + +V — VERIFY + Read every line → Explain out loud → Ask about gaps + +A — APPLY + Never copy raw → Rename/Restructure/Extend/Simplify + +L — LEARN + One insight per session → Log it → Review later +``` + +### The 70/30 Rule + +``` +Learning new things: 70% struggle, 30% AI +Applying known skills: 30% struggle, 70% AI +``` + +### Daily Minimums + +``` +☐ 15 min: Code something without AI +☐ 5 min: Explain one piece of code out loud +☐ 1 min: Log one thing you learned +``` + +### Claude Code Commands for Learning + +``` +/explain — Understand existing code +/quiz — Test your understanding +/teach — Learn something new +``` + +--- + +*This guide is part of the [Claude Code Ultimate Guide](./ultimate-guide.md). For questions or contributions, see the main repository.* diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index f88c0b4..1ec93ed 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -19,6 +19,17 @@ deep_dive: pdf_generation: "guide/workflows/pdf-generation.md" pdf_generator_skill: "examples/skills/pdf-generator.md" whitepapers_example: "whitepapers/README.md" + # Learning with AI (guide/learning-with-ai.md) + learning_quick_check: "guide/learning-with-ai.md:31" + learning_uval_protocol: "guide/learning-with-ai.md:127" + learning_claude_config: "guide/learning-with-ai.md:353" + learning_breaking_dependency: "guide/learning-with-ai.md:470" + learning_embracing_ai: "guide/learning-with-ai.md:518" + 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" + learning_capture_hook: "examples/hooks/bash/learning-capture.sh" # Architecture internals (guide/architecture.md) architecture_master_loop: "guide/architecture.md:60" architecture_tools: "guide/architecture.md:130"