How to Stop AI Slop in Claude Code Pull Requests and Plans

Hello builders,

Give it a format, and a Claude Code PR description becomes one your team reads once and acts on. The change a user will notice sits on line 1. Its plans and handoff notes follow the same format. I read more agent-written text in a day than most people read in a week. Pull requests are where fog costs the most, because every reviewer who opens one pays for it. Kenton Varda got fed up enough to ban AI-written descriptions from the team.

Here’s how Varda put it:

I just declared a moratorium against AI-written change descriptions (e.g. PR and commit messages, also issues/tickets) from my team. AI was writing change descriptions that were worse than useless to me as I tried to review PRs: outlining details of the code that could easily be seen by looking at the code, but omitting the higher-level framing needed to understand broadly what the code is doing.

(Kenton Varda, quoted by Simon Willison)

We call that AI slop in a pull request: details anyone can read in the diff, and nothing a reviewer needs to decide.

I’d keep the agent writing and give it a format, one line for pull requests and one each for plans, status reports and handoff notes. I like these lines because each one answers a single question for its document: what does the reader need first?

The format lines

We put these in ~/.claude/CLAUDE.md, or in a CLAUDE.md in the repo’s root folder when the whole team should get them. If the file already exists, we paste the block at the top and keep the rest. The two-line writing rule goes first. It names ASD-STE100, the plain English of aircraft repair manuals, which keeps each sentence short inside every format.

The whole block:

Write every reply in ASD-STE100 Simplified Technical English.
Code, commands, file paths, names, prices and numbers stay exactly as they are.

When you write a plan: start with the proposed change in one or two sentences. Then number the steps, one action per step. Use one name for each component in every step. End with the decisions you need from me, as questions.

When you write a pull-request description: give a title that says what changes for the people who use it. Then write what the change does, why (with the ticket), how to test it, and what to review first.

When you report on a task: give the result first, then the evidence, then what is next. Do not open with what you did. Do not hedge the result.

When you write a handoff note: give the state (what works and what does not), the open items as a numbered list, the one next action, and the name you used for each component.

A code comment says what the code does now, or why. It never describes the change that produced it.

Start a new session after you save the file, since CLAUDE.md loads when a session starts and an open session won’t see the change.

What came back

I ran the same pull-request prompt with and without the format. The prompt described a retry change to fetchInvoices() that fixes the duplicate-invoice bug in ticket BILL-212. The default title was “Retry fetchInvoices() with exponential backoff (fixes BILL-212)”, 7 words about a function and a technique. With the format, the title came back as “Invoice list no longer shows duplicate invoices after a timeout,” 10 words about the bug a user saw. A product manager can read that title, and so can you in six months. The whole description went from 282 words to 212, and it gained a numbered “How to test” list and a “What to review first” section that the default didn’t write.

The plan moved even more, since the same rate-limiting prompt that gave a 959-word plan without the format gave 493 words with it. It opens with “Proposed change: Add a rate limiter to the Express app that keeps its counters in Redis, so all app instances share the same limits.” The next sentence adds a per-IP limit in nginx. A reviewer can say yes or no from those two sentences, before reading a single step. It ends with a section called “Decisions I need from you,” six questions long.

The status-report line is my favorite of the four, because it catches something worse than fog. GattyWorks published this default status report from an agent. It opens “I’ve gone ahead and implemented the requested changes and also took the liberty of refactoring some adjacent utility functions.” That sentence hides a change to a file nobody asked the agent to touch. The format version names it on line 2: “I also changed format.ts, which you did not ask for.” A reviewer who reads only that line knows where to look before merging.

The plan in the picture is a smaller example I wrote for the book. Three names for one read replica became one name, and the vague “once replication lag looks healthy” became a question for you. The handoff line gives the next session or person three things. We get the state, the open items with their file paths, and one next action. The note in the picture dropped from 52 words to 30, and its longest sentence from 32 words to 8.

If your team uses a pull-request template, we add one comment line anywhere in .github/pull_request_template.md. Then the agent sees the format every time it fills one in.

The line:

<!-- Fill this in for the reviewer: what changes for the people who use it, why (with the ticket), how to test it, and what to review first. -->

Then ask your agent for one real plan, one pull request, one status report and one handoff note from today’s work. The last line of the block covers code comments, so they say why the code is the way it is. Read only line 1 of each document. The plan should say the change, and the pull request should say what a user will notice. The status report should say the result, and the handoff should say what works. Any line 1 that names a function or narrates what the agent did is written for the agent. Tighten that format line and run it again.

Now go build something this weekend!

John Cook