Claude Code for development teams: hooks, sub-agents and MCP in production

Claude Code stopped being an IDE assistant in 2025 and became an operating agent of the SDLC. The difference is practical: an assistant waits for you to ask it to autocomplete; an agent opens files, runs commands, reads logs, executes tests, writes commits and opens PRs. If your team uses it as autocomplete, it's leaving 70% of the value on the table.

This guide distills what we learned at WITS applying it to production projects during 2025–2026: how to configure it, how to master it and how to measure it. No marketing — everything comes from real codebases that went through human code review.

Assistant vs agent: the distinction that matters

Both coexist. But the teams that move the needle treat Claude Code as a junior-senior collaborator: you delegate complete tasks to it, not lines of code.

Baseline configuration every team needs

settings.json and allowlists

The first mistake is operating without an explicit allowlist. Result: Claude asks for permission 30 times per session and the friction kills adoption. The solution is a shared .claude/settings.json in the repo with safe commands pre-approved.

CLAUDE.md: the project's memory

A file at the repo root where you document conventions, stack, critical commands and rules the agent must follow. Example of useful sections: stack (Python 3.12, FastAPI, Postgres 16), commands (`pytest -x`, `make migrate`), rules ("every new endpoint requires an integration test"), commit language, restrictions ("never touch the schema without a migration").

Slash commands: turning workflows into one word

Slash commands are reusable scripts that distill a workflow into a single command. Some we use at WITS:

• /review-pr — runs the current diff against the project rubric and reports findings by severity
• /refactor-tests — takes a test file, identifies duplication and proposes consolidation
• /migrate-schema — generates an Alembic migration + tests + updates types
• /security-scan — looks for insecure patterns (SQL strings, secrets in code, open CORS) in the current change
• /changelog — generates a CHANGELOG entry based on commits since the last tag

Each slash command lives in .claude/commands/ as a Markdown file with instructions. Versioned in git, it evolves with the team.

Sub-agents: parallelize without polluting context

A sub-agent is a secondary instance with a narrow prompt and specific tools. Useful when a subtask (e.g. searching a 200-file library) would create noise in the main agent. Patterns that work:

• Explorer — read-only. Finds where a feature lives without touching anything.
• Reviewer — runs an independent evaluation of the change without the author's bias.
• Test runner — runs long test suites and reports a summary to the main agent.
• Doc generator — generates/updates a module's docs without reopening the feature's context.

MCP servers: extend the agent to your infrastructure

Model Context Protocol (MCP) is Anthropic's standard for agents to talk to external systems. In product teams, the useful MCPs are:

Golden rule: read MCPs are low risk (use them generously); write MCPs require an explicit allowlist and human review before merging.

Hooks: automate what happens before and after

Hooks are shell commands that run on agent events. The three most useful:

• PostToolUse — after editing a file, runs the linter/formatter and leaves the repo clean
• PreToolUse — before a dangerous command (rm, git push), validates it with your own script
• SessionStart — when a session starts, prints the project's current state (branch, open PRs, pending tests)

Productive day-to-day patterns

Issue → PR end to end

You paste the Linear/Jira issue into the agent. You tell it: "plan it first, then implement". Plan mode produces the plan; you review and approve it. The agent executes, writes tests and opens a PR with a description, a link to the issue and manual testing notes. Typical time: a 200-400 LOC feature in 30-60 minutes vs 3-5 hours by hand.

Test-driven refactoring

For non-trivial refactors: ask the agent to first write the tests that protect current behavior, run them, and then refactor. The agent spots regressions immediately. A well-known but underused pattern.

Debugging with real logs

You connect the Sentry MCP (or paste the stack trace), ask for a local reproduction, and the agent finds the root cause and proposes a fix with a test that reproduces the bug. Much faster than the manual "copy log → search → edit → reproduce" cycle.

Common mistakes we see

1. 1No CLAUDE.md — the agent reinvents conventions every session
2. 2No allowlist — friction kills adoption in the first week
3. 3Skipping plan mode on complex changes — code generated without prior design, high cost later
4. 4Not using sub-agents for exploration — polluted main context, low quality
5. 5Accepting PRs without human code review — the agent can produce correct-but-wrong code
6. 6Keeping slash commands in people's heads, not in .claude/commands/ — the team doesn't scale its learning

How to measure ROI without fooling yourself

Vanity metrics (LOC generated, suggestions accepted) don't count. The real metrics:

The numbers vary by context, but the pattern is consistent: a 30-50% improvement in operating metrics, with no loss of quality if there's human code review.

Does it replace engineers?

No. It changes the profile. Pure junior engineers lose relative advantage; seniors gain massive leverage. The ideal 2026 team: a senior with Claude Code performs like a team of 3 mid-level engineers from 2 years ago — but architectural quality depends on the senior, not the agent.