worked-examples

Worked Examples & Tutorials

Step-by-step walkthroughs of real Claude Code workflows. Each tutorial shows the exact commands, expected output, and decision points.

Tutorial 1: Set Up Claude Code for a New Project

Goal: Configure Claude Code from scratch for a TypeScript/React project.

Steps:

1. Generate starter CLAUDE.md

/init

Claude analyzes your codebase and generates CLAUDE.md with build commands, test instructions, and detected conventions.

2. Review and customize CLAUDE.md Open the generated file. Keep it under 200 lines. Focus on:

• Build/test commands: pnpm install, pnpm test, npx tsc --noEmit
• Coding standards: "Use 2-space indentation", "Prefer named exports"
• Architecture notes: "API routes in src/api/, components in src/components/"

3. Create path-scoped rules

mkdir -p .claude/rules

Create code-style.md with paths frontmatter for **/*.ts, **/*.tsx. Create testing.md with paths frontmatter for **/*.test.*.

4. Configure MCP servers

/cc-mcp add context7    # Library documentation
/cc-mcp add perplexity  # Web research

5. Set up hooks

/cc-hooks create auto-format     # Format on file write
/cc-hooks create security-guard  # Block dangerous commands

6. Validate configuration

/cc-setup --audit

Check the audit score. Fix any warnings.

Expected outcome: Audit score > 80, all checks green.

---

Tutorial 2: Build a Pre-Commit Security Hook

Goal: Create a hook that blocks commits containing secrets.

Steps:

1. Create the hook script Create .claude/hooks/scripts/secret-scanner.sh:

#!/usr/bin/env bash
set -euo pipefail

input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name // empty')

if [[ "$tool_name" != "Bash" ]]; then
  echo '{"decision":"passthrough"}'
  exit 0
fi

command=$(echo "$input" | jq -r '.tool_input.command // empty')

# Block git commits that might contain secrets
if echo "$command" | grep -qE 'git (add|commit)'; then
  # Check staged files for secret patterns
  if git diff --cached --name-only 2>/dev/null | xargs grep -lE '(API_KEY|SECRET|PASSWORD|TOKEN)=[^$]' 2>/dev/null; then
    echo '{"decision":"block","reason":"Staged files contain potential secrets. Remove them before committing."}'
    exit 0
  fi
fi

echo '{"decision":"passthrough"}'

2. Make it executable

chmod +x .claude/hooks/scripts/secret-scanner.sh

3. Register in settings.json Add to .claude/settings.json under hooks.PreToolUse:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": ".claude/hooks/scripts/secret-scanner.sh"
      }
    ]
  }
}

4. Test the hook

/cc-hooks test secret-scanner

Expected outcome: Hook blocks commits with hardcoded secrets, passes clean commits.

---

Tutorial 3: Run a Multi-Agent Code Review

Goal: Review a PR using the council with expert-panel protocol.

Steps:

1. Identify the review target

/cc-council src/auth/ --preset security --depth deep

2. Observe the council process The council spawns multiple expert agents:

• Security specialist examines auth patterns
• Quality reviewer checks error handling
• Performance analyst reviews efficiency

3. Read the scoring output Each scope gets an independent score:

Security:    7.2/10 (2 HIGH, 1 MEDIUM findings)
Quality:     8.5/10 (1 MEDIUM finding)
Performance: 9.1/10 (no significant findings)

4. Address findings Start with HIGH severity findings. Fix them, then re-run:

/cc-council src/auth/ --preset security --changed-only

5. Get final verdict Once all HIGH findings are resolved, the council issues APPROVE or APPROVE_WITH_CONDITIONS.

Expected outcome: Security findings identified and resolved, final score > 8.0.

---

Tutorial 4: Create a Custom Research Agent

Goal: Build a specialized agent for researching library APIs.

Steps:

1. Define the agent

/cc-agent create library-researcher

2. Configure the agent file In .claude/agents/library-researcher.md:

---
name: library-researcher
description: Researches library APIs and produces usage guides
model: claude-haiku-4-5-20251001
tools:
  - Read
  - Grep
  - Glob
  - WebFetch
---

3. Write the system prompt Define: role, mandatory workflow, output format. The agent should:

• Accept a library name
• Search for official documentation using Context7
• Extract key APIs, patterns, and gotchas
• Return a concise summary

4. Use the agent Invoke in conversation:

Use the library-researcher agent to research the latest Prisma ORM query patterns

Expected outcome: Agent returns a focused summary of Prisma query patterns with code examples.

---

Tutorial 5: Optimize a Context-Limited Session

Goal: Complete a large task without hitting context limits.

Steps:

1. Check current budget

/cc-budget audit

See how much context is consumed by CLAUDE.md, rules, skills, MCP schemas.

2. Plan the session If working budget < 100k tokens:

• Disconnect unused MCP servers: /mcp
• Disable non-essential skills
• Use subagents for research

3. Delegate research

Research the auth module architecture using a Haiku subagent

The subagent explores files in its own context, returns only a summary.

4. Compact proactively At 70% context utilization:

/compact Focus on the auth refactor: keep the API contract changes, test plan, and file paths

5. Switch models as needed

/model claude-haiku-4-5-20251001   # For file searches
/model claude-sonnet-4-6            # For implementation

6. Monitor costs

/cost
/cc-perf tips

Expected outcome: Complex task completed within budget, no auto-compact interruptions.

---

Tutorial 6: Debug Recurring Mistakes with Self-Healing

Goal: Stop Claude from repeating the same error across sessions.

Steps:

1. Check existing lessons

# Review current lessons-learned.md
/cc-help lessons-learned

2. When an error occurs The PostToolUseFailure hook automatically captures it:

### Error: Read failure
- Tool: Read
- Input: /path/to/directory
- Error: EISDIR: illegal operation on a directory
- Status: NEEDS_FIX

3. Fix and document After fixing the issue, update the lesson:

- Status: RESOLVED
- Fix: Use `ls` or `Glob` for directories, `Read` for files only
- Prevention: Always check if path is a file before using Read tool

4. Promote patterns to rules If the same error appears 3+ times: Create a new rule in .claude/rules/ with the prevention strategy.

5. Verify in next session The fix is loaded as a rule. Claude reads it and avoids the mistake.

Expected outcome: Error never recurs. Lessons-learned.md grows into a project-specific knowledge base.

---

Tutorial 7: Set Up Persistent Memory

Goal: Configure the three-tier memory system for cross-session learning.

Steps:

1. Tier 1: CLAUDE.md and Rules Already set up in Tutorial 1. These are your explicit, team-shared instructions.

2. Tier 2: Auto Memory Enable in settings (on by default since v2.1.59):

{ "autoMemoryEnabled": true }

Claude automatically saves useful findings to ~/.claude/projects/<project>/memory/.

3. Tell Claude to remember things

Remember that the API tests require a local Redis instance on port 6380

Claude saves this to auto memory. Next session, it knows.

4. Review auto memory

/memory

Browse saved memories. Edit or delete as needed.

5. Tier 3: MCP-Backed Memory (Optional) For semantic search across memories, add an MCP memory server:

/cc-mcp add memory

6. Verify persistence Start a new session. Ask about Redis. Claude should recall the port without prompting.

Expected outcome: Knowledge persists across sessions. Build commands, preferences, and project quirks are remembered.

---

Tutorial 8: Automate PR Review in GitHub Actions

Goal: Set up Claude Code as an automated PR reviewer in CI.

Steps:

1. Generate the workflow

/cc-cicd generate github-actions --template pr-review

2. Review the generated workflow .github/workflows/claude-review.yml:

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-haiku-4-5-20251001
          prompt: |
            Review this PR for security issues, code quality, and test coverage.
            Focus on: input validation, error handling, and edge cases.
            Output a structured review with severity ratings.

3. Add secrets In GitHub repo settings → Secrets → Add ANTHROPIC_API_KEY.

4. Test with a PR Create a test PR. The action runs and posts review comments.

5. Tune the prompt Adjust the review prompt based on results. Add project-specific guidance.

Expected outcome: Every PR gets an automated Claude review within minutes.

---

Quick Reference

Tutorial	Topic	Difficulty	Time
1	Project setup	Beginner	10 min
2	Security hooks	Intermediate	15 min
3	Code review council	Intermediate	10 min
4	Custom agents	Intermediate	15 min
5	Context optimization	Advanced	20 min
6	Self-healing	Intermediate	10 min
7	Persistent memory	Beginner	10 min
8	CI/CD integration	Advanced	20 min