Agent workbench (capstone)

1 · The repo layout essential

You've felt this failure even if you've never named it. You spent an afternoon teaching Claude your project's quirks — the test command, the module you never touch, the review style you like — and it was great. Then a teammate opened the same repo, got a Claude that knew none of it, and shipped a change your way of working would have caught. All that steering lived on your laptop, in your head and your loose config, and it evaporated at the edge of your machine. A workbench fixes exactly that: it makes the steering part of the repo.

Think of the repo layout like the shared kit in a professional kitchen. It isn't the food — it's the mise en place: knives sharpened, stations labelled, the recipe card pinned where everyone reads it. Any cook who walks in inherits the setup and works to the same standard on day one. That is what the .claude/ folder is: a station every teammate's Claude sits down at, pre-configured. CLAUDE.md is the recipe card (conventions and commands), settings.json is the safety guard on the equipment (permissions and hooks), and skills/, agents/, and mcp/ are the specialist tools bolted to the bench.

The precise idea worth holding onto: everything that shapes Claude's behaviour lives in version-controlled files, not in a person. Why does that separation earn its own opening section? Because it flips configuration from a private habit into a shared, reviewable, git-tracked artifact — the same shift that turned "works on my machine" scripts into real infrastructure. The common mistake is treating .claude/ as personal scratch and .gitignore-ing it; do that and you're back to steering that dies on one laptop. Commit it, and one git pull hands the whole team your judgment.

tree.txtyour-project/
├── CLAUDE.md                       # K1: conventions, commands, guardrails
├── .claude/
│   ├── settings.json               # K1/K2: permissions + a Stop hook (tests)
│   ├── commands/review.md          # K2: /review slash command
│   ├── skills/house-style/SKILL.md # K4: team code + doc conventions
│   └── agents/code-reviewer.md     # K5: least-privilege reviewer subagent
├── mcp/server.py                   # K6: MCP server exposing project tools/data
└── .github/workflows/claude-review.yml   # K2: headless review on PRs

2 · Wire the config essential

The scariest bug an agent can hit isn't a wrong answer — it's a right-looking action taken without asking. An agent that "helpfully" runs git push to a shared branch, or edits a vendored library you'd sworn never to touch, has done something no test will catch until it's already out. The config file is where you decide, up front and in writing, which actions Claude may take alone and which must stop for a human. Get it wrong and you either babysit every step (useless) or hand over the keys to the whole car (dangerous).

The mental model is a building's access-card system. Some doors open for anyone with a badge (the break room), some need a manager's card (the server room), and a few are welded shut no matter whose card you wave (the roof). Claude Code's settings.json works the same way: an allow list is the doors that open freely, the deny list is the welded doors — and crucially, deny always beats allow. If an action matches both, deny wins. That ordering is the whole safety story: a broad allow pattern can never accidentally re-open something you explicitly closed.

Two things go in this one file, and it's worth seeing why they belong together. Permissions answer "what may Claude do?"; hooks answer "what happens automatically at certain moments?" — like a Stop hook that runs your tests every time Claude finishes a turn. The common mistake is to lean on the allow list alone, quietly omitting the dangerous stuff and hoping it never comes up. Omission isn't protection: an unlisted action falls through to "ask," which is fine until a broad pattern you added later silently covers it. Spell the dangerous actions out on the deny list so the guarantee is explicit, not accidental.

settings.json{
  "permissions": {
    "allow": ["Bash(pytest:*)", "Bash(ruff:*)", "Read(*)", "Edit(src/**)"],
    "deny":  ["Bash(git push:*)", "Edit(vendor/**)"]
  },
  "hooks": {
    "Stop": [ { "matcher": "*", "hooks": [
      { "type": "command", "command": "pytest -q || echo TESTS-FAILED" } ]} ]
  }
}

3 · The MCP server (K6) intermediate

Here's the ceiling you hit with a well-configured Claude that has no tools of its own. You ask "which tickets are open on the billing component?" and it can't answer — it has no way to reach your tracker. So you copy-paste the ticket list into the chat, and the deploy log, and yesterday's incident, every single time. The intelligence is there; the reach isn't. An MCP server is how you give Claude arms long enough to touch your own systems.

Think of MCP (Model Context Protocol) as a universal wall socket. Before standard sockets, every appliance needed its own custom wiring into the mains; after, anything with the right plug just works. MCP is that standard plug for tools: you wrap your ticket tracker or deploy log behind a small server that speaks the protocol, and any MCP-aware host — Claude Code here — can plug in without bespoke integration. FastMCP is the convenience layer that turns an ordinary, typed Python function into one of those pluggable tools with a single @mcp.tool() decorator.

The subtle, load-bearing point — the one that separates a working server from a useless one — is that the docstring is the interface, not documentation. Claude doesn't run your tools by reading their code; it reads each tool's docstring and type hints to decide which one to call. A vague description ("gets stuff") means the model routes to the wrong tool or none at all; a precise one ("List open tickets for a component; use when triaging or planning") routes reliably. So write docstrings as if they were the tool's public spec — because to the model, they are. And keep the tool surface small: every tool you expose is one more thing the model must choose correctly between, so expose only what the workbench actually needs.

server.pyfrom mcp.server.fastmcp import FastMCP
mcp = FastMCP("project-tools")

def query_tracker(**kw): ...       # your ticket-system integration
def read_deploy_log(service): ...  # your deploy-log integration

@mcp.tool()
def open_tickets(component: str) -> list[dict]:
    """List open tickets for a component. Use when triaging or planning."""
    return query_tracker(status="open", component=component)

@mcp.tool()
def last_deploy(service: str) -> dict:
    """Return the last deploy's status and commit for a service."""
    return read_deploy_log(service)

if __name__ == "__main__":
    mcp.run(transport="stdio")

4 · Advanced — Skill + subagent advanced

You've probably repeated yourself into exhaustion. Every session you retype the same reminders — "use type hints, lead docs with the why, never except: pass" — and every session Claude forgets them the moment the window closes. Worse, when you hand a big review to your one general assistant, it can wander: it starts editing the file it was only meant to critique. Skills and subagents are the two fixes for those two pains — and it's worth being clear which solves which, because beginners conflate them.

A Skill is packaged know-how; a subagent is a scoped worker. The analogy that keeps them straight: a Skill is the laminated procedure card you pin above a workstation ("here's how we do it here"), while a subagent is a specialist you hire with a deliberately limited badge. The procedure card is pure instruction — text Claude loads when its description says the situation applies. The specialist is a separate persona with its own tool permissions — a code reviewer you give read-only access, so it physically cannot edit or run anything even if it wanted to.

Why draw the line so sharply? Because the Skill answers "how should this be done?" and the subagent answers "who does it, and what may they touch?" — and conflating them is the classic mistake. People stuff behaviour rules into a subagent that every session needs (should have been a Skill, always available) or, worse, give a reviewer subagent broad edit rights "just in case" (defeating the entire point of a scoped worker). A reviewer that can write files is a liability the day a prompt injection or a confused turn tells it to; narrowing it to read-only shrinks the blast radius to nothing. Least privilege isn't paranoia here — it's the feature.

house-style.md---
name: house-style
description: >
  Apply our team's code and doc conventions. Use whenever writing or editing
  code, docs, or PR descriptions in this repo.
---
# House style
- Functions: type hints + a one-line docstring stating the contract.
- Errors: raise specific exceptions; never `except: pass`.
- Docs: lead with the "why", then the "how"; examples must be runnable.
- PRs: describe the change, the risk, and how it was verified.

5 · Professional — automate the review professional

A safeguard that depends on someone remembering to use it isn't a safeguard. You built a sharp code-reviewer subagent in §4 — but if running it is optional, it runs on the PRs you're not rushed on and skips the ones that matter most, the Friday-evening hotfix nobody double-checks. Any quality bar that lives only in a person's discipline erodes under deadline pressure. The move that makes it real is to take that same reviewer out of your hands and wire it into the pipeline, so it fires on every pull request whether anyone remembers or not.

The key realisation is that Claude Code has two doors, and this section walks through the second one. Interactively, you chat with it in your editor; headlessly, you invoke it as a plain command — claude -p "…" — that takes a prompt, does the work, and prints a result, no chat window involved. That headless door is what lets a machine, not a human, drive the agent. A GitHub Actions workflow is just a recipe that machine follows: on a pull request, check out the code, compute the diff, and pipe it through claude -p pointed at your reviewer subagent.

The leverage worth naming — and the reason this rung is "professional" — is write once, run in both doors: the exact subagent that helps you at your desk now guards every teammate's PR automatically, with zero extra code. That's the same encoded judgment reused, not a second implementation to maintain. The mistake to avoid is the tempting shortcut of pasting your API key straight into the YAML; that file is committed and shared, so the key leaks the moment the repo does. Read it from CI secrets instead (${{ secrets.… }}) — the automation stays safe to commit precisely because the credential never appears in it.

claude-review.ymlname: Claude review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - env: { ANTHROPIC_API_KEY: "${{ secrets.ANTHROPIC_API_KEY }}" }
        run: |
          git diff origin/main...HEAD > /tmp/diff.txt
          claude -p "Use the code-reviewer subagent on /tmp/diff.txt. \
            Output findings grouped by severity." > review.md
          cat review.md

6 · Professional — the 4 Ds, made concrete professional

Frameworks feel hollow until you can point at where they live in the code. "AI Fluency" and its four Ds — Delegation, Description, Discernment, Diligence — are easy to nod along to and just as easy to forget, because at the slide level they're abstractions. The failure mode is building a workbench that feels complete but has a silent gap: great steering and no verification, or tight tools and no way to keep dangerous actions human. The four Ds are the checklist that catches those gaps.

The reason this section exists is to close the loop between principle and artifact: every piece you've built maps to exactly one D, and seeing the map is what turns four vocabulary words into a design review you can actually run. Delegation is deciding what Claude does alone versus what stops for you — that's your permissions and deny-list. Description is carrying intent so the model knows what "good" means here — CLAUDE.md and the Skill. Discernment is verifying the work rather than trusting it — the Stop hook and CI review. Diligence is staying responsible over time — no-auto-push, secrets kept out of files, checks that gate the build.

Hold onto the payoff: if you can name which D a component serves, you can spot the one that's missing. A workbench strong on Description but weak on Discernment writes beautiful code nobody checks; strong on Delegation but weak on Diligence is safe today and leaky the day someone widens an allow rule. The common mistake is to treat the four as a feel-good summary at the end; instead use them as a gap-finder — walk each D, point at the file that satisfies it, and if you can't point at one, that's your next commit.

The workbench is where AI Fluency becomes concrete: Delegation — the deny-list keeps risky actions human; Description — CLAUDE.md + the Skill carry intent; Discernment — the Stop hook + CI review verify; Diligence — permissions + no-auto-push keep it responsible.

workbench_check.pydef workbench_ready(repo):
    required = {
        "claude_md": "CLAUDE.md (K1)",
        "settings_permissions": "permissions (K1)",
        "stop_hook": "test-on-stop hook (K2)",
        "skill": "a house Skill (K4)",
        "subagent": "a subagent (K5)",
        "mcp_server": "an MCP server (K6)",
        "ci_review": "CI review (K2)",
    }
    missing = [desc for key, desc in required.items() if not repo.get(key)]
    return (not missing), missing

full = dict(claude_md=1, settings_permissions=1, stop_hook=1, skill=1,
            subagent=1, mcp_server=1, ci_review=1)
print("ready:", workbench_ready(full))
partial = dict(claude_md=1, settings_permissions=1, skill=1)
print("partial:", workbench_ready(partial))

ready: (True, [])
partial: (False, ['test-on-stop hook (K2)', 'a subagent (K5)', 'an MCP server (K6)', 'CI review (K2)'])

7 · Tech-lead — ship the workbench to the team tech-lead

Picture the team you're actually on: ten engineers, ten laptops, ten slightly different Claudes. One person has a great deny-list, another has none; one wrote a lovely reviewer subagent nobody else knows exists. Everyone re-solves the same setup, badly and inconsistently, and the org's collective judgment about "how we work with Claude here" lives nowhere. That inconsistency is the problem this final rung solves — and it's a leadership problem, not a coding one.

The shift in thinking is from personal tool to institutional asset. A great individual setup helps one person; a committed setup helps everyone who ever clones the repo, including the teammate who joins next year. This is the same leap that made linters and CI worth adopting: value that scales with the team because it's enforced by the system, not by each person's memory. When the whole .claude/ tree and the MCP server are in version control, a single git pull hands a newcomer your steering, your limits, your Skills, your tools, and your safety rails — day-one parity, no onboarding call.

The precise payoff is what the course calls institutional leverage: your judgment, encoded once, enforced automatically for every engineer's Claude. The mistake that quietly kills this is treating the config as personal and leaving it out of the commit — then the leverage evaporates and you're back to ten laptops. The tech-lead move is the opposite instinct: whenever you improve how your own Claude behaves, ask "should the whole team have this?" and if yes, commit it. That one habit is how a good engineer's taste becomes the team's baseline.

Commit the whole .claude/ tree + the MCP server. Every teammate who clones the repo inherits your steering, Skills, subagents, and safety — the entire section, working for the whole team from one git pull.

ALLOW = ["Bash(pytest:*)", "Bash(ruff:*)", "Read(*)", "Edit(src/**)"]
DENY  = ["Bash(git push:*)", "Edit(vendor/**)"]

def matches(rule, action):
    tool, pat = rule[:-1].split("(", 1)      # e.g. Bash(pytest:*)
    return action["tool"] == tool and action["arg"].startswith(pat.rstrip("*"))

def decide(action):
    if any(matches(r, action) for r in DENY):   # deny checked first, wins
        return "DENY"
    if any(matches(r, action) for r in ALLOW):
        return "ALLOW"
    return "ASK"                                  # default: prompt the human

print(decide({"tool": "Bash", "arg": "pytest -q"}))       # ALLOW
print(decide({"tool": "Bash", "arg": "git push origin"})) # DENY
print(decide({"tool": "Bash", "arg": "rm -rf /"}))        # ASK

{
  "permissions": {
    "allow": ["Bash(pytest:*)", "Read(*)", "Edit(src/**)"],
    "deny":  ["Bash(git push:*)"]
  },
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "pytest -q || echo TESTS-FAILED" }
        ]
      }
    ]
  }
}

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("project-tools")

def query_tracker(**kw): ...          # your real integrations
def read_deploy_log(service): ...

@mcp.tool()
def open_tickets(component: str) -> list[dict]:
    """List open tickets for a component. Use when triaging or planning work."""
    return query_tracker(status="open", component=component)

@mcp.tool()
def last_deploy(service: str) -> dict:
    """Return the last deploy's status and commit for a service."""
    return read_deploy_log(service)

if __name__ == "__main__":
    mcp.run(transport="stdio")          # host launches this as a subprocess

# Code Reviewer

A focused subagent for reviewing diffs. Least-privilege: read-only on files.

Behavior:
- Analyze the diff strictly for correctness.
- Group findings by severity: critical (must fix), warning (should fix),
  note (nice-to-have).
- Output markdown with line-by-line references.

Tools: Read only. No Edit, no Bash. It reviews; it does not change code.

name: Claude review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - env:
          ANTHROPIC_API_KEY: "${{ secrets.ANTHROPIC_API_KEY }}"   # never inline
        run: |
          git diff origin/main...HEAD > /tmp/diff.txt
          claude -p "Use the code-reviewer subagent on /tmp/diff.txt. \
            Output findings grouped by severity." > review.md
          cat review.md

PIECES = {                       # piece -> which of the 4 Ds it serves
    "claude_md":            "Description  (intent travels with the repo)",
    "settings_permissions": "Delegation   (allow safe, deny risky)",
    "stop_hook":            "Discernment  (tests verify every change)",
    "skill":                "Description  (house conventions encoded)",
    "subagent":             "Delegation   (least-privilege specialist)",
    "mcp_server":           "Delegation   (domain tools, write-once)",
    "ci_review":            "Diligence    (automated, on every PR)",
}
def workbench_ready(repo):
    missing = [f"{k}: {d}" for k, d in PIECES.items() if not repo.get(k)]
    return (not missing), missing

full = {k: 1 for k in PIECES}
print("ready:", workbench_ready(full)[0])          # True
partial = dict(full); partial["ci_review"] = 0
print("missing:", workbench_ready(partial)[1])     # Diligence gap

Knowledge check check yourself