Prompt Effectiveness Criteria

# Prompt Effectiveness Guide — How Claude Interprets Your Instructions

This reference explains how Claude Code actually processes skill instructions, agent definitions, and hooks. Use it to understand why certain prompt patterns work better than others and to diagnose issues where Claude behaves unexpectedly.

---

## 1. Common Ambiguity Patterns

These verbs/phrases sound clear to humans but are semantically empty for Claude. Claude will substitute its training priors, which may not match your intent.

| Ambiguous pattern                     | What Claude does                          | Better alternative                                                            |
|---------------------------------------|-------------------------------------------|-------------------------------------------------------------------------------|
| "Handle the error"                    | Logs it and continues (most common prior) | "If 4xx, return empty result. If 5xx, retry once, then fail with error."      |
| "Process the data"                    | Reads it and produces a summary           | "Parse each row as JSON, validate against schema, collect failures in array"  |
| "Manage the state"                    | Creates a variable and updates it         | "Store in `Map<string, State>`, update on event X, clear on event Y"          |
| "Ensure quality"                      | Does nothing measurable                   | "Run `pnpm lint && pnpm test` and fail if either exits non-zero"              |
| "Check if valid"                      | Returns boolean with no definition        | "Validate: field X is non-empty string, field Y matches regex `/^\d{3}$/`"    |
| "Clean up"                            | Deletes temporary files                   | "Remove files matching `*.tmp` in `./out/`, but preserve `./out/index.html`"  |
| "Optimize"                            | Adds caching                              | "Reduce response time by batching DB queries: max 1 query per entity type"    |

---

## 2. Claude's Interpretation Heuristics

When instructions are ambiguous, Claude falls back to these defaults:

### 2a. Missing error handling → Claude skips errors silently
If your skill doesn't say what to do when something fails, Claude will typically try/catch and continue. This is almost never what you want.

**Fix**: Always specify failure behaviour explicitly: