Review comments to improve prompts in code generation

Why the same review comments return

Repeated review notes usually point to expectation gaps, not isolated code mistakes. AI generated code often looks acceptable on a quick read, then misses the habits your team follows every day: naming, test coverage, error handling, file boundaries, or where certain logic belongs.

That is why the same notes appear across pull requests. One PR gets "add failure-case tests." Another gets "split this file." A third gets "keep database calls out of the controller." The files differ, but the rule behind the comment is the same. If nobody turns that rule into a prompt constraint, reviewers teach the same lesson again next week.

The cost hides in small edits. Two minutes for naming. Five for logging. Ten to move logic into the right layer. On a busy team, those minutes pile up quickly.

Generic prompts make this worse. "Write clean, maintainable code" sounds reasonable, but it does not tell a model what your team means by clean. Some teams want thin controllers and strict service boundaries. Others prefer fewer layers and shorter files. A generic prompt falls back to average patterns, and average patterns often miss local standards.

Small teams feel this first. If three people spend all week reviewing AI generated code, repeated comments pull attention away from product choices, bug risk, and architecture. Review becomes routine correction instead of a real quality check.

Most repeat comments fall into a few familiar buckets: missing edge case tests, unclear naming, too much logic in one function, weak error messages, and code that ignores existing repo patterns. Once those notes start repeating, they stop being one off edits. They become good candidates for reusable prompt rules.

Which comments belong in the prompt

Some comments belong in prompts. Others belong in review and should stay there.

A comment is a good prompt rule when it appears across different tasks, files, and developers. If reviewers keep writing "split this function," "validate input," or "use the project error format," the model is missing a shared standard. When the same note shows up three or four times in a short stretch, treat it as a rule worth capturing.

The best candidates usually affect how code reads, how safely it behaves, and how the project stays organized. That includes naming, file layout, test expectations, log format, input validation, auth checks, timeout handling, and rules about where business logic belongs.

Skip one off preferences. If one reviewer prefers a certain import order or comment style, that usually does not belong in the prompt unless the team agrees it matters. Prompts should carry shared standards, not personal habits.

A simple filter helps: would this comment still make sense next month on a different task? If yes, keep it. If it only fits one file or one person's taste, leave it out.

Start with rules that save review time fastest. "Add tests for new branching logic" can remove a full round of comments. "Never call an external service without timeout and retry handling" can prevent bugs before anyone opens the pull request.

This matters even more when one lead engineer or CTO reviews code across several products. Repeated comments stack up fast. Turning them into prompt rules cuts noise and leaves reviewers with the harder questions: tradeoffs, architecture, and edge cases no prompt can settle on its own.

How to turn a comment into a usable rule

Start with a real review comment, not a made up policy. The strongest rules usually come from something a reviewer already typed several times in the same month.

Take a comment like "Don't swallow errors in API handlers." It helps in a review, but it is too loose for a prompt. The model can follow it in several different ways and still miss what your team wants.

A better version names the behavior in plain language: "In API handlers, never leave a catch block empty. Log the error, return a clear error response, and keep the original status code when an upstream service already set one." Now the model has a concrete instruction, and a reviewer can check it quickly.

A good rule answers five questions: where it applies, what the code should do, what it should avoid, which exceptions exist, and how a reviewer can tell whether it passed. If two reviewers would argue about whether the rule was followed, the wording is still too soft.

Add limits while the example is fresh. If the rule only applies to public endpoints, say so. If test helpers can skip logging, say that too. Weak rules usually fail on edge cases, not on the happy path.

The wording matters more than most teams expect. "Handle errors properly" creates drift. "For public API handlers, return JSON errors with message and code, never expose stack traces, and log unexpected failures once" gives the model something it can repeat.

You are not trying to write a perfect policy document. You are trying to turn one repeated correction into a rule that produces a better first draft.

Test the rule on one small task before you add it everywhere. A tiny endpoint, one background job, or one form handler is enough. If the AI follows the rule without extra explanation, the rule is probably clear enough.

Organize rules by task type

Prompts get worse when they try to control everything at once. A giant wall of rules looks thorough, but it usually creates noise. The model skips parts, mixes priorities, or follows the wrong rule for the job.

Smaller rule blocks work better. You can reuse them, swap them in and out, and spot which block caused a bad result.

Most teams do well with separate blocks for naming, tests, error handling, and docs. Keep each block narrow. If the naming block starts talking about retries, it is doing too much.

Match the blocks to the task. A small UI copy change does not need the same prompt as a database migration. A backend bug fix may need error handling and tests. A refactor may need naming and doc rules, but no release note guidance.

This gets more obvious when a team works across several layers. A React screen, a Go service, and a CI job rarely trigger the same review comments. If you force one master prompt onto all three, the prompt gets longer and less clear.

Rules also expire. Teams rename folders, switch test tools, drop old patterns, or change logging style. If stale rules stay in the prompt, the model keeps producing code that matches the prompt and clashes with the repo.

Set a simple maintenance habit. Every few weeks, check which prompt blocks still prevent repeat comments and which ones now create friction. Remove dead rules. Rewrite fuzzy ones. Split any block that has turned into a mini policy document.

You do not need a perfect master prompt. You need a small set of clear constraints that fit the task in front of you.

Use examples instead of abstract advice

Abstract rules leave too much room for guessing. A model can read "use clear names" and still produce data, item, or tmp. A short example pair closes that gap fast.

Instead of saving a note like "please handle errors better," save a tiny before and after snippet that shows what the team accepts.

Show the bad version next to the better one

A small contrast works better than a long explanation. Keep it to one function or one test file so the model can copy the pattern without getting lost in extra detail.

// Bad
function proc(u) {
  if (!u) return null;
  return { n: u.name };
}

// Better
function buildUserProfile(user) {
  if (!user) {
    throw new Error("user is required");
  }

  return { name: user.name };
}

The second version is easier to review. The name says what the function does, the error is explicit, and the return shape is readable without a comment.

A full file usually adds noise. A 10 to 20 line snippet is enough to teach the rule. Teams that move quickly with AI coding tools often get better results from three short examples than from one large "reference implementation."

Show the tests you expect

If you want better output, show the tests that match your team's habits. Do not just say "add tests." Show success and failure cases in the style your team already reviews and merges.

test("throws when user is missing", () => {
  expect(() => buildUserProfile()).toThrow("user is required");
});

test("returns the expected shape", () => {
  expect(buildUserProfile({ name: "Sam" })).toEqual({ name: "Sam" });
});

These examples teach several rules at once: use names that say what the code does, throw clear errors instead of failing silently, test both the happy path and the failure path, and add comments only when the reason is not obvious.

That last point matters. Comments should explain why a choice exists, not repeat what the code already says. If your team follows that rule, include one example with a useful comment and one with a pointless comment. Models usually learn the difference faster from a concrete contrast than from another paragraph of instructions.

When the examples look like real review fixes, the prompt starts to sound like your team instead of a generic style guide.

A review cycle example

One comment shows up often in generated backend code: the handler accepts input and goes straight to the database with almost no checks. The code passes a quick smoke test, then fails on empty fields, bad IDs, or numbers that should never be negative.

A repeated comment like that should stop living only in pull requests. Turn it into a prompt rule for handler functions.

Use wording that leaves little room for guessing:

For every HTTP handler, validate path params, query params, and JSON body fields before calling services or the database. Reject missing or malformed required input with status 400 and a short error message. Stop execution after the first validation failure.

Now make it specific. If the team often reviews a generated CreateInvoice handler and leaves notes like "Check customerId", "Reject zero amount", and "Do not accept missing currency", add those expectations to the task prompt, not just the general rule. The model then has both the pattern and the task specific checks.

The next generated file usually changes in an obvious way. Instead of parsing the body and calling invoiceService.create(...) on line five, it starts with guards. It checks that customerId is present, amount is greater than zero, and currency is not empty. If one check fails, the handler returns a clear 400 response and exits.

That is better, but review still matters. A reviewer still needs to check whether the rule fits the product, whether the error text matches the rest of the app, and whether the handler leaks too much detail in logs or responses. The prompt can enforce the habit of validation. People still decide what "valid" means for the business.

Mistakes that make prompts worse

Teams often take a focused prompt and turn it into a dumping ground. That usually makes generated code less consistent, not more.

A common mistake is pasting every old review note into the prompt. Most review comments are local. They fix one bug, one odd naming choice, or one rushed shortcut. If a comment does not repeat across many pull requests, it probably does not belong in the prompt.

When rules fight each other

Conflicting rules confuse the model quickly. A team might tell it to "keep functions short" and also "avoid extra helper functions." Both ideas can make sense, but not in the same way for every task. When rules clash, the model guesses, and guessing produces odd code.

Teams run into similar problems when they never remove old rules. Standards change. A team allows a new pattern, renames a layer, or accepts a different testing style, but the prompt still pushes the old choice. Then the model keeps producing code that reviewers already left behind.

Vague words break the rule

Words like "clean," "better," and "simple" sound useful, but they do not tell the model what to do. Different reviewers mean different things when they use them. One means fewer lines. Another means clearer names. A third means fewer abstractions.

Weak rules usually sound like this:

• "Write clean code"
• "Make it better"
• "Use good structure"

Those lines need a concrete rewrite. Say what you want instead: prefer early returns, keep database logic out of controllers, add a test for null input, or match the existing file pattern.

Another mistake is expecting the prompt to replace code review. It cannot. Review still catches tradeoffs, missing context, and product specific choices. The prompt handles repeat standards. Review handles judgment.

A good prompt gets shorter over time, not longer. Keep the rules that show up again and again, drop one off comments, and use plain language that leaves little room for guessing.

A quick check before wider rollout

Before you share a prompt with the whole team, try it against three or four recent pull requests. That small test will tell you whether the rules help in real work or just sound neat on paper.

Use a short checklist:

• Name the task clearly. "Improve this feature" is too loose. "Update the billing webhook handler and keep the existing response shape" gives the model a clear lane.
• Keep each rule simple. Reviewers should understand it quickly, and the model should not have to guess what words like "clean" or "better" mean.
• Match examples to the code your team writes now. If the team uses Vitest instead of Jest, or stores SQL in a specific folder, the examples should follow that pattern.
• Ask for proof when it makes sense. That might mean tests, type checks, lint results, or a short note about what the model verified and what it left alone.
• Watch the next review round. If reviewers still leave the same comment, the rule is either too vague or attached to the wrong kind of task.

The point is simple: cut repeated friction. A rule earns its place only if reviewers can see the difference in the next batch of code.

This also keeps prompts short. Five sharp checks beat a long block of instructions that nobody really follows. If one rule only matters for database work or CI changes, move it into a smaller prompt for that job instead of stuffing it into the default prompt.

Lean teams notice this quickly. When a prompt names the file type, uses plain language, and asks for proof, reviewers spend less time repeating themselves and more time checking the real change.

Make it part of the team's routine

Teams get better results when they treat repeated review notes like process defects. If the same comment shows up every week, do not leave it buried in old pull requests. Turn it into a shared rule.

Start with a short review window. Look at pull requests from the last month and pull out three comments that kept coming back. Pick ones that are easy to act on, such as missing edge case tests, vague naming, or business logic in the wrong layer.

Then turn those comments into a small prompt block the team can reuse:

• Add tests for the happy path and one failure path.
• Keep business logic out of controllers.
• Use names that describe the action clearly.

That is enough for a first version. Most teams make this too big, too fast. A prompt with fifteen rules usually becomes background noise.

Use the block in the next few tasks and watch the following PRs closely. When the model still misses the mark, rewrite the rule instead of wrapping it in more words. Short rules often work better because they leave less room for guessing.

A small log helps. Write down the rule, where the team used it, and whether it reduced review churn. After five or six PRs, you will know which rules improve output and which ones only make prompts longer.

If your team needs outside help setting up AI coding standards, oleg.is shares Oleg Sotnikov's work as a Fractional CTO and startup advisor. He focuses on practical AI assisted development, infrastructure, and lean engineering workflows for small and mid sized teams.

The goal is straightforward: fewer repeated comments, less back and forth, and code that matches the team's standards sooner.