Design Prompts with Explicit Criteria
This module is about precision prompting: giving Claude specific reporting criteria so it flags real issues and avoids noisy, trust-damaging false positives.
Can you improve prompts like:
Into concrete, categorical criteria like:
- Report a comment issue only when the comment makes a specific behavioral claim that directly contradicts the current code behavior.
- Do not report vague, incomplete, outdated, stylistic, or non-behavioral comments.
Anthropic’s prompt engineering docs emphasize that clear, explicit instructions improve results, and that Claude performs better when you specify the desired output, constraints, and success criteria rather than relying on vague prompts. (Claude)
1. Why Vague Instructions Fail
1.1 Weak Prompt
Problem: “accurate” is too broad.
1.2 Better Prompt
Flag comment issues only when all of these are true:
1. The comment makes a concrete claim about runtime behavior, data shape, security behavior, error handling, or side effects.
2. The current code directly contradicts that claim.
3. The contradiction could mislead a developer into using or modifying the code incorrectly.
Skip:
- comments that are merely incomplete
- comments that use older terminology but are not behaviorally wrong
- comments that are vague but not contradictory
- comments in generated files
- style or grammar issues
This prompt defines a category boundary.
Anthropic’s Code Review docs describe review customization in similar terms: you can tune what Claude flags, define severity, list skip rules, require evidence before findings, and suppress categories that are noisy or already covered by CI. (Claude)
2. Mention Explicit Criteria
The official guide makes this point directly.
Weak:
These sound good, but they do not tell Claude which findings are allowed. Better:
Report only these categories:
1. Correctness bugs introduced by this diff that can cause wrong output, crashes, data loss, or broken user-visible behavior.
2. Security issues introduced by this diff, including auth bypass, tenant isolation failure, sensitive data exposure, or injection risk.
3. Broken edge cases where the new code fails for null, empty, boundary, or common invalid inputs already handled elsewhere.
Do not report:
- formatting, lint, naming, or style issues
- issues CI already enforces
- purely hypothetical risks without a plausible execution path
- pre-existing issues not introduced by the diff
- minor local pattern differences with no behavioral impact
This converts “be conservative” into a clear decision rule.
3. Report Vs Skip Criteria
A strong review prompt should say both:
3.1 Sample High-Precision Code Review Criteria
# Review Criteria
Report only issues introduced by this diff that meet one of these categories:
## Report
### Correctness
- The changed code can produce incorrect output for a realistic input.
- The changed code can throw an exception on a common path.
- The changed code breaks an existing documented behavior.
- The changed code mishandles null, empty, boundary, or invalid input in a way that affects runtime behavior.
### Security
- The changed code weakens authentication or authorization.
- The changed code exposes secrets, PII, tokens, or tenant data.
- The changed code introduces injection, path traversal, SSRF, XSS, or unsafe deserialization risk.
- The changed code logs sensitive request or user data.
### Data integrity
- The changed code can corrupt, drop, duplicate, or incorrectly migrate data.
- The changed code can create inconsistent state after retry or partial failure.
## Skip
Do not report:
- formatting, lint, or type errors already enforced by CI
- subjective style preferences
- minor naming differences
- pre-existing issues not introduced by this diff
- generated files, lockfiles, or vendored dependencies
- missing tests unless the missing test creates concrete regression risk under project policy
Claude Code’s Code Review docs say default reviews focus on correctness bugs that would break production, not formatting preferences or missing test coverage, and that review guidance can define skip rules such as generated files, lockfiles, vendored dependencies, and categories already enforced by CI. (Claude)
4. Temporarily Disabling Noisy Categories (False Positive)
The official docs says you should know when to disable high false-positive categories.
Use this when:
- A category is often wrong.
- Developers are losing trust.
- The prompt lacks enough criteria.
- The category needs better examples or validation.
- You need to preserve signal from accurate categories.
4.1 Better Response
Temporarily do not report comment accuracy findings.
Reason:
This category has produced too many false positives.
Replacement rule:
Only report comment/code mismatches when the comment makes a concrete behavioral claim that directly contradicts current code behavior and could mislead future maintainers.
Claude Code’s review customization docs explicitly support skip rules and higher bars for noisy categories or paths, such as “only report if near-certain and severe” for certain areas. (Claude)
5. Severity Criteria
Docs specifically call out defining severity criteria with concrete code examples.
A weak severity rubric:
A better rubric:
# Severity Rubric
## Important
Report as Important only if the issue should be fixed before merging.
Important includes:
- production correctness bug
- security vulnerability
- data loss or corruption
- tenant isolation failure
- crash on a common user path
- broken documented behavior
- migration that is not idempotent when reruns are expected
## Nit
Report as Nit only if the issue is worth fixing but not merge-blocking.
Nit includes:
- small maintainability issue
- minor project convention violation
- unclear code that could reasonably confuse future maintainers
- missing low-risk test under project standards
## Skip
Do not report:
- pure style preferences
- formatting/lint/type issues already handled by CI
- speculative concerns without evidence
- pre-existing issues
- generated files
Claude Code’s Code Review docs define severity categories such as Important, Nit, and Pre-existing, and note that review guidance can redefine what Important means for a repository. (Claude)
6. Ask for Evidence
One of the best ways to reduce false positives is to request evidence, this makes the agent work and not be lazy.
Weak:
Better:
For every finding, include:
1. The exact changed line or block.
2. The execution path that triggers the issue.
3. The expected behavior.
4. The actual behavior caused by the diff.
5. Why this was introduced by the diff, not pre-existing.
6. A minimal example input if applicable.
Do not report if you cannot provide this evidence.
Claude Code’s review docs recommend requiring evidence for classes of findings; for example, behavior-claim findings should cite source evidence rather than infer from naming. (Claude)
7. How to Tune a Noisy Review Category
Suppose your review prompt currently includes:
Claude posts many weak findings:
7.1 Step 1: Disable or Narrow Temporarily
Temporarily skip performance findings unless there is direct evidence of a newly introduced unbounded operation on a production path.
7.2 Step 2: Add Categorical Criteria
Report performance issues only when:
1. The diff introduces a repeated network call, database query, or expensive computation inside a loop over an unbounded collection.
2. The previous code avoided that repeated operation.
3. The input size can realistically grow in production.
4. The finding includes the loop, the repeated operation, and the production path.
Step 3: Add Examples
Report:
for (const user of users) {
await db.orders.findMany({ where: { userId: user.id } });
}
Reason:
This introduces one query per user for an unbounded production list.
Skip:
const displayNames = users.map(user => formatName(user));
Reason:
This is an in-memory linear transformation with no evidence of production risk.
8. Prompt Patterns to Remember
8.1 Pattern A: Report-Skip Criteria
8.2 Pattern B: Evidence Gate
Do not report unless you can show evidence for:
- changed code line
- realistic failure path
- expected vs actual behavior
- why it was introduced by this diff
8.3 Pattern C: Severity Rubric
Important = must fix before merge because...
Nit = worth fixing but not blocking because...
Skip = not worth reporting because...
8.4 Pattern D: Temporary Disablement (False Positive)
Temporarily do not report [category] findings.
Only re-enable when the prompt defines exact reportable conditions and examples.
8.5 Pattern E: Examples Per Severity
Here are examples of Important, Nit, and Skip findings.
- Classify new findings consistently with these examples.
9. Cheat Sheet
Memorize this:
1. Explicit criteria beat vague instructions.
2. “Be conservative” is weaker than report - skip rules.
3. “Only high-confidence findings” is weaker than categorical criteria.
4. Define what to report and what to skip.
5. Focus review prompts on bugs, security, regressions, and concrete behavior.
6. Skip style, formatting, lint, and issues CI already catches.
7. Require evidence for findings.
8. Require realistic failure scenarios.
9. False positives reduce developer trust.
10. Noisy categories can damage trust in accurate categories.
11. Temporarily disable high-false-positive categories while improving prompts.
12. Define severity levels with concrete impact criteria.
13. Important should mean “must fix before merge.”
14. Nit should mean “worth fixing but not blocking.”
15. Add concrete code examples for Important, Nit, and Skip.