Scenario 04 · Teaching Aid

Developer Productivity
with Claude

Learn how to build developer productivity agents that explore codebases, understand legacy systems, generate boilerplate, and automate repetitive tasks using the Agent SDK's built-in tools and MCP integrations.

Agent SDK Built-in Tools MCP Integration Codebase Navigation Automation

Built-in Tools

📖ReadRead file contents

✏️WriteCreate or overwrite files

⚙️BashRun shell commands

🔎GrepSearch file content

🗂GlobFind files by pattern

01 · Use Cases

Four Core Developer Jobs — Click Each

🗺

Codebase Explorer

Map unfamiliar repos fast

🏚

Legacy Decoder

Understand old systems

🏗

Boilerplate Generator

Scaffold standard patterns

⚙️

Task Automator

Eliminate repetitive work

Codebase Explorer - Orientation at Speed

A developer joins a project. Instead of spending 2 days reading code, the Codebase Explorer agent maps the architecture in under 5 minutes. It uses Glob to find all key files, Read to scan entry points and config, Grep to find class definitions and routes, and Bash to check git history.

The output is a structured report: tech stack, directory annotated tree, key entry points, data flow diagram (in ASCII), and "top 3 things a new dev should know." This is a read-only agent, it never writes. Set max_turns=15 and restrict to read operations.

Typical tool flow

Glob("**") Read(package.json) Grep("class|def|func") Read(entry_points) Bash("git log") Report

Tool order matters. Always Glob first - it gives the agent a complete file inventory without reading any content. Then Read selectively.

02 · Built-in Tools Deep Dive

Select a Tool to Explore

Read

¸Write

¸Bash

Grep

Glob

Read()READ

Reads the full content of a file at the given path. Returns raw text.

Parameters

Parameter	Description
file_path	Absolute or relative path
offset	Optional: start from line N
limit	Optional: read at most N lines

Usage Rules

Read config/manifest files first to orient
Use offset+limit for large files
Read before Write - always understand the file first

Example

# Good: Oriented read
Read("package.json")
Read("src/index.ts")
Read("src/routes/user.ts", offset=1, limit=50)

03 · MCP Server Integrations

Expand Claude's Reach — Click to Explore

MCP servers extend the built-in tools with access to external systems. A developer productivity agent typically needs 3–5 MCP servers for full coverage of the dev lifecycle.

GitHub MCP

PR reviews, issues, code search

VCS

Available Tools

list_issuescreate_prget_pr_diffsearch_codeadd_comment

Use Case

Let the agent create PRs after making changes, search for similar code across the organization, and post automated review comments.

Scope permissions carefully. A productivity agent needs read+write on PRs but should NOT have merge permissions.

PostgreSQL MCP

Schema exploration, query assistance

DATABASE

Available Tools

querylist_tablesdescribe_tablelist_schemasget_table_stats

Use Case

Let the agent understand your data model by querying the schema directly, run read-only analytical queries, and generate migration scripts based on actual schema state.

Always connect to a read-only database replica, never production write access.

Fetch / Browser MCP

Docs, APIs, external resources

WEB

Available Tools

fetch_urlfetch_jsonsearch_web

Use Case

Let the agent retrieve library documentation, fetch API specs, look up error messages, and check dependency versions.

Use this for documentation retrieval, not general web browsing.

Sentry MCP

Error monitoring, stack traces

MONITORING

Available Tools

list_issuesget_issue_detailsget_stack_traceget_breadcrumbs

Use Case

Let the agent look up real production errors, read the full stack trace, then navigate directly to the relevant code to diagnose and fix the bug.

"Fix Sentry issue PROJ-142" becomes a full workflow: fetch stack trace - read failing file, diagnose, write fix, run tests.

Filesystem MCP

Extended file access outside workspace

FILES

Available Tools

read_filewrite_filelist_directorymove_filecreate_directory

Use Case

Useful when the dev agent needs to access files outside the project workspace, shared config files, monorepo access, or generating outputs to a separate docs directory.

The path argument restricts the filesystem server to a specific directory tree. Always restrict to the minimum necessary scope.

Secrets / Vault MCP

Secure credential management

SECURITY

Available Tools

get_secretlist_secretsset_secret

Use Case

Let the agent access secrets from Vault to populate .env files for local development or verify that all required secrets for a new feature are provisioned.

Productivity agents should NEVER write to secrets stores, only read. Never log secret values in output.

Configuration note: MCP servers are configured in .claude/settings.json under the mcpServers key. Claude discovers available tools automatically at session start via session.list_tools().

04 · Workflow Builder — Interactive

Watch the Agent Execute Real Dev Tasks

GlobGlob("**") to map full file tree of src/247 files found

ReadRead("package.json"), identify stack, entry pointsNext.js 14, TypeScript, Prisma

GlobGlob("src/app/**/route.ts") - find all API routes18 route files

ReadRead("src/app/api/users/route.ts") - examine main resourceCRUD + auth middleware

GrepGrep("class|interface|type") in src/types/ - map data model12 types found

BashBash("git log --oneline -15") - understand change velocityActive: 8 commits this week

WriteWrite("ARCHITECTURE.md") - output orientation guide3,200-word guide written

05 · Implementation Code

Reference Patterns

dev_agent.py — Core Agent Loop

# dev_agent.py — Developer Productivity Agent
import asyncio
from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

client = Anthropic()

async def run_dev_agent(task: str, workspace: str) -> str:
    server = MCP_SERVERS.get(infer_server(task))
    
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            mcp_tools = await session.list_tools()
            
            all_tools = BUILTIN_TOOLS + [
                {"name": t.name, "description": t.description,
                 "input_schema": t.inputSchema}
                for t in mcp_tools.tools
            ]
            
            messages = [{
                "role": "user",
                "content": f"Workspace: {workspace}\n\nTask: {task}"
            }]
            
            max_turns = 25
            turn = 0
            
            while turn < max_turns:
                response = client.messages.create(
                    model="claude-sonnet-4-6",
                    max_tokens=8192,
                    system=DEV_AGENT_SYSTEM_PROMPT,
                    tools=all_tools,
                    messages=messages
                )
                turn += 1
                
                if response.stop_reason == "end_turn":
                    return extract_text(response.content)
                
                if response.stop_reason == "tool_use":
                    tool_results = await execute_tools(
                        response.content, session, workspace
                    )
                    messages.append({"role": "assistant", "content": response.content})
                    messages.append({"role": "user", "content": tool_results})

explorers/codebase_explorer.py

# Codebase Explorer — maps an unfamiliar repo quickly

EXPLORE_PROMPT = """You are a codebase exploration specialist.
Given a project workspace, produce a comprehensive map of:
1. Project type and tech stack
2. Top-level architecture (key directories and their roles)
3. Entry points (main.py, index.ts, cmd/, etc.)
4. Core data models and their relationships
5. External dependencies and integrations

## Exploration Strategy
- Start with Glob("**/{package.json,requirements.txt,go.mod}")
- Use Glob to get the directory tree structure
- Read only the most important files (entry points, config, key models)
- Use Grep to find patterns: class definitions, imports, API routes
- Run Bash("git log --oneline -20") for recent change velocity
- Never read more than 20 files — be selective
"""

async def explore_codebase(workspace: str) -> str:
    return await run_dev_agent(
        task="Produce a comprehensive codebase map",
        workspace=workspace,
        system_prompt=EXPLORE_PROMPT,
        max_turns=15
    )

generators/scaffolder.py

# Boilerplate Scaffolder — generates style-matched code

SCAFFOLD_PROMPT = """You are a code scaffolding specialist.
You generate new code that perfectly matches the existing project's:
- Naming conventions
- File organization patterns
- Import style (absolute vs relative)
- Error handling approach
- Testing patterns

## Process
1. Read 2-3 existing similar files to understand the project's style
2. Note the exact patterns used (don't improvise)
3. Generate new files indistinguishable from handwritten code
4. Create the implementation file AND the test file
5. Run the test suite after generating to verify

## Rules
- NEVER invent abstractions that don't exist in the codebase
- Match the existing error handling pattern exactly
- Generate tests that follow the existing test patterns
"""

async def generate_scaffold(resource: str, workspace: str) -> str:
    return await run_dev_agent(
        task=f"Generate complete scaffold for: {resource}",
        workspace=workspace,
        system_prompt=SCAFFOLD_PROMPT,
        max_turns=20
    )

system_prompts.txt

═══ CORE DEV AGENT ═════════════════════════════════════
You are a developer productivity agent working inside a software project.
You have access to the file system (Read, Write, Glob, Grep) and
can run shell commands (Bash).

## Approach
Read before you write. Never modify a file without reading it first.
Understand the existing patterns before generating new code.
Run tests after making changes. Report failures with specifics.

## File Operation Rules
- Always use Glob to orient before opening specific files
- Read only what you need
- When writing, preserve the file's existing style exactly
- Never delete files without explicit instruction

## Bash Safety
- Never run destructive commands (rm -rf, DROP TABLE, git push --force)
- For database operations, prefer read-only queries
- Run tests with --dry-run first when available

═══ LEGACY DECODER ═════════════════════════════════════
Focus: understanding without changing.
Map data flows. Identify undocumented business rules.
Document "why" not just "what". Flag dangerous patterns.

═══ TASK AUTOMATOR ══════════════════════════════════════
Focus: eliminate repetition across the codebase.
Grep for duplicated patterns. Ask before assuming automation scope.
Generate automation scripts, not one-off fixes.

06 · Agent Patterns for Dev Tools

Design Patterns — Click to Expand

Read Before You Write - Always

Core Rule

The single most important rule: Read the file before writing it. An agent that writes without reading will generate code that violates the project's existing conventions.

System prompt enforcement: "Before modifying any file, Read it first. Before generating a new file of type X, Read 2 existing files of type X." This eliminates 80% of style mismatch issues.

Pattern: Read - Parse conventions - Write style-matched output. The Read cost (1 tool call) pays back 10x in fewer correction cycles.

Glob-First Orientation

Core Rule

Before doing anything else, run Glob("**") to get the complete file inventory. This takes 1 tool call and 0 content tokens - just paths. An oriented agent makes dramatically better decisions.

Analog: you wouldn't start debugging without first looking at the project structure. Glob is instant orientation at minimal cost.

Put Glob orientation in the system prompt: "Your first action in any new session MUST be Glob('**') to understand the project layout."

Incremental Verification

Core Rule

After every Write, run a verification command with Bash. Run the specific test file, or at minimum run the linter. Never write 5 files and run tests once at the end.

Each Write should be followed by: Bash("npm test -- path/to/test"). If the test fails, fix immediately before writing the next file.

In the system prompt: "After each file you write, run the most specific test you can. Do not proceed to the next file if the test fails."

Scope Confirmation for Bulk Operations

Safety Critical

Any operation that touches more than 3 files is a "bulk operation." Before executing it, the agent should pause and output a proposed change manifest.

Without this, a simple "add TypeScript types everywhere" task can modify 80 files. Most will be fine, but 3 will have subtle bugs.

System prompt: "If your plan involves modifying more than 3 files, output a numbered list of all files you plan to change. Wait for confirmation."

Surgical Grep vs Broad Read

Efficiency

When you need to find something specific, all usages of a function, and all API routes use Grep. Don't read 20 files hoping to find it. Grep returns the answer in 1 tool call.

Grep use cases: finding function call sites before refactoring, discovering deprecated API usage, counting module imports, finding config key references.

"Grepping before reading" is the dev agent equivalent of index scans vs full table scans. Grep is O(files), Read is O(content).

MCP + Built-in Tools Composition

Advanced

The most powerful workflows combine MCP server data with built-in file tools. Example: fetch a Sentry error (MCP) - Grep for the failing function - Read the file - Write the fix - run tests (Bash).

Composition pattern: MCP tools provide external context (error traces, database schemas, PR diffs), built-in tools perform local file operations.

Pass all MCP tools + all built-in tools together. The agent picks the right tool for each step automatically.

07 · Knowledge Check

Developer Productivity
with Claude

Four Core Developer Jobs — Click Each

Codebase Explorer - Orientation at Speed

Select a Tool to Explore

Expand Claude's Reach — Click to Explore

Watch the Agent Execute Real Dev Tasks

Reference Patterns

Design Patterns — Click to Expand

Test Your Understanding

Get in Touch instantly

Need a Consultation?

Services

Industries

Helpful Links

Locations