Scenario: Developer Productivity with Claude

Scenario Description

You're building developer productivity tools using the Claude Agent SDK that help engineers explore unfamiliar codebases, understand legacy systems, generate boilerplate code, and automate repetitive development tasks. The agent leverages built-in tools (Read, Write, Bash, Grep, Glob) and integrates with MCP servers (e.g., for accessing internal documentation, package registries, or deployment systems) to provide a seamless development experience.

This scenario requires mastering the interplay between built-in tools and MCP server integration. You'll design tool selection strategies—knowing when to use Grep for rapid content search versus Glob for file discovery patterns. You'll configure MCP servers at both project level (.mcp.json in the repository) and user level (~/.claude.json for global tools), with environment variable expansion for credentials. The agent must navigate large, unfamiliar codebases efficiently, using incremental exploration and context management to avoid overwhelming the model.

Key challenges include handling ambiguous code patterns, understanding architectural decisions from scattered documentation, and generating code that matches the project's style and dependencies. You'll also design scratchpad files and exploration logs that help the agent (and the developer) track what's been learned and what still needs investigation.

Domains Tested

Key Concepts to Study

Tool Design & MCP Integration

Built-in tool selection: Grep for content search patterns, Glob for file path matching, Read/Write/Edit for file operations, Bash for build/test commands
MCP server integration: .mcp.json at project level for project-specific tools, ~/.claude.json at user level for personal tools
Environment variable expansion: configuring credentials (API keys, tokens) in MCP server definitions without hardcoding secrets
MCP resources as content catalogs: using MCP servers to serve README files, architecture docs, dependency manifests as queryable resources

Claude Code Configuration & Workflows

Incremental codebase exploration: designing a strategy to understand large codebases without reading everything (e.g., start with entry points, follow imports, inspect error traces)
Context management in large codebases: deciding what to load into the agent's context window (core modules vs. test files vs. vendored dependencies)
Scratchpad files: creating a _claude_notes.md to log findings, document assumptions, and track what still needs investigation

Agentic Architecture & Orchestration

Recursive exploration: when the agent discovers a dependency or import, deciding whether to follow it or defer exploration
Error-driven investigation: using test failures and error messages to guide code exploration (e.g., "Test fails at line 42; let me read the test and then the implementation")
Checkpoint patterns: periodically summarizing findings and asking the developer for direction ("I've found the auth module; should I focus on the login flow or token generation?")

Study Tips for This Scenario

Start with Entry Points and Dependency Graphs: When exploring an unfamiliar codebase, don't start with random file reads. Use Glob to find entry points (e.g., main.py, index.js, package.json), then use Grep to trace imports and dependencies. Build a mental (or literal scratchpad) map of module structure before diving into implementation details.
Design MCP Servers for High-Value Context: Rather than trying to embed all project documentation in the agent's context, create MCP servers that expose key resources (architecture docs, API specs, deployment guides) as queryable interfaces. This keeps context lean while making deep knowledge accessible on-demand.
Use Bash for Contextual Information: Don't just read code; run find, grep -r, and build/test commands to understand what's actually happening in the codebase. For example, run grep -r "TODO" src/ to find incomplete patterns, or npm list to see the dependency tree. This real-world context often reveals assumptions that code alone doesn't show.
Create Scratchpad Files for Complex Explorations: For large codebase investigations, maintain a _claude_notes.md file that logs discoveries, assumptions, and open questions. When you need to resume exploration in a new session, the scratchpad provides continuity and prevents redundant exploration. It also helps the developer understand the agent's reasoning process.