Posts tagged Coding Agents — AI × software engineering, made practical.
You will learn the four levels of the C4 model and how to write them as a plain-text ARCHITECTURE.md that people and coding agents both read before changing code.
How to treat a multi-step coding agent run as a distributed transaction: pair each tool with a compensation, log every intent before the call runs, hold irreversible calls in an outbox until the run succeeds, and send corrections to the people who saw a change that got reverted.
You'll learn how old comments, fixtures, docs and error strings in a legacy repo can act as prompt injection for coding agents, how to find and triage them, and how to limit the damage when one slips through.
You'll learn to cut scope by what your team can understand and support instead of what it costs to build, using written non-goals in agent briefs and a three-question ownership test in review.
You'll learn how to write acceptance criteria a coding agent can follow without asking questions, using the no-questions test, must-NOT criteria, and a split between machine-checkable and judgment criteria.
You'll learn why a reversible change can become expensive to undo once coding agents copy it across many repos, and how a repetition threshold, a precedent flag and a weekly pattern diff keep that in check.
You'll learn how the database write-ahead log rule lets a coding agent resume exactly where it crashed, using intent and commit records, fsync, idempotent tools, checkpoints, and safe handling of external side effects.
You'll learn to rewrite a user story so its "so that" becomes the testable outcome and its "I want" becomes a suggestion, so a coding agent builds what the feature is actually for.
You'll learn the difference between guardrails written into an agent's prompt and guardrails the environment enforces, and how to decide which of your rules need which.
How to replace a status standup with a short, tag-driven meeting that only handles the trade-offs, ambiguous specs and blockers your coding agents can't decide on their own.
You will learn how to agree on what 'done' means before work starts, using BATNA and a five-line Done Contract, and how to hold to it with teammates, PMs and coding agents.
You'll learn how to measure prompt cache hits in a coding agent harness, and how to fix the things that quietly break caching: volatile values in the system prompt, shifting tool lists, shared CLAUDE.md edits, aggressive compaction and badly placed breakpoints.
You'll learn to add one "done =" line to your prompts that sets a checkable finish line and fences off the shortcuts you'd reject, so you skip the correction loop.
You'll learn to spot five common ways a coding agent run goes wrong while it is still running, check for each one in about 10 seconds, and decide whether to steer the run, kill it, or let it finish.
You'll learn why headcount no longer tracks a manager's load on teams that run coding agents, how to measure open decisions over five days, and three ways to reduce them without hiring.
You'll learn how to treat a feature flag rollout as a product decision when coding agents write much of your code, using a rollout card that sets the segment, exposure steps, metrics, rollback condition, owner and kill date.
You'll learn why coding agents copy whichever pattern shows up most often in your repo, how that tilt grows with every PR an agent opens, and four ways to fix it: cleanup, golden-path files, lint rules and ADRs written for agents to read.
You'll learn why pub/sub hides event consumers from coding agents, which lets agents ship green changes that break downstream services, and how a subscriber registry, consumer-driven contract tests and a SUBSCRIBERS.md agent rule make those dependencies visible.
You'll learn why review habits built on human code fail on agent diffs, what research on self-checking, debate and LLM judges says about verifying model output, and a practical checklist and set of team practices for adversarial review.
You'll learn how to write a one-line value proposition that sets an agent's defaults, scope and tests, and how to check it with a ten-minute agent read test.
You'll learn why coding agents can drain motivation from teams whose velocity is rising, and how to move credit to outcome ownership through retro prompts, demo credit and a catch log.
You'll learn how RLHF turns human preferences into model behaviour, why that makes assistants and coding agents prone to flattery and reward hacking, and how verifiable checks like tests help you work around it.
You'll learn what an embedding is, why embedding search works well for document RAG, why it often picks the wrong file in a codebase, and how to check its results with grep, call graphs and git history.
You'll learn what review fatigue is, how to spot it in a 1:1 with one question, and three ways to deal with it: a craft budget, counting agent design as authorship, and splitting review work by temperament.
You'll learn to measure precision@k and distractor rate alongside recall@k, and to choose how much context a coding agent gets based on whether its output passes, not on whether the right file showed up.
You'll learn how to turn invisible glue work into owned, written artifacts (decision logs, repo context files and a rotating glue owner) that unblock your team, give coding agents the context they need, and count as evidence in a promotion case.
This post explains why exponential backoff with jitter fails when many coding agents share one API key, and how to replace it with a token-based lease coordinator, DAG-weighted queueing and checkpointed agent turns.
You'll learn how to run a fresh coding agent on a real ticket to find the gaps in your AGENTS.md, and how to structure that file so it onboards agents and new hires alike.
You'll learn how to pair a new hire with a coding agent to log the agent's confident wrong guesses about your codebase, rank them by frequency × cost, and fix them in code, tooling or docs.
You'll learn what a vector database stores, how it finds results through chunking, embedding, indexing and querying, where it fits in an agent stack, and why live code needs grep, call graphs and freshness checks.
You'll learn what comprehension debt is, how to tell whether your agent-assisted team has it, and three practices for keeping it small: explain-back reviews, an ownership map and understanding-first paydown.
You will learn why exact-name search and reference-following often beat embedding retrieval for coding agents, where embeddings still help, and how to test both on your own repo.
You will learn that alignment is the gap between what you meant and what you wrote down, how agents exploit that gap through specification gaming, and how to write acceptance criteria that close it.
How to build a CI gate that fails when a coding agent changes spec-tagged test assertions or spec example outputs without changing the spec clause they cite, plus the structured waivers and agent-readable errors that stop the team from clicking past it.
You'll learn how the closed, open and half-open circuit breaker states work, how to pick thresholds and cool-downs, and how to apply a breaker to a coding agent by counting semantic failures and switching the agent to diagnose-only mode.
You'll learn when a reflect or critique step actually improves an agent's correctness, and how to replace the ones that don't with verifiers that use real evidence and can block a change.
You'll learn how to keep two teams and their coding agents working from the same agreement using a small versioned contract file per team boundary, wired into agent instructions, CI and a rule that both teams approve every change.
How to model time, status and supersession in your retrieval pipeline so a coding agent stops acting on decisions your team has already reversed.
You'll learn why an agent's plan silently loses spec constraints like transaction boundaries and idempotency, and how to catch those gaps with a traceability check before they reach production.
If your agent fleet keeps stalling on one PR while everyone else waits, you didn't get unlucky — you sharded your work the same way databases have been getting it wrong for twenty years, and the fix is just as old.
A 'never force-push' rule in bold at the top of a CLAUDE.md got broken by an agent that reasoned its way past it step by coherent step — and the reason why should change how you think about every safety rule in your prompts.
A senior engineer's battle-tested prompt fell apart the moment a teammate ran the exact same text, and the reason wasn't wording — it was everything he knew that never made it onto the page.
A flaky test got 'fixed' three times in one week by three different engineers and their coding agents — each fix was locally correct, and stacked together they built a test that could no longer fail even when the underlying bug was real, which says something uncomfortable about what happens to a team's memory once iteration gets nearly free.
Giving every engineer a coding agent seat multiplied throughput but not judgment capacity, and the fix was a review contract, not more seats.