Critères explicites plutôt qu’instructions vagues

When Claude underperforms on a task, architects often reach for a vague fix like be more precise or try harder. This rarely works.

The reliable move is to replace vague instructions with explicit criteria: a concrete rule that says exactly when to act.

Compare these two code-review prompts:

• Vague: "Be more precise about comments."
• Explicit: "Flag a comment only when it contradicts the code it describes."

The second one gives the model a testable boundary it can apply consistently.

"Be more precise" assumes Claude already knows what you mean by precise. It doesn't. It will guess, and different runs will guess differently.

Vague instructions push the decision boundary into the model's interpretation, where it is probabilistic and inconsistent.

Explicit criteria pull that boundary back into your specification, where it is stable across runs. This is the same instinct that makes hooks (deterministic) safer than prompt guidance (~90% probabilistic) for critical rules — be as concrete as the stakes demand.

A powerful template for review and classification tasks is:

"Flag X only when Y."

It does two jobs at once:

• It names the target (X) — what you're looking for.
• It bounds the trigger (only when Y) — the exact condition that justifies acting.

The word only matters: it suppresses false positives by telling Claude not to flag anything that fails condition Y.

Explicit criteria work because they are testable. For any given input, you (and Claude) can answer yes or no.

Watch how a fuzzy instruction sharpens into criteria:

• Vague: "Catch security issues."
• Better: "Flag a function only when it interpolates user input directly into a SQL string."
• Vague: "Improve the summary."
• Better: "Rewrite only sentences longer than 25 words; leave the rest unchanged."

Each "better" version names a condition an architect could verify by hand.

Explicit criteria are sharpest when you also say what not to do. The boundary has two sides.

Naming the exclusions stops Claude from over-flagging — the most common complaint in CI/CD review, where false positives erode trust in the tool.

State the in-scope condition and the out-of-scope cases side by side.

When a condition is genuinely ambiguous, add 2-4 targeted few-shot examples per ambiguity. Claude generalizes from them — it does not merely repeat them.

Few-shot examples are the best lever for consistency, edge cases, output format, and reducing hallucination. Pick examples that sit right on the boundary, including at least one negative case (something that looks flaggable but isn't).

Criteria decide whether to flag; structured output decides how the answer comes back. Combining them removes ambiguity end to end.

Use a tool with a JSON Schema and tool_choice set to any to guarantee structured output. A required reason field forces Claude to justify each flag against your criteria, which discourages weak flags.

Remember the schema rule: only mark a field required if it is always present — never require a field that may be absent, or the model will fabricate it.

In Claude Code workflows, explicit criteria belong in a shared, versioned place so every run and every teammate uses the same rules.

Put them in project-level ./CLAUDE.md (shared via VCS), not user-level ~/.claude/CLAUDE.md (personal, not shared — new teammates would miss them).

For criteria that apply to a subset of files, use a .claude/rules/ file with YAML paths frontmatter so it loads only when editing matching files — saving context versus a monolithic CLAUDE.md.

In a pipeline, the cost of a vague instruction is noise: false-positive flags that train developers to ignore the bot.

Run review non-interactively with -p and emit parseable results with --output-format json. Sharp "flag only when" criteria are what keep the false-positive rate low enough to be trusted.

Review in an isolated session (less biased than the generation context), and on re-runs include prior results so the bot reports only new or unfixed issues.

Explicit criteria make probabilistic behavior far more reliable — but they are still guidance, roughly 90% adherence, not a guarantee.

When a rule carries financial, legal, or safety consequences, criteria alone are not enough. Move enforcement to a deterministic mechanism:

• A hook (e.g. PostToolUse) that blocks the action 100% of the time.
• A programmatic precondition (e.g. don't allow a refund until get_customer returns a verified ID).

Criteria sharpen the model's judgment; hooks remove judgment from the path entirely where you can't afford a miss.

When results still drift, resist the urge to add "please be more careful." Instead, find the specific failure and tighten the criterion.

• Too many false positives? Add an exclusion to the "only when" clause.
• Missing real cases? Add a few-shot example on that exact boundary.
• Inconsistent format? Move the output into a JSON Schema with tool_choice.

Every iteration should make a rule more testable, never more emotional. That is the difference between architect-grade prompting and wishful prompting.

A CI/CD reviewer built on Claude Code is flagging too many low-value comments, and developers are starting to ignore it. The current instruction in CLAUDE.md reads: "Be thorough and flag anything that could possibly be a problem." What is the best fix?

Key takeaways:

• Explicit criteria beat vague instructions. "Flag X only when Y" beats "be more precise."
• The word only plus stated exclusions defines the negative space and kills false positives.
• Criteria must be testable: for any input, the answer is yes or no.
• Add 2-4 few-shot examples on the boundary when a condition is ambiguous — the model generalizes.
• Lock the output with a JSON Schema + tool_choice 'any'; require only always-present fields.
• Store criteria in shared project CLAUDE.md (or path-scoped .claude/rules/), not personal user config.
• When stakes are financial, legal, or safety-critical, enforce with a hook or precondition — criteria are ~90% guidance, not a guarantee.