Skip to main content

Phase 2 — Fluency: using Claude Code daily

Duration: 4 weeks · Dedication: 8–10h/week · Tracks: 🟢🔵🟣 (all modules essential) Prerequisite: Phase 1 completed (Claude Code installed, CLAUDE.md configured, structured prompts, first project delivered). Primary focus: Claude Code · Transferable concepts: marked with 🌐.

Phase objective​

Move from "I use Claude Code occasionally" to "Claude Code is a fixed pair in my daily work". By the end of this phase, automation, test generation, debugging, code review, documentation and navigating large codebases stop being manual tasks.

By the end of this phase you can:

  • Refactor and generate multi-file code with Claude Code
  • Work in spec-driven mode (write the spec, let Claude implement)
  • Practice TDD with Claude Code reliably
  • Automate commits, PRs and code review with Claude Code + GitHub Actions
  • Debug real bugs using structured workflows
  • Keep documentation in sync with code
  • Navigate and contribute to large codebases without drowning in context

Conventions​

  • Type: 📚 Official doc · 📖 Article/Paper · 🎓 Course · 🎬 Video/Podcast · 🛠️ Hands-on/Repository
  • Language: [PT] Portuguese · [EN] English
  • Cost: [Free] · [Paid] · [Freemium]
  • Level: beginner · intermediate · advanced
  • ⭐ essential · 🌐 universal concept (transferable to any agent)

M5 · Development task automation with Claude Code

Why this module​

You already know how to use Claude Code for individual tasks. Here you consolidate the automation patterns that come up every day: multi-file refactoring, boilerplate generation, repetitive transformations, small migrations. The gain is moving from "thinking how to ask" to having reflex prompts and flows.

Topics​

  • Refactoring with Claude Code: moving code between files, extracting functions, consistent renaming, applying patterns
  • Multi-file editing in one session (Claude Code is natively multi-file)
  • Boilerplate generation: API routes, components, schemas, migrations
  • Repetitive transformations: applying the same change in N places
  • Prompt patterns for recurring tasks (personal templates)
  • When to use plan mode (Shift+Tab) vs. direct mode
  • When to activate thinking modes (think, think hard, ultrathink)
  • When NOT to use Claude Code (trivial tasks, tasks where you're already fluent)

Materials​

Official documentation ⭐​

Courses and guides​

In Portuguese​

Practical exercise​

In a real project of yours, do 5 tasks with Claude Code:

  1. Refactor a large function into 3 smaller ones
  2. Consistently rename a variable/concept across 5+ files
  3. Add typing (TypeScript / Python type hints) to a module without types
  4. Generate boilerplate for a new API route + corresponding test
  5. Apply the same transformation (e.g.: replace console.log with structured logger) across N files

Document in my-claude-playbook.md the prompt template that worked for each type of task. This file will become your forever reference.

Definition of Done​

  • You have 3+ personal prompt templates for recurring tasks
  • Know when to use plan mode and when to go direct
  • Know to activate thinking mode when problem requires
  • Identify in seconds when NOT to use Claude Code

M6 · Spec-driven development with Claude

Why this module​

🌐 Spec-driven development became an emerging standard in 2025/26 — write the specification first and let the agent implement. Instead of loose prompts, you write a document explaining intent, constraints and acceptance criteria. Result: less iteration, less rework, much higher quality.

Anthropic documents the pattern as Explore → Plan → Code → Commit. GitHub created Spec Kit, an open source toolkit for this flow. Several organizations reported throughput change when adopting.

Topics​

Universal 🌐​

  • What spec-driven development is and why it works
  • Structure of a good spec: context, objectives, requirements, constraints, acceptance criteria, edge cases
  • Explore → Plan → Code → Commit flow
  • Spec vs. PRD vs. design doc — when to use each format

Claude Code specific​

  • Plan mode (Shift+Tab) as primary tool for interactive spec
  • CLAUDE.md as persistent spec for the entire project
  • .claude/rules/ for scoped rules
  • Subagents receiving specs as input

Tools​

  • GitHub Spec Kit — official toolkit, supports Claude Code (constitution → specify → plan → tasks → implement)
  • claude-code-spec-workflow (Pimzino) — automated workflows for spec-driven dev and bug fix
  • cc-sdd (gotalab) — minimal spec-driven harness with Skills

Materials​

Conceptual ⭐​

Tools (hands-on) ⭐​

  • ⭐ 🛠️ GitHub Spec Kit · [EN] [Free] Official open source toolkit. Supports Claude Code, Copilot, Gemini CLI. Use during the exercise.

  • 🛠️ claude-code-spec-workflow (Pimzino) · [EN] [Free] Automated workflow for Claude Code: Requirements → Design → Tasks → Implementation, plus a bug fix workflow.

  • 🛠️ cc-sdd (gotalab) · [EN] [Free] More minimalist, focuses on long-running autonomy with Skills. Compatible with various agents.

Guided tutorial​

Anthropic documentation​

Practical exercise​

Pick a small feature from one of your projects (or start a new project) and build via spec-driven:

  1. Install GitHub Spec Kit (uv tool install spec-kit-cli or equivalent)
  2. Initialize the flow: constitution → specify → plan → tasks → implement
  3. Use Claude Code as agent in all stages
  4. Compare result with what you'd do with loose prompts
  5. Document in learnings-spec-driven.md:
    • How long each stage took
    • How much rework occurred vs. your previous flow
    • Where the spec was insufficient and you had to iterate

Definition of Done​

  • You completed at least 1 feature via complete spec-driven flow
  • Have informed opinion on when spec-driven is worth the overhead vs. when it's overkill
  • Know how to use CLAUDE.md as persistent spec layer
  • Know at least 1 spec workflow tool (Spec Kit, Pimzino, or cc-sdd)

M7 · Test-Driven Development with Claude Code

Why this module​

🌐 TDD with AI is particularly powerful because the agent performs much better when it has a verifiable target (tests that need to pass). It's the modern, justified version of TDD — the agent iterates until green, without stubbornness.

The trinity Red → Green → Refactor gains a fourth step: Validate (you check that the agent didn't cheat, didn't write tests for the code it already wrote, didn't ignore edge cases).

Topics​

Universal 🌐​

  • Red → Green → Refactor → Validate
  • Why TDD with agent is different from human TDD
  • How to avoid anti-patterns: agent writing empty tests, over-mocking, shortcuts
  • How to give verifiable targets to the agent (specific asserts, explicit edge cases)

Claude Code specific​

  • Write tests, commit; code, iterate, commit pattern (Anthropic best practices)
  • Use plan mode to write the test spec first
  • "Verifier" subagent that reviews if the agent didn't cheat
  • Custom TDD Skill (several exist in the community)

Materials​

Conceptual ⭐​

Community Skills and tools 🛠️​

Practical articles​

Practical exercise​

Pick a new feature you'll need to implement (something real, ~2–4h of normal work).

  1. Create a branch
  2. Start Claude Code session
  3. Use the prompt: "Let's do TDD. For feature X, write the tests first covering happy paths, error cases and edge cases. Don't implement the code yet. Confirm tests fail."
  4. Review the tests manually — do they reflect the behavior you want?
  5. Request implementation: "Now implement minimal code to make all tests pass. Don't modify the tests."
  6. Verify it passed
  7. Refactor: "Refactor for readability without changing behavior. Confirm tests keep passing."
  8. Manual validate: run tests, read implementation, ensure no improper mocks

Document in learnings-tdd.md: what worked, where Claude tried to cheat, which prompts prevented cheating.

Definition of Done​

  • You did at least 1 entire feature via TDD with Claude Code
  • Identify in 30 seconds if Claude is "cheating" (writing tests for what it already wrote)
  • Have 1 prompt template for TDD ready in your playbook
  • Know at least 1 Skill or slash command for TDD (installed or referenced)

M8 · Git, PR and code review with Claude Code

Why this module​

Git, PRs and code review consume a lot of devs' cognitive time. Claude Code automates these three points with high quality — from semantic commit messages to structured PR review in GitHub Actions.

Anthropic maintains an official Code Review plugin with 4-phase pipeline (qualification → summary → parallel review by 5 specialized agents → final verification). It's in research preview on Team/Enterprise plans.

Topics​

Daily Git workflow with Claude Code​

  • Generation of semantic commit messages
  • Generation of PR descriptions (title + body + checklist)
  • Resolution of merge conflicts with Claude Code
  • "Co-authored-by: Claude" attribution (convention, not mandatory)

Code review​

  • Integrated /review command
  • Official Anthropic Code Review plugin (5 specialized agents)
  • Comment @claude review on GitHub PRs for on-demand review
  • Comparison: what Claude catches well vs. what it misses

Automation with GitHub Actions​

  • anthropics/claude-code-action — official Action
  • Trigger on PR open/update
  • Post review as inline comments
  • Configure via CLAUDE.md and workflow YAML
  • Cost and security (secrets, allowlists)

Materials​

Official documentation ⭐​

Practical guides ⭐​

Honest reviews​

Git workflow​

Community Skills​

Practical exercise​

  1. Configure a commit message template in your project's CLAUDE.md (Conventional Commits, for example)
  2. Use Claude Code to create 5 commits in a real branch following the template
  3. Create a PR with description generated by Claude Code (title, body, checklist)
  4. Configure claude-code-action in the repository (use the official Anthropic Action)
  5. Open a new PR and watch the automatic review running
  6. Critique the review: what did Claude catch? What did it miss? Compare with the LogRocket article
  7. Document in learnings-pr-review.md

Definition of Done​

  • You generate commit messages and PR descriptions exclusively via Claude Code
  • Have claude-code-action running in at least 1 of your repositories
  • Know when automatic review is reliable and when it isn't
  • Configured @claude review trigger or similar for on-demand review

M9 · Debugging and error resolution with Claude Code

Why this module​

Debugging is the task where Claude Code shines most — because it combines three things: reading many files (call stack), multi-step reasoning (from symptom to root cause) and iteration until green (running tests/scripts and validating fix). Practical studies report ~95% first-time fix-rate with structured workflow vs. ~40% with loose prompts.

Topics​

Structured debugging workflow with Claude Code​

  • Phase 1 — Investigation: capture full stack trace, attach relevant code, request analysis (DON'T ask for fix yet)
  • Phase 2 — Hypothesis and validation: request 2–3 hypotheses, validate with additional reading or logs
  • Phase 3 — Minimal fix: apply minimal correction and run tests
  • Phase 4 — Regression: request automated regression test for the specific bug

Universal principles 🌐​

  • Always trace to root cause, never fix only the symptom
  • Full stack trace, not just the last line
  • Reproduce the bug first, fix later
  • Regression test before closing

Claude Code specific​

  • think hard or ultrathink for really difficult bugs
  • Specialized debugging subagent (defined in .claude/agents/)
  • PostToolUse hooks to run tests automatically after edit

Materials​

Official documentation and blog ⭐​

Practical guides ⭐​

Community Skills and patterns​

Practical exercise​

Take 2 real bugs (from your work or your personal project backlog):

Bug A — medium: clear stack trace, quick hypothesis.

  1. Paste full stack trace into Claude Code
  2. Request analysis without fix
  3. Validate hypothesis
  4. Apply fix and run tests
  5. Create regression test

Bug B — difficult: intermittent, multi-file, or behavioral.

  1. Use ultrathink or think hard
  2. Use plan mode to plan investigation first
  3. Consider "investigator" subagent (you define in .claude/agents/)
  4. Document the path to root cause

Note in learnings-debugging.md:

  • Time for each bug with Claude Code
  • Estimated time if doing alone
  • Where Claude was essential vs. where it got in the way

Definition of Done​

  • You use Claude Code as primary debugging tool for non-trivial bugs
  • Have 1 debugging prompt template in your playbook
  • Create regression test for every non-trivial bug you fix
  • Know when to activate ultrathink

M10 · Automated technical documentation

Why this module​

Documentation is the most obvious place where AI adds value — and yet most teams generate poor documentation because they treat it as a "one-time task". Claude Code allows keeping documentation synchronized with code via hooks, slash commands and recurring workflows.

Topics​

Types of automatable documentation​

  • Inline: JSDoc, docstrings (Python), TSDoc (TypeScript)
  • README: structure, badges, examples, troubleshooting
  • API docs: OpenAPI/Swagger generated from types/schemas
  • Diagrams: Mermaid and PlantUML generated from code (sequence, ER, architecture)
  • Changelogs: generated from commits and PRs
  • ADRs (Architecture Decision Records) assisted by Claude

Keeping documentation synchronized​

  • Custom /update-docs slash command
  • PostToolUse hook that requests doc sync after big change
  • "Documentation reviewer" subagent that runs on PRs

Materials​

Official documentation ⭐​

Guides and examples​

Hands-on​

  • 🛠️ Take any of your projects without README and have Claude generate a complete README from the code
  • 🛠️ Take any function without docstring and request inline documentation with examples

Practical exercise​

  1. In one of your projects without a decent README, request from Claude a complete README (structure: What it is, installation, usage, architecture, contributing, license)
  2. Add Mermaid architecture diagram to README, generated by Claude from code
  3. Create a custom slash command /update-docs in .claude/commands/update-docs.md that standardizes the task
  4. Create a changelog generated from commits with Claude
  5. Add rich docstrings in at least 1 critical module

Definition of Done​

  • Has quality README generated in at least 1 of your projects
  • At least 1 Mermaid diagram in a README
  • Has /update-docs slash command or equivalent in your setup
  • Knows how to generate changelog from scratch in seconds

M11 · Large codebases with Claude Code

Why this module​

In small projects, Claude Code "just works". In monorepos and large codebases, without strategy, it drowns: reads too many files, loses context, repeats work, ignores scoped conventions.

The solution has 3 pillars: hierarchical CLAUDE.md, subagents for exploration, and orchestrator pattern with parallelization. Teams report ~4x reduction in context overhead with proper scoping.

Topics​

CLAUDE.md hierarchy​

  • ~/.claude/CLAUDE.md — global dev preferences
  • <project>/CLAUDE.md — project conventions
  • <project>/<module>/CLAUDE.md — area-scoped (frontend, backend, infra)
  • .claude/rules/ for even more granular rules

Subagents for exploration​

  • "Code search agent" — exploration in separate context window
  • "Architecture agent" — understands structure without polluting main context
  • Subagents report summaries, not file dumps

Orchestrator pattern (4 phases)​

  1. Clarify — main agent understands the request
  2. Plan — generates plan with independent tasks
  3. Dispatch — fires subagents in parallel
  4. Verify — main agent consolidates and validates

Patterns in monorepo​

  • 1 subagent per module (auth, db, api, frontend)
  • Specific Skills per area
  • Shared team plugins
  • Shared convention via AGENTS.md (emerging cross-tool standard)

Materials​

Official Anthropic ⭐​

Practical cases ⭐​

Practical exercise​

Use a large repository (your work monorepo, or clone a large open source like vercel/next.js, microsoft/vscode, kubernetes/kubernetes):

  1. Map structure: create CLAUDE.md at root with repo map, modules, global conventions
  2. Scope: create CLAUDE.md in at least 2 subfolders (different modules)
  3. Create 2 specialized subagents in .claude/agents/:
    • An "explorer" that maps code without editing
    • A "module-X-expert" for a specific module
  4. Do a real task that touches 2+ modules and use the orchestrator pattern (main Claude delegates to subagents)
  5. Compare: how many times did Claude need to re-read the same file? How much context was saved?
  6. Document in learnings-large-codebase.md

Definition of Done​

  • Has hierarchical CLAUDE.md in at least 1 of your large codebases
  • Defined at least 2 subagents in .claude/agents/
  • Executed at least 1 multi-module task with orchestrator pattern
  • Knows when subagent is worth the overhead vs. when it's overkill

Phase 2 Capstone (integrative deliverable)

Apply the 7 modules in a real project of yours (your product, side project, or open source contribution). Doesn't need to be a giant feature — pick something with ~10–15h of real work.

Requirements​

  • Feature implemented via spec-driven (M6)
  • Implementation followed TDD (M7)
  • At least 5 commits with messages generated via Claude Code (M8)
  • PR with automatic description (M8)
  • claude-code-action active in the repository (M8)
  • At least 1 real bug debugged with structured workflow documented in learnings-debugging.md (M9)
  • README and Mermaid diagram updated via Claude Code (M10)
  • If monorepo/large codebase: hierarchical CLAUDE.md + 1 custom subagent (M11)
  • Final file LEARNINGS-PHASE-2.md consolidating learnings

Self-assessment at the end of Phase 2

  • I have 3+ personal prompt templates for recurring tasks
  • Already did entire feature via spec-driven with Spec Kit or equivalent
  • Already did entire feature via TDD with Claude Code
  • Have claude-code-action running in at least 1 repo
  • Use Claude Code as primary debugging tool
  • Know how to generate README + Mermaid diagram in minutes
  • Have hierarchical CLAUDE.md in large codebase (if applicable)
  • Defined at least 1 subagent in .claude/agents/
  • Know when subagent is worth the overhead

If you checked 7+ items, you're ready for Phase 3.

Next phase​

Phase 3 — Advanced: extending the agent (4 weeks) covers modules M12 to M18: headless and CI/CD, MCP (Model Context Protocol), subagents in depth, custom hooks and slash commands, Skills and plugins, advanced context control, and security/prompt injection.