Appendix A: How to Write the Perfect Intent File

Appendix A: How to Write the Perfect Intent File

(Intent-Driven Engineering — Practical Standard)

1. What Is an Intent File?

An intent file is a structured, declarative specification of what must be built — not how to build it.

It replaces:

• vague prompts

• scattered requirements

• tribal knowledge

With:

• clear outcomes

• explicit constraints

• machine-interpretable structure

Think of it as:

A contract between human intent and machine execution.

2. The Core Principle (Critical)

Most teams get this backwards.

❌ Prompting model:

Human asks → AI guesses → Human fixes → Repeat

✅ Intent-driven model:

AI asks → Human answers → System constructs → Output is correct first time

That inversion is what makes intent files powerful.

3. The Anatomy of a Perfect Intent File

A high-quality intent file always contains six layers:

1. Goal (The Why)

Clear, outcome-based objective.

goal: >

  Build a Spring Boot REST API that receives webhook events from Nautobot

  and synchronizes location data into Salesforce with full reliability.

Rules:

• Must be measurable

• Must describe end state

• No technical fluff

2. Inputs & Outputs (The Contract)

Define what enters and exits the system.

inputs:

  - webhook_event: JSON payload from Nautobot

outputs:

  - salesforce_location: Created or updated location object

  - status: success | failure

Rules:

• Treat this like an API contract

• Be explicit about formats

3. Constraints (Non-Negotiables)

These define boundaries the system must obey.

constraints:

  - language: Java

  - framework: Spring Boot

  - reliability: must support retries and DLQ

  - deployment: AWS (Fargate)

Rules:

• No ambiguity

• No “optional unless”

• These drive architecture decisions

4. Architecture Decisions (The Shape)

Translate intent into system design.

architecture:

  pattern: event-driven

  components:

    - inbound_adapter: REST controller

    - core:

        - transformer

        - orchestrator

        - validator

    - outbound_adapter: Salesforce client

    - messaging: Kafka (retry + DLQ)

Rules:

• Define components, not code

• Must align with constraints

• Avoid over-design

5. Behavioral Rules (The Intelligence)

How the system behaves under real conditions.

behavior:

  - validate incoming payload

  - deduplicate events

  - retry failures up to 3 times

  - send failed messages to DLQ

  - log all transactions

Rules:

• This is where production readiness lives

• Think failure first, not happy path

6. Output Expectations (The Deliverable)

What the system must generate.

output:

  - complete project structure

  - production-ready code

  - README with setup instructions

  - environment variables defined

Rules:

• Be explicit about artifacts

• No “basic example” unless stated

4. The Golden Format (Reusable Template)

intent:

  goal: >

    [Clear outcome]

  inputs:

    - [input_name]: [description]

  outputs:

    - [output_name]: [description]

  constraints:

    - [constraint]

  architecture:

    pattern: [pattern]

    components:

      - [component]

  behavior:

    - [rule]

  output:

    - [deliverable]

5. Example (Production-Grade)

intent:

  goal: >

    Build a fault-tolerant integration service that processes Nautobot

    webhook events and synchronizes location data to Salesforce.

  inputs:

    - webhook_event: JSON payload

  outputs:

    - salesforce_location: Updated object

    - status: success | failure

  constraints:

    - language: Java

    - framework: Spring Boot

    - messaging: Kafka

    - deployment: AWS Fargate

  architecture:

    pattern: event-driven

    components:

      - REST Controller

      - Transformer

      - Orchestrator

      - Salesforce Adapter

      - Kafka Producer/Consumer

  behavior:

    - validate payload

    - transform to canonical model

    - retry failures (3x exponential backoff)

    - route failures to DLQ

    - log and trace all flows

  output:

    - full Spring Boot project

    - Dockerfile

    - deployment config

    - README

6. What Makes an Intent File “Perfect”

A perfect intent file is:

• Complete → no missing assumptions

• Deterministic → same input = same output

• Constraint-driven → architecture emerges automatically

• Failure-aware → handles real-world scenarios

• Executable → can be run directly by an AI system

7. Common Mistakes (And Why Teams Fail)

❌ Too vague

“Build a microservice for orders”

❌ Too prescriptive

“Create 3 classes, name them X, use this method…”

❌ Missing constraints

Leads to inconsistent outputs across teams

❌ No failure handling

Works in demo, fails in production

❌ Prompt leakage

Mixing conversational fluff into structured intent

8. The Shift (Why This Matters)

This is bigger than formatting.

You are moving from:

• Prompting → Specifying

• Guessing → Defining

• Iteration → Precision

• AI as assistant → AI as execution engine

9. Final Rule

If your intent file still requires explanation…

it’s not finished.