{"slug": "how-i-set-up-claude-code-with-26-production-subagents-claude-md-mcp-hooks", "title": "How I Set Up Claude Code with 26 Production Subagents (CLAUDE.md, MCP, Hooks)", "summary": "A developer detailed how they configured Claude Code with 26 production subagents, a CLAUDE.md contract, MCP servers, and hooks to transform the AI from a forgetful junior into a reliable senior team. The setup uses focused subagents with strict output formats and a short, specific CLAUDE.md file to enforce conventions and prevent destructive actions.", "body_md": "When I first opened Claude Code on a real project, it felt like hiring a brilliant junior who had read every book but never shipped anything. It could write code fast, but it would forget my conventions halfway through a session, run a migration without asking, and \"fix\" a bug by deleting the failing test.\n\nAfter a few weeks of tuning, it now behaves like a small senior team: it plans before it codes, reviews its own work, writes tests, and refuses to run anything destructive. The difference wasn't a better model. It was a better **setup** — a `CLAUDE.md`\n\n, a set of focused subagents, a couple of MCP servers, and two small hooks.\n\nHere is exactly how that setup works, so you can build your own.\n\n`CLAUDE.md`\n\nis the file Claude Code reads automatically at the start of every session. Most people treat it like a README. It works far better as a **contract**: short, specific, and written in always/never terms the agent can't misread.\n\nThe two rules that gave me the biggest jump in quality:\n\n```\n## Build & test (run these, do not guess)\n- Install:  pnpm install\n- Dev:      pnpm dev\n- Test:     pnpm test -- --run\n- Lint:     pnpm lint\n- Typecheck: pnpm typecheck\n\n## Always\n- Run `pnpm typecheck && pnpm test -- --run` before saying a task is done.\n- Use parameterized queries. Never build SQL with string concatenation.\n- When you change a public function, update its tests in the same edit.\n\n## Never\n- Never run `git push`, `git reset --hard`, or any DB migration without me confirming.\n- Never add a dependency to fix something a few lines of code can solve.\n- Never disable a failing test to make the suite pass.\n```\n\nThe reason the \"Build & test\" block matters: without the exact commands, the agent **guesses** them (`npm test`\n\n, `yarn test`\n\n, `make test`\n\n) and wastes turns failing. Give it the real commands once and it stops guessing.\n\nKeep this file under ~50 lines. A long `CLAUDE.md`\n\ngets diluted in the context and the agent starts ignoring the middle of it. Be ruthless.\n\nA single agent juggling \"review this, also write tests, also refactor\" produces mediocre output at every task. Subagents fix this by giving each job its own focused instructions and its own context window. In Claude Code these live in `.claude/agents/*.md`\n\nand you invoke them by name.\n\nA subagent is just a Markdown file with frontmatter and a system prompt. Here's a real one — my `code-reviewer`\n\n:\n\n```\n---\nname: code-reviewer\ndescription: \"Reviews a diff for bugs, security issues, and convention violations. Use after writing or changing code.\"\ntools: Read, Grep, Bash\n---\n\nYou are a senior code reviewer. Review ONLY the changed lines plus their immediate context.\n\nOutput exactly three sections:\n1. **Blocking** — bugs, security holes, data loss risks. Each with file:line and a fix.\n2. **Should fix** — correctness or clarity issues that aren't blocking.\n3. **Nits** — style/naming. Keep this short.\n\nRules:\n- If there are no blocking issues, say so on line one. Do not invent problems to look thorough.\n- Check: injection, missing error handling, N+1 queries, unhandled null, race conditions.\n- Quote the exact line you're flagging. No vague \"consider improving error handling\".\n```\n\nThe two lines that make it useful are *\"Do not invent problems to look thorough\"* and *\"Quote the exact line.\"* Without them, reviewers either rubber-stamp everything or generate a wall of generic advice. With them, you get actionable output.\n\nI run a roster of focused specialists this way — a `debugger`\n\nthat reproduces before it theorizes, a `test-writer`\n\nthat targets edge cases instead of happy paths, a `security-auditor`\n\nthat thinks in OWASP categories, an `api-designer`\n\n, a `refactor-architect`\n\n, and so on. Each one is a small file with a tight output format. The pattern is always the same: **one job, one output format, one anti-fluff constraint.**\n\nMCP (Model Context Protocol) servers are how Claude Code reaches outside the chat — the filesystem, a browser, a persistent memory store. You configure them in `.mcp.json`\n\n:\n\n```\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"./\"]\n    },\n    \"sequential-thinking\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-sequential-thinking\"]\n    }\n  }\n}\n```\n\nThe one I'd add first is **sequential-thinking**. It gives the agent a scratchpad to break a problem into steps before acting, which noticeably reduces the \"confidently wrong\" answers on multi-step tasks. A browser MCP (Playwright) is the second I reach for, because it lets the agent actually load the page and read the console instead of guessing why the UI broke.\n\nOne caution: MCP servers move fast and some get abandoned. Pin to maintained ones and check they still install before you rely on them.\n\nHooks are shell commands Claude Code runs on events you choose. Two are worth setting up on day one.\n\n**Auto-format on save** — so you never review a diff full of whitespace noise:\n\n```\n{\n  \"hooks\": {\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Edit|Write\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"pnpm prettier --write \\\"$CLAUDE_FILE_PATHS\\\"\" }]\n      }\n    ]\n  }\n}\n```\n\n**Block dangerous commands** — a pre-execution guard that refuses destructive shell calls even if the agent tries them:\n\n``` bash\n#!/usr/bin/env bash\n# .claude/hooks/guard.sh — exit non-zero to block the command\nif echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf /|git reset --hard|DROP TABLE'; then\n  echo \"Blocked: destructive command refused by guard hook.\" >&2\n  exit 1\nfi\n```\n\nThis is the difference between trusting an autonomous agent and babysitting it. The model can be wrong; the hook is deterministic.\n\nWith the setup above, my actual workflow on a new feature is short:\n\n`code-reviewer`\n\non the diff, then `test-writer`\n\nfor the gaps it found.`pnpm typecheck && pnpm test`\n\nruns because `CLAUDE.md`\n\nsays it must.The agent does the typing. I do the deciding. That's the whole point.\n\nBuilding all of this from scratch is a real time sink — the 26 subagents alone took me weeks of tuning to get the output formats right. If you'd rather skip that and drop a finished setup into any repo, I packaged my exact configuration as ** Claude Code Agent OS**: 26 specialized subagents, 12 slash commands (\n\n`/plan`\n\n, `/review`\n\n, `/test`\n\n, `/ship`\n\n...), 5 ready-to-edit `CLAUDE.md`\n\ntemplates, the MCP configs, and the safety + format hooks (bash and PowerShell) — with a START HERE quickstart that gets you running in about 5 minutes.But you don't need it to get value from this post. Start with a tight `CLAUDE.md`\n\nand one `code-reviewer`\n\nsubagent today; that pair alone will change how your next commit feels.\n\nIf you build your own subagent roster, I'd genuinely like to see which specialists you find most useful — drop them in the comments.", "url": "https://wpnews.pro/news/how-i-set-up-claude-code-with-26-production-subagents-claude-md-mcp-hooks", "canonical_source": "https://dev.to/nongdyz_d9c3069b1acb2a08c/how-i-set-up-claude-code-with-26-production-subagents-claudemd-mcp-hooks-3jij", "published_at": "2026-06-27 13:54:39+00:00", "updated_at": "2026-06-27 14:33:31.964169+00:00", "lang": "en", "topics": ["large-language-models", "ai-agents", "developer-tools", "ai-tools", "ai-products"], "entities": ["Claude Code", "CLAUDE.md", "MCP", "OWASP"], "alternates": {"html": "https://wpnews.pro/news/how-i-set-up-claude-code-with-26-production-subagents-claude-md-mcp-hooks", "markdown": "https://wpnews.pro/news/how-i-set-up-claude-code-with-26-production-subagents-claude-md-mcp-hooks.md", "text": "https://wpnews.pro/news/how-i-set-up-claude-code-with-26-production-subagents-claude-md-mcp-hooks.txt", "jsonld": "https://wpnews.pro/news/how-i-set-up-claude-code-with-26-production-subagents-claude-md-mcp-hooks.jsonld"}}