proto[code]

A Reviewer’s Field Guide to Slop

Eight kinds of slop in agent code, how to spot each one in a diff & the one-line rule that keeps it out.

Slop Is a Review Problem

Slop is code that works, or looks like it works, & costs more to read & maintain than the task called for.

An agent can write a diff faster than you can read the first file. The writing got cheap. The reading didn’t, & every line the agent adds is one your team reviews today & maintains for as long as it exists.

My bar for agent code is the smallest change that fully does the job, written the way the rest of the codebase already writes it. Google’s code review guidelines draw the same line around over-engineering:

Encourage developers to solve the problem they know needs to be solved now, not the problem that the developer speculates might need to be solved in the future.

Google Engineering Practices, What to Look For in a Code Review
WHAT THE TASK NEEDEDThe changeWHAT THE AGENT SENTThe changeInterfaceOptionsError handlingCommentsHelper copyTODOWhat the reviewer also has to read
Figure 1. An illustrative diff for a one-line task. The change you asked for is the small part, & the reviewer reads all of it.

What Kinds of Slop Are There?

Slop comes in three kinds: code the task didn’t need, code that already exists & code that isn’t finished.

BLOATED1Speculative abstraction2Options nobody asked for3Defensive code4Narrating commentsDUPLICATED5Duplicate helpers6A second way to do itHALF-FINISHED7Stubs & TODOs8Tests that test nothingCOSTS YOUReview timeCOSTS YOUTwo places to fixCOSTS YOUSurprises in production
Figure 2. The eight patterns by kind. The numbers stay the same throughout.

Each kind costs you something different. Bloat costs review time. Duplication leaves two places to fix, & the next bug fix lands in only one of them. Half-finished code passes a skim & you find out in production.

Bloat is the easiest to spot & the easiest to wave through. That’s why it’s worth pushing back on first. A stub or a hollow test is much easier to miss in 300 lines than in 30.

The Eight Patterns

Rows are patterns. The middle column is the tell in the diff, & the last is a rule short enough to paste into your agent’s instructions.

Bloated

PatternSpot it in the diffThe rule
1Speculative abstractionA new interface, base class or factory with exactly one implementation. A Manager or Provider wrapped around a single case.Add the abstraction when the second case shows up.
2Options nobody asked forNew parameters every caller leaves at the default. New config keys. A flag for behavior the task never mentioned.Build what the task asks for & nothing it might ask for later.
3Defensive codeNull checks on values the types already guarantee. A try/catch that logs & rethrows. The same validation at every layer.Validate at the boundary & trust the types inside it.
4Narrating commentsA comment above each line saying what the line does: // Save the order.Comment the why. The code already says what.

Duplicated

PatternSpot it in the diffThe rule
5Duplicate helpersA new private method with a generic name in a feature file: FormatDate, IsValidEmail, RoundToCents.Search the codebase before you write a helper.
6A second way to do itA different error handling style, a new library for a job an existing one does, a folder shape no other feature uses.Follow the pattern the codebase already uses. When there isn’t one, ask.

Half-finished

PatternSpot it in the diffThe rule
7Stubs & TODOsTODO comments, NotImplementedException, hard-coded return values, sample data left in place, new code nothing calls yet.Finish every path, or list the gap in the pull request.
8Tests that test nothingAssertions that only check a mock was called. Expected values edited to match new output. Skipped tests.A test has to fail when the behavior it covers breaks.

Keep the rules this short. A reviewer can quote one in a comment, & an agent can follow one without guessing what you meant.

If the task didn’t need a line, the diff shouldn’t have it.

One Diff, Seven Patterns

Here is the kind of diff an agent sends back for a one-line task: give loyalty members 10% off the order total.

+++++++++++++++++++++++++++public interface IDiscountService{decimal Apply(Order order, decimal rate = 0.10m);}public class DiscountService(ILogger<DiscountService> logger) : IDiscountService{public decimal Apply(Order order, decimal rate = 0.10m){try{// Apply the rate if the customer is a loyalty membervar discount = order.IsLoyaltyMember ? rate : 0m;return RoundToCents(order.Subtotal * (1 - discount));}catch (Exception ex){logger.LogError(ex, "Discount failed");throw;}}private static decimal RoundToCents(decimal value) =>Math.Round(value, 2, MidpointRounding.AwayFromZero);// TODO: support tiered loyalty levels}1263457
Figure 3. 27 lines for a one-line task, & nothing calls the new class yet. Each number is one of the eight patterns.
public decimal Total(Order order) =>-Money.Round(order.Subtotal);+Money.Round(order.Subtotal * (order.IsLoyaltyMember ? 0.9m : 1m));
Figure 4. One changed line, in the method that already owns the total, using the rounding helper the codebase already has.

Catch It Before Review

Review is the most expensive place to catch slop. Stop each pattern at the earliest stage that can catch it.

BEFORE IT WRITESBEFORE THE PULL REQUESTIN REVIEWAgent instructionsToolingReviewA rule & an examplefor every patternPatterns 2, 3, 5, 6, 7 & 8on every pull requestPatterns 1 & 4& the judgment calls
Figure 5. Each stage catches what the one before it missed. Review gets what’s left.

I’d rather an agent read a rule once than write the same review comment every week. A rule works best with an example from your own codebase beside it, so the agent copies the right shape instead of guessing at it.

PatternCatch it with
1Speculative abstractionA rule in the agent’s instructions, with an example of when your codebase does add an interface. Review catches the rest.
2Options nobody asked forUnused parameter analyzers catch the options nothing reads: IDE0060 in .NET, no-unused-vars in ESLint. Review catches the ones no caller sets.
3Defensive codeStrict null checking, plus a linter rule for conditions that can never be true, like typescript-eslint’s no-unnecessary-condition.
4Narrating commentsA rule in the agent’s instructions, then review. Telling a useful comment from a narrating one takes judgment.
5Duplicate helpersCopy & paste detection (jscpd, PMD’s CPD) for near copies. A “search before you write” rule for helpers that do the same job with different code.
6A second way to do itArchitecture tests (ArchUnit, NetArchTest) for layers, dependencies & naming. An example of the existing pattern in the agent’s instructions.
7Stubs & TODOsA CI check that fails when a pull request adds TODO, FIXME or NotImplementedException.
8Tests that test nothingMutation testing (Stryker) breaks your code on purpose & shows which tests still pass.

How Do You Review a Diff for Slop?

Most slop shows up before you read a line of logic, if you read the diff from the outside in.

1File listNew files or folders the task didn’t call for?A folder shape nothing else uses?1 · 62New types & methodsAn interface or base class with one implementation?A helper with a generic name?1 · 53SignaturesNew parameters, defaults or config keysthat no caller sets?24Catches & commentsA catch that logs & rethrows? A comment thatrestates its line? A TODO?3 · 4 · 75TestsWould any assertion fail if the codewere wrong?8
Figure 6. Work from the file list inward. The numbers on the right are the patterns each step catches.

When the scan turns up a pattern, send the pull request back with the rule quoted. Cleaning it up yourself fixes one pull request. Adding the rule to the agent’s instructions fixes the next one too.

An Afternoon Audit

You can find out which patterns your agents fall into most in an afternoon. Do it with the people who review the most agent code. They already know which patterns they’re tired of.

  1. Pick 10 recent pull requests where an agent wrote most of the code.
  2. Scan each one outside in & tally the patterns you find.
  3. Next to each pull request, note how many lines the task needed & how many it added. A rough guess is fine.
  4. Take your top three patterns. Add their rules to the instructions your agents read, each with one example of the right way from your own code.
  5. Add a tooling check for any of the three that a tool can catch.
  6. Two weeks later, run the same audit on the next 10 & compare.
PATTERNPR 1PR 2PR 3PR 4PR 5PR 6PR 7PR 8PR 9PR 10TOTAL1Speculative abstraction2Options nobody asked for3Defensive code4Narrating comments5Duplicate helpers6A second way to do it7Stubs & TODOs8Tests that test nothingLines needed / added
Figure 7. One column per pull request. The totals tell you which rules to write first.

The writing got cheap. Keep the reading cheap too: put the rules where the agent reads them before it starts, & save review for the calls only a person can make.

proto[code] serves your rules & examples to every coding agent through MCP, so each agent reads them before it writes.

Resources

The guidelines & tools behind these patterns, if you want to go deeper.