12 Prompt Design Principles for Long-Horizon AI Agents

1. Why Prompts Written Six Months Ago May Stop Working

If you are still using the same prompts you wrote for agent models six months ago, you may be doing three things that do not help the result and may even harm it:

1. Explaining capabilities the model already has by default.
2. Repeatedly tuning its reasoning process with natural-language instructions.
3. Leaving the model to decide when the task is finished when the task has no clear completion definition.

Newer models optimized for agentic scenarios have generally changed in three ways:

• Reasoning is enabled by default and no longer needs to be explicitly “awakened.”
• Instruction following and long-context stability have improved, making them better at handling structured and hierarchical constraints.
• Tool calling and multi-step execution success rates have improved, allowing longer task chains within a single task.

Public industry evaluations often show improvements in metrics such as output speed and token consumption per task. However, exact numbers should be based on each provider’s official evaluations and your own evaluation sets. Do not copy marketing claims when planning capacity.

The key conclusion is one sentence:

The optimization direction is not “directing the model’s thinking more forcefully,” but “defining task results and boundaries more precisely.”

The former loses value as models become more capable. The latter gains value as task complexity increases.

Why Redundant Instructions Are Actually Harmful

Developers often assume that adding phrases such as “think carefully” or “pay close attention” cannot hurt. In practice, there are four clear loss paths:

• Attention dilution: Critical constraints are surrounded by ceremonial instructions. Their effective weight is diluted, and the most important restrictions may be ignored.
• Instruction competition: Conflicting or overlapping soft instructions force the model to spend extra reasoning budget on conflict resolution.
• False completion: When there is no definition of completion, the model must rely on internal heuristics to decide when to stop. It may produce deliverables that “look finished” but are not.
• Linear cost amplification: Every repeated instruction is billed again in each reasoning turn. For long-running tasks, this cost grows with the number of turns.

2. Build a Unified Prompt Structure First

Before applying the 12 principles, treat a prompt as a work specification, not as an opening line of dialogue.

A stable four-part skeleton can cover most engineering tasks:

[Goal]         One sentence describing the business or engineering result to achieve.
[Definition of Done] Verifiable acceptance criteria. All must be true for completion.
[Boundaries]     Allowed modification scope, explicit forbidden zones, and invariants that must remain unchanged.
[Evidence and Escalation] What evidence is required for conclusions, and what situations must stop the task and ask a human.

The value of this skeleton is that it minimizes process instructions and makes results and constraints explicit. The 12 principles below can all fit into these four sections.

3. Group One: Define the Result Clearly — Principles 1–3

Principle 1: Make “Done” Decidable

This is the highest-return principle for autonomous agent tasks.

A bad prompt is a one-sentence task:

Migrate the authentication system to the standard authorization protocol.

A better prompt breaks completion into verifiable items:

Task: Migrate the authentication system to the standard authorization protocol.
Definition of Done — all criteria must be satisfied:
  1. All authentication endpoints use the standard authorization protocol, with no legacy implementation call paths remaining.
  2. The existing test suite passes completely, and coverage is not lower than the pre-migration baseline.
  3. New test cases cover the authorization flow: normal login, token expiration, refresh failure, and insufficient permissions.
  4. Old authentication implementation code, feature flags, and configuration items have been removed, with no dead code left behind.
  5. API documentation, environment variable documentation, and the rollback guide have been updated.
  6. The system can be started locally with one command and verified end to end.
Stop and ask me when a product decision or irreversible operation is required. Do not make assumptions on your own.

The difference is not length. The endpoint of the first task is guessed by the model. The endpoint of the second is defined by you.

Principle 2: Use Acceptance Tests Instead of Process Guidance

Do not tell the model only “how to do it.” Provide what “done correctly” looks like.

The most reliable form is to make tests the contract:

• State which tests must be added.
• State which tests must continue to pass.
• State the exact commands used to run them.

When the model has a self-verification loop — run tests, read errors, fix issues, rerun tests — it can converge on a correct path on its own. The path may even be better than the one you assumed.

A practical example:

Verification loop — must be executed after every change:
  Run <unified project test command>
  Consider the change deliverable only if all tests pass and lint reports no new warnings.
On failure:
  Read the full error message, locate the root cause, and fix it.
  Do not comment out or skip tests to make them pass.

The last sentence is necessary. Without an explicit prohibition, the shortest path to “passing tests” may be weakening assertions.

Principle 3: Start from the Smallest Verifiable Slice

The most common reason long tasks fail is not insufficient model capability. It is excessive task granularity, which causes context expansion and state confusion midway through execution.

Break a large task into vertical slices that can be verified independently. Each slice should have:

• A clear input.
• A clear output.
• A clear validation method.
• An interface contract with adjacent slices.

A practical granularity guideline is that a single slice should be completable within one observable reasoning session, and its correctness should be automatically verifiable.

4. Group Two: Adjust Reasoning Intensity, Not Reasoning Content — Principles 4–6

Principle 4: Use Effort Levels Instead of Natural-Language Urging

Phrases such as “think step by step,” “think deeply,” and “do not rush” have very low marginal value on newer models where reasoning is always on.

The correct approach is to use the platform-provided effort level or thinking budget to control depth. Save the prompt content for the task itself.

The reverse mistake is also worth avoiding. Using phrases such as “think less” or “answer quickly” to suppress reasoning often leads to missed edge cases.

If you want faster execution, the correct approach is:

• Lower the effort level.
• Narrow the task scope.

Do not instruct the model not to think.

Principle 5: Start at a Medium Level and Tune with Evaluations

Starting at a medium effort level is the most economical default.

Adjust the level based on data, not subjective impressions:

• If the medium level has a high pass rate and low token consumption per task, keep it.
• If failures at the medium level are concentrated in areas requiring rigorous logic, such as concurrency, edge cases, or complex refactoring, raise the level only for those task types. Do not raise it globally.
• If the low level already passes reliably, lower the level and reserve budget for genuinely hard tasks.

A practical recommendation is to assign levels by task type:

• Low level: format conversion, code comments, unit test generation.
• Medium or high level: cross-module refactoring, root-cause analysis, solution design.

Store the effort level as part of the task metadata instead of manually adjusting it every time.

Principle 6: Externalize Complex Reasoning into Artifacts

For tasks spanning multiple files or stages, do not let the model “think it all through internally.” Require it to first write the plan into a file.

The plan should include:

• Goal decomposition.
• List of affected files.
• Modification order.
• Risk points.
• Verification methods.

This artifact serves three purposes:

1. It forces the model to expose logical gaps before making changes.
2. It provides a low-cost review checkpoint for humans.
3. It can be used as a recovery basis if a long task is interrupted.

Example:

Stage 1: Output only the plan document plan.md. Do not modify any code.
After I confirm the plan, enter the implementation stage.

5. Group Three: Hard-Code Boundaries and Escalation Paths — Principles 7–9

Principle 7: Explicitly Declare Forbidden Zones and Invariants

The model does not know your implicit constraints. You must explicitly state them.

Common items that should be written out include:

• Files or directories that must not be modified.
• Public interfaces and data formats that must not change.
• Legacy compatibility logic that must not be deleted.
• Performance and memory upper bounds that must be preserved.
• Categories of new dependencies that are forbidden.

Also define a rollback strategy:

• Changes should be made in small, revertible commits.
• Do not replace incremental modifications with a single overwrite-style rewrite.

Principle 8: Define Conditions That Require Stopping and Asking a Human

Autonomous operation does not mean no human involvement for the entire task.

Making “when to escalate” a decidable condition is key to risk control.

The agent should stop and ask a human when:

• It reaches a decision requiring product or business judgment, such as “Should the external response structure be changed?”
• The same root-cause fix has failed N consecutive times.
• It needs to perform irreversible operations, such as deleting data, changing production configuration, force pushing, or releasing to production.
• It discovers that a prerequisite assumption is invalid, such as a fundamental conflict between requirements and the existing architecture.

A corresponding prompt example:

Stop immediately and report if any of the following occurs. Do not proceed on your own:
  a) The external API semantics must be changed.
  b) The same issue still fails after two fix attempts.
  c) The task involves deleting production data or changing production schemas.
Report format:
  Symptom
  Solutions already tried
  Failure reason
  Two recommended options and their tradeoffs

Asking for “options and tradeoffs” changes human involvement from firefighting to decision-making. This can significantly shorten blocking time.

Principle 9: Require Evidence for Conclusions

In long-running tasks, one of the most dangerous behaviors is making definitive statements about unverified content.

Define evidence rules:

• Conclusions involving behavioral judgments must include file paths and line numbers, commands and full output, or test logs.
• Parts that cannot be verified must be marked as “unverified” and include a method for verification.

This single rule can eliminate most deliverables that only “look finished.”

6. Group Four: Engineer Long-Running Execution — Principles 10–12

Principle 10: Proactively Manage Context Budget

Long-running tasks are not about putting everything into the context. They are about layered context management:

• Stable specifications and constraints go at the system level.
• Task slices and acceptance criteria go at the task level.
• Process details, such as logs, trial-and-error history, and temporary file contents, should be archived as files and read only when needed.

A practical technique is to generate progress summaries at key stages and persist them to disk. This helps prevent context expansion and “middle-section forgetting.”

Principle 11: Make Execution Idempotent and Recoverable

Require each slice to be implemented idempotently: repeated execution should produce the same result.

Also write execution state into an explicit state file:

• Completed items.
• Current item.
• Pending items.
• Blocked items.

If the task is interrupted, recovery only needs to point to the state file. There is no need to restate all background from scratch.

In addition, require changes to be submitted in minimal revertible units. This makes it easier to locate regressions through bisection.

Principle 12: Treat Prompts Like Code

Prompts are production assets. They need version control, review, and regression testing.

The minimum viable approach is to maintain an evaluation set of 20–50 real tasks covering:

• Typical tasks.
• Edge-case tasks.
• Known error-prone tasks.

Track four metrics:

Metric	Meaning	Optimization Direction
Task success rate	Percentage of tasks passing acceptance in one delivery	Increase
Human intervention rate	Percentage of tasks requiring human decision or correction	Decrease
Average turns	Number of interaction turns needed to reach acceptance	Decrease
Tokens per task	Total token consumption, including retries and verification	Decrease

After modifying a prompt, run the evaluation set before deciding whether to release it. Without this closed loop, judgments such as “it feels better” are not trustworthy.

7. Common Anti-Patterns

• Spending the beginning of the prompt on personality settings, polite language, and tone requirements, while pushing real constraints into the middle.
• Repeating the same constraint three times and adding “very important.” Repetition does not increase weight. It only increases cost.
• Describing reasoning depth in natural language, such as “think more deeply,” instead of using the platform’s effort-level setting.
• Concentrating all constraints at the beginning and providing no reinforcement at the end. In long contexts, middle-section information is especially likely to be weakened.
• Driving autonomous execution with open-ended phrases such as “optimize it” or “improve it” when there is no endpoint definition.
• Dispatching a large task spanning more than ten files in one go, with no slicing and no stage checkpoints.
• Specifying only what must be done, without specifying what must not be done, causing the model to refactor unrelated modules.
• Not requiring verification evidence and accepting “completed” claims for tests that were never run.

8. A Reusable Template

# Goal
<One-sentence result description, including business value>
# Background and Entry Points
- Related modules: <paths>
- Key points of the current implementation: <points>
- Invariants that must be preserved: <interface/format/performance constraints>
# Definition of Done — each item must be verifiable
1. ...
2. ...
# Verification Loop
- Run: <unified test and static analysis commands for the project>
- Pass condition: All green and no new warnings. On failure, read the full error, locate the root cause, and fix it.
# Forbidden Zones
- Do not modify: <files/directories>
- Do not introduce: <dependency categories>
- Do not make checks pass by commenting out, skipping, or weakening assertions.
# Escalation Conditions — stop and report immediately if any occurs
- The external API semantics must be changed.
- The same root cause still fails after two fix attempts.
- The task involves deleting production data or changing production schemas.
# Output Requirements
- Changes must be made in small, revertible commits.
- Conclusions must include evidence: file paths and line numbers / command output / test logs.
- Unverified content must be explicitly marked as “unverified” and include a verification method.

9. Conclusion

The 12 principles can be compressed into one paradigm shift:

Stop micromanaging the model’s thinking process. Instead, precisely define the result, boundaries, evidence, and endpoint.

For developers, this means prompt engineering shifts from “wording techniques” to “task modeling and acceptance design.” It becomes closer to writing requirement documents and test cases than to guessing the model’s psychology.

At the engineering level, these practices require platform-side capabilities, such as effort-level configuration for model services, evaluation and version management, invocation logs and monitoring alerts, and persistent storage for task state.

For example, with Baidu AI Cloud’s large model services and related general capabilities, such as model evaluation, logging, and monitoring alerts, prompt version management, evaluation-set regression, and runtime metric observation can be connected into a closed loop. This allows every prompt change to be supported by data.

What ultimately determines the success of a long-horizon agent is not how long the prompt is, but how clearly you define “done.”