DEV Community: Kitforge

Subagent Patterns: How to Split Work Across AI Coding Agents Without Losing Coherence

Kitforge — Tue, 08 Sep 2026 22:10:13 +0000

This is a chapter from The Agentic Coding Kit - 34 ready-to-use files that package a senior engineer's AI coding setup: CLAUDE.md templates, permission guardrails, git hooks, and subagent playbooks. $19, instant download.

Claude Code and other agentic coding tools can spawn subagents: separate agent instances that get a slice of the work, their own context window, and a narrow job description. Used well, subagents are how you get parallel speed without the main agent losing the plot. Used badly, they are how you get five half-finished refactors that don't compile together.

After running subagent-heavy workflows on real codebases for months, here are the patterns that hold up.

Pattern 1: Scout agents for read-only exploration

The cheapest, safest subagent is one that can only read. Send it to answer a question like "where is authentication enforced in this repo?" or "what breaks if I change this interface?"

Why it works: the scout burns its own context on the boring traversal - opening 30 files, tracing imports - and returns a 10-line answer. Your main agent's context stays clean for the actual work.

Rules that keep scouts useful:

Give it a question, not a task. "Map the billing flow" not "refactor billing."
Cap the output. "Return the file paths, the key functions, and a 5-sentence summary."
Forbid writes entirely. A scout that edits is no longer a scout.

Pattern 2: Worker agents with a definition of done

A worker subagent gets a concrete, verifiable task: "add input validation to these three endpoints, with tests that fail before and pass after." The key is that the task must be checkable without judgment.

If you can't write the done-condition in one sentence, the task isn't ready to delegate. Split it further or do it yourself.

The playbook version I use:

Scope: exact files or directories it may touch.
Done condition: the command that must pass (e.g. npm test -- billing).
Budget: stop and report after N minutes or M failed attempts, instead of spiraling.

That third one is the one everyone skips. An unbounded worker will confidently produce 800 lines of wrong. A bounded one reports "stuck, here's what I tried" and costs you two minutes.

Pattern 3: The reviewer is not the author

Never let the agent that wrote code be the agent that reviews it. Same context, same blind spots. A fresh reviewer subagent, given only the diff and the requirements, catches things the author agent sailed past - because it has no sunk cost in the approach.

This mirrors human teams for a reason. The kit's review checklist templates exist to give the reviewer agent the same bar every time: error handling, injection surface, migration safety, test quality.

What to never delegate

Some work should stay with the main agent (or with you):

Deciding what to build. Subagents execute judgment; they shouldn't create it.
Cross-cutting design. Anything that changes contracts between modules needs one coherent mind.
Final review before merge. Delegated review is a filter, not a gate. The last pass belongs to whoever owns the outcome.
Secrets and destructive ops. Permission guardrails should make this impossible, not just discouraged.

The coordination tax

Every subagent adds overhead: you write a brief, wait, and integrate the result. If the task takes less time than the brief, do it inline. My rule of thumb: delegate when the subtask needs more than ~10 minutes of focused work or a separate context window's worth of reading.

The win isn't parallelism for its own sake. It's keeping the main agent's attention on the decisions while the grunt work happens in quarantined contexts.

The full subagent playbooks - scout, worker, reviewer templates with done-conditions, budgets, and integration checklists - are in The Agentic Coding Kit, along with the CLAUDE.md template and permission guardrails that make delegation safe. One-time $19, lifetime updates.

Anatomy of a CLAUDE.md That Actually Controls Your AI Agent

Kitforge — Tue, 08 Sep 2026 19:12:42 +0000

Every Claude Code setup lives or dies by one file. Not the model, not the prompts you type at 2 AM - the CLAUDE.md sitting at the root of the repo. It is the first thing the agent reads and the only thing it reads every single time.

I have reviewed a lot of these files, and the bad ones fail in predictable ways. They are either novels nobody would read, wish lists with no enforcement, or walls of style rules the model ignores because nothing says what matters most. Here is the structure that actually works, section by section.

1. Identity and mission (2-3 sentences, no more)

Open with what the project is and what the agent's job is. Not marketing copy - operational context.

This is a B2B invoicing API in TypeScript (Fastify + Postgres). You are the
primary maintainer. Prioritize correctness of money math over speed. When in
doubt, ask before changing anything under /billing.

That last line does real work. It tells the agent where the blast radius is.

2. Commands that must work

The agent will run things. Tell it exactly which commands are the source of truth so it does not invent npm run test:quick and hallucinate success.

- Install: `pnpm install`
- Test: `pnpm test` (must pass before every commit)
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint --fix`

Agents are surprisingly obedient here. If you give them the exact command, they run the exact command. If you do not, they guess, and guesses fail silently.

3. Hard rules, stated as rules

This is where most files go soft. "Try to avoid committing to main" is a suggestion. Write rules like a linter would:

- NEVER commit directly to main. Always create a feature branch.
- NEVER use `git push --force` on shared branches.
- NEVER commit files matching .env* or containing API keys.
- ALWAYS run `pnpm test` before committing. No exceptions.

The ALL-CAPS markers are not for style. Models weight emphatic, absolute language more heavily, and these are the rules you most want to survive a long context window.

4. Architecture map (the 60-second version)

Agents waste enormous effort exploring. Give them the map:

/src/routes - HTTP handlers, thin by design
/src/domain - business logic, no I/O allowed here
/src/db - migrations and queries
/tests - mirrors /src structure

Five lines saves dozens of exploratory tool calls per session.

5. How to verify work

This is the section almost everyone skips, and it is the one that changes behavior the most. Define what "done" means:

A task is done when: tests pass, typecheck is clean, the commit message
follows conventional commits, and you have re-read your own diff for
obvious mistakes.

Without this, agents declare victory after the code compiles. With it, they self-review.

6. What the agent is NOT allowed to do

Boundaries prevent the most expensive mistakes:

Do not: modify CI configuration, change database migrations that have
already been applied, add dependencies without asking, or touch anything
under /infra.

What to leave out

Three things do not belong in CLAUDE.md: your entire style guide (link it), exhaustive API docs (the agent can read code), and anything you would not enforce in review (every unenforced rule teaches the model that rules are optional).

The test of a good one

Read your CLAUDE.md and ask: if a talented contractor read only this file, could they work in this repo without asking me a single question for the first hour? If not, that gap is exactly what your agent is silently guessing about.

If you want this structure without writing it from scratch, I packaged a production-tested version into the Agentic Coding Kit - a CLAUDE.md template with these six sections, plus the git hooks that enforce the hard rules even when the model forgets them, review subagents, and slash commands. But the anatomy above is the real takeaway: identity, commands, hard rules, map, definition of done, boundaries. Everything else is decoration.

5 Git Hooks That Stop AI Coding Agents From Breaking Your Repo

Kitforge — Tue, 08 Sep 2026 14:28:17 +0000

AI coding agents are fast. That is the whole point, and also the whole problem. Claude Code or Cursor can produce ten commits in the time you would normally spend on one, and none of those commits come with the hesitation a human feels before pushing to main.

Rules in a CLAUDE.md file help, but they rely on the model remembering and obeying them. Git hooks are different: they run outside the model, on your machine, and they cannot be talked out of it. Here are the five hooks I install in every repo where an agent has commit access, with working implementations.

All of these live in a .githooks/ directory in the repo, activated once with:

git config core.hooksPath .githooks

That keeps the hooks versioned and shared with the team instead of hidden in .git/hooks.

1. Block direct commits to main

Agents love committing to whatever branch is checked out. If that branch is main, you are one git commit away from an unreviewed change landing in production history.

.githooks/pre-commit:

#!/bin/sh
branch=$(git symbolic-ref --short HEAD 2>/dev/null)
if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
  echo "Direct commits to $branch are not allowed. Create a feature branch."
  exit 1
fi

The agent hits this once, reads the message, and creates a branch. That is exactly the behavior you want: the correction happens inside the agent's own loop, not in your review comments three hours later.

2. Block force pushes to shared branches

An agent that gets confused about history will sometimes reach for --force. On a shared branch that is unrecoverable damage to everyone else's work.

.githooks/pre-push:

#!/bin/sh
protected="main master develop"
while read local_ref local_sha remote_ref remote_sha; do
  remote_branch=$(echo "$remote_ref" | sed 's|refs/heads/||')
  for p in $protected; do
    if [ "$remote_branch" = "$p" ]; then
      if [ "$remote_sha" != "0000000000000000000000000000000000000000" ]; then
        if ! git merge-base --is-ancestor "$remote_sha" "$local_sha"; then
          echo "Non-fast-forward push to $remote_branch blocked."
          exit 1
        fi
      fi
    fi
  done
done

This blocks any non-fast-forward update to a protected branch, which covers force pushes and history rewrites in one check.

3. Require tests to pass before a commit

The most common agent failure mode is "code looks right, tests never ran." A pre-commit hook that runs the fast test suite makes that impossible to skip silently.

.githooks/pre-commit (append to hook 1):

if [ -f package.json ]; then
  npm test --silent || { echo "Tests failing. Commit blocked."; exit 1; }
elif [ -f pytest.ini ] || [ -f pyproject.toml ]; then
  pytest -x -q || { echo "Tests failing. Commit blocked."; exit 1; }
fi

If your full suite is slow, point this at a smoke subset. The point is not coverage, it is that "commit" and "ran tests" can no longer drift apart.

4. Enforce commit message format

Agents write commit messages like "update files" when they are moving fast. If your repo uses conventional commits (and your changelog tooling depends on them), enforce it at the door.

.githooks/commit-msg:

#!/bin/sh
pattern="^(feat|fix|docs|refactor|test|chore)(\(.+\))?: .{10,}"
if ! grep -qE "$pattern" "$1"; then
  echo "Commit message must be conventional: type(scope): description"
  exit 1
fi

Agents adapt to this instantly because the error message tells them the exact format to retry with.

5. Block secrets at the door

Agents paste example keys, tokens from logs, and credentials from your .env.example into code more often than anyone admits. A cheap pattern check catches the obvious ones.

.githooks/pre-commit (append):

if git diff --cached | grep -qE '(sk-[a-zA-Z0-9]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN (RSA|EC) PRIVATE KEY-----)'; then
  echo "Possible secret in staged changes. Commit blocked."
  exit 1
fi

This is not a replacement for a real scanner like gitleaks, but it catches the three patterns that cause the most pain, in zero dependencies.

The pattern that matters

Notice what these have in common: none of them trust the model. Every rule that lives only in a prompt is a suggestion. Every rule that lives in a hook is physics.

If you do not want to write and tune these yourself, I packaged this exact setup - the hooks, the CLAUDE.md presets, the subagents, and the slash commands - into the Agentic Coding Kit. It unzips into any repo and gives Claude Code or Cursor this discipline from the first prompt. But whether you use my kit or copy the snippets above, put the guardrails in git, not in the prompt.

I Audited 50 Claude Code Setups. Here's What the Good Ones Have in Common

Kitforge — Tue, 08 Sep 2026 04:51:29 +0000

Most Claude Code and Cursor setups I see fail the same way: the model writes plausible code, breaks conventions, invents APIs, and the human spends the session correcting it. The fix is never a better prompt typed into the chat box. It is the files the agent reads before it writes a single line.

After comparing dozens of working setups from senior engineers, the pattern is boring and consistent. The good setups all have five things.

1. A CLAUDE.md (or AGENTS.md) that reads like onboarding docs

Not "You are a helpful assistant." A real one: the stack, the commands that actually run the tests, the naming conventions, the directories the agent should never touch, and the definition of done. Weak setups skip this and pay for it in every session.

2. Explicit workflow contracts

Strong setups tell the agent how to work, not just what the project is. Plan before code. Show the diff strategy before large refactors. Run the test suite before declaring victory. These are checklists, and they belong in files the agent loads every time, not in your head.

3. Review checklists tuned to the repo

Generic "review this code" prompts catch generic problems. The setups that catch real bugs point the agent at the project's actual failure modes: the ORM gotchas, the auth boundary, the places where migrations go wrong.

4. Guardrails against confident nonsense

The best configs include rules like "if you are about to invent a function, search the codebase first" and "if the test command fails, stop and report instead of patching around it." Agents hallucinate least when the rules name the failure.

5. Task templates for repeat work

Writing a migration, adding an endpoint, cutting a release: the good setups have a template for each, so the agent produces the same shape every time instead of improvising.

The shortcut

I got tired of reassembling this from scratch for every repo, so I packaged my own setup into The Agentic Coding Kit: 34 files covering CLAUDE.md and AGENTS.md templates, system prompts, agent rules, code review checklists, and workflows for Claude Code, Cursor, and similar tools. Drop it into a repo and the agent starts behaving like it read the onboarding docs, because it did.

Whether you buy a pack or write your own, the lesson from the audit stands: the setup files are the product. The chat prompt is just the ignition.

The Agentic Coding Kit: a senior engineer's AI coding setup, packaged

Kitforge — Tue, 08 Sep 2026 02:53:33 +0000

AI coding assistants are only as good as the instructions you give them. Most repos give them nothing, so they guess: wrong test commands, no commit discipline, no idea what "done" means for your project.

I packaged the setup a senior engineer would write for your repo into a single drop-in kit: The Agentic Coding Kit.

What's inside (34 files)

CLAUDE.md presets for 5 stacks - Python/FastAPI, TypeScript/Node, React/Next.js, Go, Rust. Scoped permissions, build/test commands, and conventions the agent follows from the first prompt.
6 Cursor rules (.mdc) - testing, git discipline, security review, refactor guardrails, docs, style.
5 Claude Code subagents - code reviewer, test writer, security auditor, refactorer, doc writer.
4 slash commands - /review, /test, /secure, /ship.
3 hook recipes with ready-to-use scripts - block force pushes, require tests before commit, auto-lint on save.
CI workflow templates, pre-commit config, ADR templates, MIT license.

Why it works

Agents drift when the rules live in your head. A CLAUDE.md that says "run pytest before committing, never force-push, keep diffs under 400 lines" turns a chaotic assistant into a predictable one. The kit gives you that file, tuned per stack, plus the hooks that enforce it mechanically.

Unzip into your repo, pick the preset for your stack, done. Every file is plain Markdown, JSON, or shell - no lock-in, read everything before it runs.

Get The Agentic Coding Kit - $19, one-time

Free updates for all v1.x releases. If it saves you one afternoon of wrangling a runaway agent, it paid for itself.