Twelve Prompting Rules for Long-Horizon Coding Agents

Long-horizon agents have moved beyond simple question answering and code completion. They now perform multi-step coding tasks, information retrieval, visual understanding, and broader knowledge work. When prompts continue to follow patterns from six months ago, the result is often not greater rigor but unnecessary instruction: the agent repeatedly self-checks, expands its search, keeps polishing work that is already deliverable, and may eventually stop to request confirmation before the task is complete.

A more reliable division of responsibility is to leave reasoning depth to the runtime’s effort setting or budget controls. The prompt should define the outcome, boundaries, evidence, and stopping point. The following twelve rules follow that principle and can be adapted directly into team templates.

1. Define “Done” as a Verifiable Checklist

“Move authentication to a standard token-based flow” describes a direction, not an endpoint. The agent must infer the scope: which interfaces should change, whether the old implementation should be removed, how much test coverage is required, and who should update the documentation. The broader the inferred scope, the longer the agent may continue iterating.

A completion definition should include the behavior change, verification method, and cleanup requirements. For example:

• All relevant endpoints use the new flow.
• Existing tests pass.
• Tests cover the critical new paths.
• The old implementation and dead configuration are removed.
• Public documentation is updated.

The agent should pause only when a blocker requires a human decision. Turning “finished” from a subjective feeling into a checklist is the first line of defense against overwork.

2. Stop Micromanaging the Reasoning Process

Instructions such as “think carefully,” “reason step by step,” and “consider every possibility” were once used to elicit intermediate reasoning. For agents that already reason continuously, these phrases often do not improve accuracy. Instead, they encourage longer internal processes and unnecessary branches.

When speed matters, do not simply write “think less.” Lower the effort setting, narrow the task, or provide stricter acceptance criteria, then compare latency, token usage, and first-pass success rates on the same examples. The prompt should specify what the reasoning must accomplish—not how the agent’s internal process should work.

3. Start with a Moderate Effort Level by Default

The highest effort level is appropriate for architectural trade-offs, difficult defects, and irreversible changes. Routine modifications, formatting work, and checklist-based test additions often require only moderate effort.

Start by running the main path at a moderate level, and increase the effort only for failed cases or high-risk subtasks. Treating maximum reasoning depth as a universal quality guarantee usually moves costs forward without replacing a clear specification.

4. Put Boundaries Next to the Objective

Boundaries may include:

• Directories that may be modified
• Modules that must not be touched
• Dependency upgrade policies
• Compatibility requirements
• Style conventions

Without explicit boundaries, an agent may refactor unrelated code in an attempt to produce a “more correct” result. A short list of prohibited actions is cheaper than repairing an oversized diff later.

Boundaries should be executable. “Do not add external dependencies” is more useful than “keep the solution simple.”

5. Require Evidence Before Conclusions

Before claiming that a task is complete, require the agent to provide verifiable evidence, such as:

• A reproduction of the failing case
• The names of passing tests
• A summary of important changes
• The relevant API contract or documentation reference

An unsupported statement such as “this should work” should be treated as incomplete.

For knowledge tasks, evidence consists of sources and the key points from the original text. For coding tasks, evidence consists of command results and observable behavior changes—not the agent’s self-assessment.

6. Define When the Agent Must Ask a Human

If an agent is never allowed to ask questions, it may guess when information is missing. If it asks about everything, a long-running task becomes a sequence of interruptions.

A practical whitelist is to pause only when:

• Two or more options would affect external behavior or data security
• A required key or permission is unavailable
• The acceptance criteria conflict with each other

In all other cases, the agent should choose the most conservative implementation consistent with the stated constraints and continue.

7. Break Down the Task Without Writing an Operation Script

A useful breakdown follows deliverable-oriented slices:

1. Define the contract and tests.
2. Implement the change.
3. Remove the old path.
4. Update the documentation.

Do not hard-code every command, filename, and reasoning step. An overly detailed script prevents the agent from using the repository’s actual structure and encourages mechanical execution when the environment differs from the assumptions.

Keep the objective at the checklist level and leave the exact path to the agent.

8. Provide Facts, Not Emotion, in the Context

Useful context includes:

• Error logs
• Interface constraints
• Sample data
• Invariants
• Previously rejected approaches

Unhelpful context includes statements such as “you are the world’s leading expert” or “this is extremely important, so make it perfect.” Role-playing rarely changes how an agent uses tools, but it does consume context-window space.

Reserve that space for stack traces, directory conventions, and acceptance commands.

9. Replace Adjectives with Acceptance Commands

Statements such as “the code should be robust, readable, and high-performance” are difficult to evaluate. Convert them into executable conditions instead:

• The specified test suite exits successfully.
• Static checks report no new issues.
• Public interface signatures remain unchanged.
• The hot path does not add another remote call.

A standard that the agent can execute is also a standard that tells it when to stop.

10. Limit the Exploration Radius

Research-oriented tasks can easily turn into unlimited searching. Set limits in advance:

• Specify which directories or document types may be inspected.
• Stop after finding two authoritative explanations for a similar issue.
• Do not modify historical files merely to achieve stylistic consistency.

Exploration is a means, while the exploration radius is a cost control. Without a defined radius, a request for “comprehensive research” can consume the budget during information gathering alone.

11. Separate Preferences from Hard Constraints

Some requirements are non-negotiable. Violating them means failure. Examples include:

• Transaction boundaries
• Permission checks
• Prohibitions on recording sensitive fields

Preferences are defaults, such as reusing an existing utility function whenever possible. If reuse would violate a hard constraint, writing a new implementation should be allowed.

Mixing these two categories causes the agent to hesitate between style and correctness, or to introduce unnecessary changes merely to satisfy a preference.

12. Review Prompts Using the Same Measurement Standard

Change one factor at a time, such as:

• The completion definition
• The effort level
• The stopping condition
• The evidence requirement

Track whether the task reaches closure on the first pass, how often human intervention is required, the amount of rework in the final diff, and total token usage.

In older prompts, repeated reasoning slogans, role-playing instructions, and vague quality terms should be removed first. Observe the results before adding more text.

A Short Prompt Template

The template can remain concise:

Goal: Migrate login-related endpoints to token-based validation.
Done:
- All relevant endpoints use the new flow.
- The old session implementation is removed.
- Existing tests and new critical-path tests pass.
- The documentation is updated.
Boundaries:
- Modify only the authentication module and related tests.
- Do not upgrade unrelated dependencies.
- Do not change billing logic.
Evidence:
- List test identifiers and summarize key differences.
- Explicitly identify any checks that were not run.
Stop:
- Ask only when the security semantics have mutually exclusive options.
- Otherwise, choose the option that preserves compatibility with existing clients and continue.

In practice, place this template in the repository’s task instructions rather than repeating it in every conversation.

The quality of a long-horizon agent depends on whether the endpoint is clearly defined—not on whether the prompt tries to arrange the agent’s entire thinking process.