DEV Community: Kitforge

The context window is your real budget

Kitforge — Wed, 09 Sep 2026 09:23:57 +0000

Everyone talks about model quality. Almost nobody talks about the resource that actually decides whether your AI coding session succeeds: the context window. It is a budget, and you are spending it every turn.

What you are actually spending

A session with an agent loads your instructions, the files it read, its own earlier attempts, tool outputs, and your corrections. All of it sits in the same window. At the start of a session the model is sharp and follows your conventions. Ninety minutes later it is "forgetting" rules you stated up front. It didn't forget. Your rules got diluted by 40,000 tokens of stack traces and half-finished diffs.

The three leaks

1. Reading whole files when a function would do. Every cat entire-module.py costs you thousands of tokens that stay in the window for the rest of the session. Teach the agent to grep first, then read the narrowest range that answers the question.

2. Letting failed attempts accumulate. Three wrong turns leave three full diffs and their error output in context. The model starts pattern-matching on its own mistakes. When an approach fails twice, start a fresh session with a one-paragraph summary of what you learned, not the whole transcript.

3. Stuffing the context file. A 300-line CLAUDE.md is a tax on every single turn. Keep it under 80 lines and push detail into files the agent loads only when a task needs them.

What works instead

Treat context like memory in an embedded system. Small, deliberate allocations. Subagents for research, so their exploration never pollutes your main session. Explicit handoffs: when a session gets long, write the state to a file and restart clean. Hooks that re-inject the two or three rules that matter right before the model writes code, instead of hoping they survived from message one.

The teams getting reliable output from coding agents are not using smarter models. They are spending the window on purpose.

Where this is going

Context discipline is a workflow, not a setting. I packaged mine - context presets that stay small, subagent definitions that isolate exploration, hooks that re-assert rules at the moment of code generation - into The Agentic Coding Kit. 34 files, drop them into a repo. But the mindset is free: every token in the window is a token the model is not spending on your actual problem.

Your CLAUDE.md is too long (and other context-file mistakes

Kitforge — Wed, 09 Sep 2026 08:38:56 +0000

Most CLAUDE.md files I see fail the same way: they try to be documentation. Three hundred lines of architecture overview, API conventions, folder structure, philosophy. The model reads none of it when it counts.

Your context file is not a wiki. It is a preload. Every token in it competes with your actual request for attention, and the model will happily trade away your testing conventions for a confident answer to whatever you just asked.

The mistakes that matter

1. Writing for a human new hire. Humans skim, bookmark, and come back later. Models get one pass, every session, whether they need it or not. If a line would help a new hire but doesn't change what the AI writes today, cut it.

2. Stating what instead of enforcing how. "We use pytest" is trivia. "Every new module ships with tests in tests/ and CI fails without them" is a rule the agent can act on. If a sentence can't change a decision, it's decoration.

3. No negative rules. The most valuable lines in my context file are the "never" list: never mock the database in integration tests, never add a dependency without asking, never silence a type error with any. Agents default to the path of least resistance. Negative rules are the rails.

4. Burying the load-bearing rule at line 180. Models weight the beginning and end of context. Your three non-negotiables belong in the first ten lines, not in a subsection between "Project history" and "Team rituals."

The shape that works

Mine is under 80 lines. Roughly: a one-paragraph project summary, the stack, five non-negotiable rules, the test command, the "never" list, and a pointer to deeper docs the agent can read when a task actually needs them. Everything else got deleted or moved to files the agent loads on demand.

The test is simple: after editing, ask the agent to do a task that used to go wrong. If it still goes wrong, the rule isn't in the file or isn't enforceable. Rewrite it until the failure disappears.

Where this is going

Context files are the first layer. The next layers are subagents with narrow jobs, hooks that block bad commits before they exist, and slash commands that encode whole workflows. A short, sharp context file is what makes those layers reliable instead of decorative.

I packaged my own setup - the context presets for five stacks, the subagents, the hooks, the commands - into The Agentic Coding Kit. 34 files, drop them into a repo, done. But the lesson works without it: shorter file, enforceable rules, non-negotiables first.

Your AI agent needs a runbook, not a vibe

Kitforge — Wed, 09 Sep 2026 07:20:00 +0000

Ask an AI coding agent to deploy your service and watch what happens. It will improvise: guess the deploy command, skip the health check, forget to warm the cache, and announce success before the rollback window even opens.

Now ask a senior engineer the same thing. They don't improvise. They follow the runbook — the boring, written-down, step-by-step procedure that exists precisely so nobody has to think during a risky operation.

Your agent needs that document too. Not a paragraph of encouragement in a rules file. An actual runbook.

Vibes don't survive contact with production

Rules files tell agents how to behave in general. Runbooks tell them exactly what to do in a specific, dangerous situation. The difference matters most when the stakes are highest:

Deploys. Order of operations, health checks, rollback triggers.
Migrations. Backup first, run in a transaction, verify row counts, have the reverse migration ready.
Incident response. What to check first, who to page, what never to touch.

When you skip the runbook, the agent pattern-matches from training data — which means it runs the deploy procedure from a 2021 Medium post about a stack you don't use.

Anatomy of a runbook an agent can execute

A good agent runbook is not the wiki page you wrote for humans. Humans tolerate ambiguity, infer context, and know which steps are skippable. Agents execute literally and confidently. Write accordingly:

1. Preconditions as checks, not prose.
Bad: "Make sure the migration is reversible."
Good: ls migrations/down/ | grep <migration_name> must return a file. If not, STOP and ask.

2. Explicit STOP conditions.
Agents default to forward progress. Every runbook needs a list of states where the correct action is to halt and report: "If the health check fails twice, do NOT retry a third time. Revert and report."

3. Verification after every mutating step.
Not "deploy the service" but "deploy, then curl /healthz expecting 200, then check the error rate for 2 minutes." An agent that verifies catches its own mistakes. An agent that doesn't, ships them.

4. Named commands, never described commands.
"Run the test suite" gets you pytest on a repo that uses make test. Write the exact command. If the exact command varies, write how to discover it (cat Makefile | grep -A2 test).

A minimal example

## Deploy: api-service

Preconditions (check ALL, stop if any fail):
- `git status` clean on main
- `make test` passes
- No active incident: `curl -s status.internal/health | grep OK`

Steps:
1. `make build && make deploy-staging`
2. Verify: `curl -s staging.api/healthz` returns 200
3. Run smoke suite: `make smoke-staging`
4. `make deploy-prod`
5. Watch error rate for 120s: `make watch-errors`

STOP and rollback (`make rollback`) if:
- Any health check returns non-200
- Error rate exceeds 0.5% at any point
- Any step hangs longer than 5 minutes

Six lines of structure, and the agent goes from improvising theater to executing a procedure.

Where runbooks live

Keep them in the repo, in a runbooks/ directory, referenced from your rules file by path: "Before any deploy, read runbooks/deploy-api.md and follow it exactly." The rules file points; the runbook executes.

This also fixes the context-window problem from my last post: the agent loads the runbook when it needs it, instead of carrying 400 lines of deploy lore in every session.

The kit I sell includes ready-to-adapt runbook templates for deploys, migrations, and incident response, alongside the CLAUDE.md templates and git hook suite: The Agentic Coding Kit - $19, one-time, free v1.x updates.

Rules files don't work unless they're testable

Kitforge — Tue, 08 Sep 2026 23:02:28 +0000

Every team I know that adopted AI coding agents did the same thing first: they wrote a rules file. CLAUDE.md, .cursorrules, AGENTS.md. Pages of conventions, style guides, and stern warnings.

Then, three weeks later, the agent force-pushed to main anyway.

Here's the uncomfortable truth: a rule that isn't testable is a suggestion. And agents treat suggestions the way a junior dev treats a comment that says "don't change this" — with curiosity.

Why rules files fail

Rules files fail the same way documentation fails: nothing checks them. When a rule says "never commit directly to main," there is no mechanism enforcing it. There's just a paragraph of English hoping a probabilistic model feels cooperative today.

The failure modes are predictable:

Context window eviction. Long sessions push your rules file out of the effective context. The agent isn't disobeying. It literally cannot see the rule anymore.
Instruction dilution. A 400-line rules file is 400 lines of equal-weight text. The model can't tell "we prefer semicolons" from "you will break production if you do X."
No feedback loop. When the agent violates a rule, nothing happens. The violation ships. You find out in review, or in an incident.

The fix: turn rules into checks

The teams getting real value from agents figured out one thing: every rule worth writing down is worth expressing as a test, a hook, or a CI gate.

The pattern looks like this:

Rule (English): "Never commit secrets."
Check (enforced): a pre-commit hook that scans staged diffs for high-entropy strings and known key patterns, and refuses the commit.

Rule: "All new endpoints need tests."
Check: a CI job that fails when git diff --name-only shows a new route file without a matching spec file.

Rule: "Don't force-push shared branches."
Check: a server-side pre-receive hook or branch protection rule. Full stop, no exceptions, no agent creativity.

The English version still belongs in your rules file — it explains why. But the check is what makes it true.

The testable-rule audit

Go through your rules file right now and mark every rule with one of three labels:

Enforced — a hook, test, linter, or CI gate fails when it's violated. Keep.
Testable but not enforced — you could write a check. Write it this week. These are your highest-risk gaps.
Judgment call — genuinely not testable ("prefer composition over inheritance"). Keep these, but move them to a short "taste" section and accept the agent will get them wrong sometimes.

When I run this audit on real setups, the split is usually 15% enforced, 55% testable-but-not, 30% judgment. That middle bucket is where agents hurt you.

A worked example

One of the highest-leverage conversions I've done:

# .git/hooks/pre-push
branch=$(git rev-parse --abbrev-ref HEAD)
if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
  echo "Direct pushes to $branch are disabled. Open a PR."
  exit 1
fi

Four lines. It replaced a paragraph of rules-file prose that three different agents had independently ignored. The paragraph explained policy. The hook is policy.

The deeper win

Something unexpected happens once your rules are checks: your rules file gets shorter and better. You delete the rules that are now enforced (the hook is the documentation) and what remains is the actual hard stuff — architecture intent, naming philosophy, when to break the rules.

Agents do noticeably better with a 60-line file of real judgment calls than a 400-line file of unenforced commands.

I packaged my full setup — the testable CLAUDE.md, the git hook suite, the subagent patterns, and the audit checklist — into The Agentic Coding Kit. It's $19, one-time, with free v1.x updates. If it saves you one afternoon of wrangling a runaway agent, it paid for itself.

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.