Claude often appears unreliable for the same reason a new engineer appears unreliable on their first day: the assignment is written as an intention, while success is evaluated as a set of unstated facts.
"Add rate limiting" sounds compact to a person who knows the system. To Claude, it can conceal decisions about identity, storage, proxy trust, HTTP semantics, tenancy, test strategy, operational visibility, and rollout safety. A longer prompt may help, but length alone is not the answer.
A more dependable approach is to give Claude a task harness: a small, testable operating environment around the request. The harness makes the work concrete before code is changed, then makes quality visible before the task is declared complete.
This is not about turning every interaction into bureaucracy. It is about replacing vague confidence with evidence.
Treat the task as a contract
A useful task harness has five parts:
- Mission — the user or business outcome.
- Boundary — what Claude may and may not change.
- Invariants — properties that must remain true.
- Proof — commands, tests, or inspection steps that demonstrate success.
- Stop conditions — cases where Claude should pause and ask rather than guess.
This structure changes the conversation. Claude is no longer asked to "make the API better." It is asked to satisfy a contract with explicit constraints.
For example, instead of this:
Add rate limiting to the public API.
Use a task packet like this:
The prompt is still short. Its value comes from being inspectable.
Start with a reconnaissance pass
One of the most effective Claude improvement tips is to separate discovery from implementation. Asking for analysis and code in one step encourages premature commitment. Claude finds the first plausible integration point and begins building around it.
Instead, make the first turn deliberately non-destructive:
This is especially valuable in mature .NET, Node.js, and React repositories, where the obvious file is rarely the complete answer. Rate limiting might belong in middleware, a reverse proxy, an API gateway, a shared library, or a platform policy. The reconnaissance response gives a human reviewer a cheap moment to correct course.
Do not evaluate this stage on whether Claude sounds persuasive. Evaluate whether it cites real repository evidence: configuration keys, middleware order, existing test fixtures, dependency versions, and deployment files.
Turn assumptions into named decisions
Most coding-agent failures are not syntax failures. They are untracked assumptions.
Claude may assume Redis is available, that X-Forwarded-For is safe to trust, that pagination is offset-based, or that a background worker can retry an operation without duplicates. Those may all be reasonable guesses. They are still guesses.
Ask Claude to produce a compact decision table before implementation:
| Decision | Proposed choice | Evidence | Needs confirmation? | | --- | --- | --- | --- | | Rate-limit partition | Account ID, then client IP | Existing auth claims and public endpoints | No | | Storage | In-memory limiter | No shared cache configured | Yes for multi-instance deployment | | Proxy headers | Trust known proxy network only | Traefik deployment manifests | No |
This table is a practical forcing function. It makes uncertainty visible without requiring a lengthy architecture document. If an assumption is consequential, either resolve it or place it in the stop conditions.
Define negative behavior, not just the happy path
A task is underspecified when it only describes what should happen on success. Claude improves substantially when you specify what must not happen.
For an API change, include questions such as:
- What existing clients must continue to receive the same payload shape?
- Which failures are retryable, and which must fail immediately?
- What data must never appear in logs?
- What operations must remain idempotent?
- What should happen under concurrency?
- Which configuration values are forbidden from having insecure defaults?
Negative requirements are highly effective because they constrain attractive but dangerous shortcuts. For example, "do not silently fall back to a permissive CORS policy" is more actionable than "handle CORS correctly."
For database work, add preservation rules explicitly:
Claude can then reason against constraints rather than inventing its own definition of safe.
Ask for an evidence ledger at the end
A polished summary is useful, but it is not proof. End the task with an evidence ledger that maps each acceptance criterion to the artifact that supports it.
For example:
This request changes the agent's finishing behavior. Rather than stopping when the implementation seems plausible, Claude must trace claims back to tests, diffs, or configuration. Missing evidence becomes visible immediately.
For larger changes, require a distinction between verified, inspected, and assumed. A test run is verified. Reading a deployment manifest is inspected. Predicting production throughput is assumed. Mixing those categories creates false confidence.
Make CI the impartial reviewer
A task harness becomes much stronger when its proof section mirrors CI. If local instructions say one thing and GitHub Actions checks another, Claude may optimize for the local story and still produce a failing pull request.
Point Claude to the relevant workflows and ask it to run the closest feasible commands. Good proof commands are deterministic and narrow first, broad second:
For TypeScript projects, the equivalent might include npm run lint, npm run typecheck, focused tests, and the production build. The key is not running every command blindly. It is making the validation sequence explicit and ensuring the final report distinguishes commands that passed, failed, or were unavailable.
Design prompts for interruption
Long tasks are rarely completed in a single uninterrupted session. A robust harness should let another engineer—or a future Claude session—resume without rereading the entire conversation.
Ask for a handoff note containing:
- current implementation state;
- files changed and why;
- decisions already confirmed;
- open questions;
- commands run and their outcomes;
- the next smallest safe action.
This turns work into a recoverable engineering artifact rather than a disappearing stream of chat context.
The practical shift
The goal is not to craft a magical prompt. It is to build a small system around the task that makes correct behavior easier than improvisation.
Give Claude a mission, boundaries, invariants, proof, and stop conditions. Require reconnaissance before edits. Name assumptions. Describe failure behavior. Request an evidence ledger. Align validation with CI.
When the task harness is strong, Claude has less room to guess—and far more opportunity to contribute useful engineering work with results you can inspect, test, and trust.
No comments yet. Be the first to share your thoughts!