How to Create an Intent File That Produces Better Results, Lower Costs, and Controlled Delivery

Everybody eventually asks the same question:

How do you create a good intent file?

Not a long prompt.

Not a vague business request.

Not a document filled with background material that leaves the agent guessing.

A real intent file must do something much more important.

It must tell the delivery system:

• What business outcome matters

• What must be built

• What “done” actually means

• What constraints must be respected

• What evidence must be produced

• What limits control cost and execution

• When the system must stop, retry, escalate, or fail safely

That is the difference between asking an AI system to generate something and directing an AI engineering system to deliver something.

The quality of the intent determines the quality of the execution.

And increasingly, it also determines the economics.

The Harness Is Already There

For teams already practicing Intent-Driven Engineering, the agentic harness should already exist.

The harness may have been created internally. It may have been assembled using Claude Code, skills, hooks, sub-agents, MCP servers, validators, CI pipelines, or shared engineering services.

The specific implementation is not the important part.

The harness already knows how to:

• Read intent

• Inspect repositories

• Retrieve enterprise context

• Plan work

• Call tools

• Execute tasks

• Run tests

• Validate output

• Package evidence

• Open a pull request

• Stop or escalate when necessary

Teams should not rebuild that workflow every time they need a feature.

They should provide the harness with a better intent.

That is the real operating model.

The harness is the engine.

The intent file is the steering system.

Why Most Intent Files Fail

Most weak intent files fail for one of four reasons.

They describe activity instead of outcome

“Build a dashboard” is an activity.

“Reduce the time required for operations managers to identify failed transactions from two hours to ten minutes” is a business outcome.

The second statement gives the system something meaningful to optimize around.

They leave “done” undefined

An agent cannot reliably complete work when success exists only in someone’s head.

If acceptance criteria are missing, the model will substitute its own interpretation.

That creates rework, larger token usage, unnecessary iterations, and inconsistent results.

They do not define evidence

A generated answer is not proof of successful delivery.

The system should return evidence such as:

• Test results

• Changed files

• Validation reports

• Screenshots

• API responses

• Security scans

• Performance measurements

• Remaining risks

Without evidence, the system can only claim completion.

It cannot prove completion.

They do not bound execution

An unbounded agentic process may continue planning, searching, calling tools, retrying, rewriting, and validating long after the economic value has disappeared.

A good intent file must control:

• Maximum iterations

• Maximum retries

• Maximum tool calls

• Maximum execution time

• Cost thresholds

• Confidence thresholds

• Human-review conditions

That is not administrative overhead.

That is AI FinOps built directly into the delivery request.

The Intent File Format

The strongest intent files follow a consistent structure.

Not every field must always be used, but every intent should begin from the same operating model.

intent:

  id:

  title:

  business_outcome:

  goal:

context:

  current_state:

  users:

  systems:

  dependencies:

acceptance_criteria:

  - criterion:

constraints:

  scope:

  security:

  architecture:

  performance:

  cost:

  max_iterations:

  max_retries_per_step:

  max_tool_calls:

  max_execution_time:

  confidence_threshold:

validation:

  required_tests:

  required_checks:

  validator:

  failure_conditions:

evidence_required:

  - implementation_summary

  - changed_files

  - test_results

  - validation_report

  - remaining_risks

stop_conditions:

  complete_when:

  retry_when:

  human_review_when:

  fail_when:

delivery:

  output_format:

  target_repository:

  branch_strategy:

  pull_request_required:

This format works because it turns the intent file into an executable delivery contract.

It does not merely tell the system what the user wants.

It tells the system how to interpret the request, how to control execution, how to validate success, and how to prove the result.

Start With the Business Outcome

The most important field is not the technical goal.

It is the business outcome.

business_outcome:

  "Reduce the average time required for support agents to identify and resolve failed customer orders from 45 minutes to less than 15 minutes."

A strong business outcome gives the system a reason for the work.

It connects implementation decisions to measurable value.

That matters because there may be many technically valid ways to build a feature.

The business outcome helps the system select the one that creates the most value.

A weak outcome sounds like this:

business_outcome:

  "Create an order dashboard."

A stronger outcome sounds like this:

business_outcome:

  "Allow support agents to identify the cause of a failed order within three minutes without querying production databases manually."

The second version creates clarity around usability, speed, data access, and operational impact.

It also becomes a foundation for validation.

Define the Goal Precisely

The goal should describe the specific deliverable.

goal:

  "Create a React-based failed-order investigation page that retrieves order status, downstream service responses, retry history, and the most likely failure cause."

The goal is not the same as the business outcome.

The business outcome explains why the work matters.

The goal explains what must be delivered.

Both are required.

Without the outcome, the implementation may be technically correct but commercially irrelevant.

Without the goal, the outcome may be inspiring but not executable.

Add Only the Context That Changes the Work

Context should not become a document dump.

The system does not need every fact the organization possesses.

It needs the facts that materially affect implementation.

context:

  current_state:

    - "Support agents currently inspect four separate systems."

    - "Failure data is distributed across an order API, Kafka events, and application logs."

  users:

    - "Tier 1 support agents"

    - "Operations managers"

  systems:

    - "React customer support portal"

    - "Order Management API"

    - "Kafka event stream"

    - "OpenTelemetry log platform"

  dependencies:

    - "Existing authentication service"

    - "Order API schema"

    - "Shared UI component library"

Good context reduces search, inference, and rework.

Excess context increases token usage and distracts the system from the task.

The rule is simple:

Include context that changes a decision. Exclude context that merely proves the organization has documentation.

Acceptance Criteria Define “Done”

Acceptance criteria are where intent becomes executable.

They should be specific enough for a validator to determine pass or fail.

acceptance_criteria:

  - "A support agent can search by order ID."

  - "The page displays current order status."

  - "The page displays all downstream service failures."

  - "The page displays retry attempts in chronological order."

  - "The system identifies the most likely failure cause."

  - "Unauthorized users cannot access order details."

  - "The page loads within two seconds for 95 percent of requests."

  - "Unit, integration, and accessibility tests pass."

Avoid criteria such as:

• Make it intuitive

• Make it fast

• Use best practices

• Improve the user experience

• Make it production ready

Those phrases may be directionally useful, but they are not independently testable.

A better acceptance criterion replaces interpretation with evidence.

Instead of:

- "The page should be fast."

Use:

- "The page must load within two seconds at the 95th percentile under the expected production workload."

That can be validated.

Constraints Control Scope, Risk, and Cost

Constraints are one of the most valuable parts of the intent file.

They prevent the system from solving a larger problem than the business requested.

constraints:

  scope:

    - "Do not modify the order-processing services."

    - "Do not introduce a new database."

    - "Reuse the existing support portal."

  security:

    - "Use the existing role-based access-control service."

    - "Do not expose payment information."

    - "Mask customer personal data in logs."

  architecture:

    - "Use existing API gateway patterns."

    - "Reuse the shared React component library."

    - "Follow current repository conventions."

  performance:

    - "95th-percentile response time must remain below two seconds."

  cost:

    max_estimated_monthly_infrastructure_cost: 250

    max_agent_execution_cost: 20

  max_iterations: 5

  max_retries_per_step: 2

  max_tool_calls: 20

  max_execution_time: "30 minutes"

  confidence_threshold: 0.85

These constraints are not simply technical preferences.

They are economic controls.

Every unnecessary planning cycle costs tokens.

Every repeated search costs tokens.

Every redundant tool call costs tokens.

Every attempt to redesign the architecture creates more work and more risk.

A bounded intent forces the system to operate inside the value of the task.

This Is Where Intent Monetization Begins

The monetization of an intent file does not come from the file itself.

It comes from improving the ratio between business value and delivery cost.

A strong intent file increases value in several ways.

It reduces clarification cycles

The system does not have to repeatedly ask what the user meant.

It reduces speculative implementation

The agent does not invent requirements that were never requested.

It reduces unnecessary tool calls

The system knows where to work, what evidence is required, and which systems matter.

It reduces rework

Acceptance criteria and validation rules expose errors before the work reaches human review.

It increases reuse

The same harness can execute many different intents without being rebuilt.

It creates measurable delivery data

Organizations can compare:

• Intent quality

• Execution cost

• Number of iterations

• Tool usage

• Validation failures

• Human interventions

• Cycle time

• Business outcome achieved

That is how intent becomes monetizable.

The organization can begin answering questions such as:

• Which types of intents generate the highest value?

• Which repositories require the most retries?

• Which acceptance criteria routinely fail?

• Which teams create the most executable intents?

• Which tool calls drive cost without improving results?

• Where should the harness become more deterministic?

• Which work should never be agentic at all?

A mature Intent-Driven Engineering organization does not merely measure developer productivity.

It measures the economics of turning intent into validated delivery.

Validation Must Be Defined Before Execution

Validation should not be added after the implementation is finished.

It should be part of the intent from the beginning.

validation:

  required_tests:

    - "Unit tests"

    - "API integration tests"

    - "Accessibility tests"

    - "Performance test"

  required_checks:

    - "Lint passes"

    - "Build succeeds"

    - "No critical security vulnerabilities"

    - "All acceptance criteria mapped to evidence"

  validator:

    type: "independent"

    output: "structured_pass_fail_report"

  failure_conditions:

    - "Any critical security issue"

    - "Any acceptance criterion without evidence"

    - "Performance threshold exceeded"

    - "Unauthorized data exposed"

The validator should compare the implementation against the intent.

It should not simply review whether the output “looks good.”

That distinction matters.

The agent that created the work should not be the only authority deciding whether the work is correct.

The orchestrator owns the loop.

The reasoner proposes.

The worker executes.

The validator checks.

The stop test decides.

Require Evidence, Not Confidence

Confidence is useful, but confidence is not proof.

The intent file should specify the evidence required for completion.

evidence_required:

  - implementation_summary

  - changed_files

  - acceptance_criteria_traceability

  - unit_test_results

  - integration_test_results

  - security_scan_results

  - performance_results

  - validation_report

  - remaining_risks

This creates a delivery package that humans can review efficiently.

Instead of receiving a message saying:

The feature has been completed successfully.

The reviewer receives:

• What changed

• Why it changed

• Which criteria were satisfied

• Which tests ran

• Which tests passed

• What evidence supports completion

• What risks remain

• Whether human judgment is still required

That is controlled engineering.

Stop Conditions Make the Intent Safe

Every intent should define what happens at the end of the loop.

stop_conditions:

  complete_when:

    - "All acceptance criteria pass."

    - "All required tests pass."

    - "All required evidence is present."

    - "No blocking security or architecture issues remain."

    - "Confidence threshold is met."

  retry_when:

    - "A recoverable test failure occurs."

    - "Required evidence is incomplete."

    - "A tool call returns a transient error."

  human_review_when:

    - "Maximum iterations are reached."

    - "Maximum execution cost is reached."

    - "Requirements conflict."

    - "A production-data decision is required."

    - "Confidence remains below 0.85."

  fail_when:

    - "A critical security issue is detected."

    - "A required dependency is unavailable."

    - "The requested change violates architecture policy."

    - "The requested outcome cannot be achieved within the defined constraints."

A maximum iteration count is not a sign that the system failed.

It is a safety rail.

A good harness does not wander until it consumes the budget.

It stops, packages the evidence, explains the blocker, and hands the decision to a human.

Define the Delivery Expectation

The intent should also state what the final delivery should look like.

delivery:

  output_format:

    - "Implementation summary"

    - "Pull request"

    - "Validation report"

    - "Remaining risks"

  target_repository:

    "customer-support-portal"

  branch_strategy:

    "feature/failed-order-investigation"

  pull_request_required:

    true

This prevents a common failure mode: the system solves the problem but delivers the result in the wrong form.

The difference between working code in a temporary environment and a reviewable pull request is significant.

Delivery expectations belong inside the intent.

A Complete Example

Here is what a strong enterprise intent file can look like.

intent:

  id: "INT-ORD-1042"

  title: "Failed Order Investigation"

  business_outcome:

    "Reduce the average time required for support agents to diagnose failed customer orders from 45 minutes to less than 15 minutes."

  goal:

    "Create a React-based investigation page that displays order status, downstream failures, retry history, and the most likely failure cause."

context:

  current_state:

    - "Support agents currently inspect four separate systems."

    - "Failure information is distributed across APIs, Kafka events, and logs."

  users:

    - "Tier 1 support agents"

    - "Operations managers"

  systems:

    - "React support portal"

    - "Order Management API"

    - "Kafka"

    - "OpenTelemetry log platform"

  dependencies:

    - "Existing authentication service"

    - "Shared React component library"

    - "Order API schema"

acceptance_criteria:

  - "A user can search by order ID."

  - "The page displays the current order status."

  - "The page displays downstream service failures."

  - "Retry attempts are shown chronologically."

  - "The most likely failure cause is displayed."

  - "Unauthorized users cannot access order information."

  - "The page loads within two seconds at the 95th percentile."

  - "All required tests pass."

constraints:

  scope:

    - "Do not modify order-processing services."

    - "Do not introduce a new database."

    - "Reuse the existing support portal."

  security:

    - "Use existing role-based access control."

    - "Do not expose payment information."

    - "Mask personal data in logs."

  architecture:

    - "Follow current repository patterns."

    - "Reuse shared components."

    - "Use existing API gateway conventions."

  performance:

    - "95th-percentile page load below two seconds."

  cost:

    max_agent_execution_cost: 20

    max_estimated_monthly_infrastructure_cost: 250

  max_iterations: 5

  max_retries_per_step: 2

  max_tool_calls: 20

  max_execution_time: "30 minutes"

  confidence_threshold: 0.85

validation:

  required_tests:

    - "Unit tests"

    - "API integration tests"

    - "Accessibility tests"

    - "Performance test"

  required_checks:

    - "Lint passes"

    - "Build succeeds"

    - "No critical security findings"

    - "Every acceptance criterion has supporting evidence"

  validator:

    type: "independent"

    output: "structured_pass_fail_report"

  failure_conditions:

    - "Critical security issue"

    - "Missing evidence"

    - "Performance threshold exceeded"

    - "Unauthorized data exposure"

evidence_required:

  - implementation_summary

  - changed_files

  - acceptance_criteria_traceability

  - test_results

  - security_scan_results

  - performance_results

  - validation_report

  - remaining_risks

stop_conditions:

  complete_when:

    - "All acceptance criteria pass."

    - "All tests pass."

    - "All required evidence is present."

    - "No blocking issues remain."

    - "Confidence threshold is met."

  retry_when:

    - "A recoverable validation failure occurs."

    - "Evidence is incomplete."

    - "A transient tool failure occurs."

  human_review_when:

    - "Maximum iterations are reached."

    - "Maximum cost is reached."

    - "Requirements conflict."

    - "Confidence remains below threshold."

  fail_when:

    - "A critical security issue is detected."

    - "A required dependency is unavailable."

    - "The request violates architecture policy."

delivery:

  output_format:

    - "Implementation summary"

    - "Pull request"

    - "Validation report"

    - "Remaining risks"

  target_repository:

    "customer-support-portal"

  branch_strategy:

    "feature/failed-order-investigation"

  pull_request_required:

    true

This is not merely a request.

It is a controlled delivery contract.

Keep the Intent Proportional to the Work

Not every task needs the full enterprise format.

A small task may require only:

goal:

  "Add a password visibility toggle to the login page."

acceptance_criteria:

  - "The user can show and hide the password."

  - "The control is keyboard accessible."

  - "Existing login tests continue to pass."

constraints:

  max_iterations: 3

  max_tool_calls: 8

evidence_required:

  - implementation_summary

  - changed_files

  - test_results

stop_conditions:

  complete_when:

    - "Acceptance criteria pass."

    - "Tests pass."

  human_review_when:

    - "Maximum iterations are reached."

The principle is not to create the longest possible intent.

The principle is to create the smallest intent that removes dangerous ambiguity.

The Best Intent Is Not the Most Detailed

Detail is valuable only when it improves execution.

A hundred-page specification can still produce poor results if it does not clearly define:

• The desired outcome

• The acceptance criteria

• The constraints

• The evidence

• The stop conditions

A one-page intent can outperform it when those elements are explicit.

The goal is not documentation volume.

The goal is executable clarity.

Intent Quality Becomes a Competitive Advantage

As enterprises deploy more agents, the differentiator will not be access to the model.

Most organizations will have access to similar models, tools, repositories, and cloud platforms.

The advantage will come from how effectively they convert business intent into controlled execution.

Organizations with strong intent files will:

• Spend fewer tokens

• Use fewer tool calls

• Reduce rework

• Accelerate validation

• Improve auditability

• Increase reuse

• Reduce operational risk

• Deliver measurable business outcomes faster

Organizations with weak intent files will blame the model, rebuild the harness, add more agents, and continue paying for ambiguity.

The answer is usually not another agent.

It is a better intent.

The Rule Going Forward

Every intent file should answer four questions:

1. What business outcome are we trying to achieve?

2. How will the system prove that it achieved it?

3. What boundaries control scope, risk, time, and cost?

4. When must the system stop, retry, escalate, or fail safely?

That is how intent becomes executable.

That is how agentic delivery becomes governable.

That is how cost becomes controllable.

That is how the enterprise turns AI from an experiment into an operating model.

The harness executes the work.

The intent file determines whether the work is worth executing.

:::