Appendix A: How to Write the Perfect Intent File (Developer Playbook)

Appendix A: How to Write the Perfect Intent File (Developer Playbook)

1. What “Perfect” Means (For a Developer)

A perfect intent file is not:

• clean YAML

• nicely structured

• “complete looking”

A perfect intent file is:

One that produces correct, production-ready output in a single run

If you still need to:

• clarify

• re-prompt

• fix assumptions

👉 your intent file is incomplete

2. The Real Workflow (Step-by-Step)

This is the part most docs skip.

Step 1 — Start with Conversation (NOT writing)

Before writing anything, you must extract intent.

Use this pattern:

Ask me questions to fully define:

- goal

- inputs

- outputs

- constraints

- failure handling

- deployment

Do NOT generate code yet.

Let the AI interrogate you.

👉 This is where 80% of correctness comes from

Step 2 — Capture Raw Answers (Don’t Structure Yet)

Example (raw):

- needs to take webhook from Nautobot

- push to Salesforce

- must not lose data

- retry failures

- AWS deployment

- Java Spring Boot

This is messy — good.

Step 3 — Convert to Structured Intent

Now you transform into this:

intent:

  goal: >

    Process webhook events from Nautobot and reliably synchronize

    location data to Salesforce without data loss.

  inputs:

    - webhook_event: JSON payload from Nautobot

  outputs:

    - salesforce_location: updated object

    - status: success | failure

  constraints:

    - language: Java

    - framework: Spring Boot

    - deployment: AWS Fargate

    - reliability: no data loss

  architecture:

    pattern: event-driven

    components:

      - REST Controller

      - Transformer

      - Orchestrator

      - Kafka

      - Salesforce Adapter

  behavior:

    - validate payload

    - transform to canonical model

    - retry failures (3x)

    - send to DLQ after retries

    - log all transactions

  output:

    - full Spring Boot project

    - Dockerfile

    - README

3. The Developer Rules (Non-Negotiable)

Rule 1 — Every ambiguity becomes a bug

Bad:

process data and send to Salesforce

Good:

transform webhook payload to canonical model before sending to Salesforce

Rule 2 — Constraints drive everything

If you don’t specify:

• language

• framework

• deployment

👉 you will get inconsistent results across runs and engineers

Rule 3 — Behavior is where production happens

Most devs stop at architecture.

That’s wrong.

This is what makes it real:

behavior:

  - retry failures (3x exponential backoff)

  - deduplicate events

  - send failures to DLQ

Rule 4 — Output must be explicit

Bad:

generate code

Good:

output:

  - full project structure

  - production-ready code

  - Dockerfile

  - environment variables

  - README with setup steps

4. How to Run This in Practice (Claude / GPT)

Pattern to use:

You are a senior architect using Intent-Driven Engineering.

Take the following intent file and generate a complete implementation.

Rules:

- Respect all constraints

- Generate production-ready code

- Include project structure

- Include setup instructions

- Do not simplify

Intent:

<PASTE INTENT FILE>

5. Iteration Pattern (When It’s Not Perfect)

If output is off, don’t rewrite everything.

Fix at the right layer:

Problem

Fix

Wrong tech

constraints

Missing component

architecture

Fails in edge cases

behavior

Incomplete output

output section

👉 Never “re-prompt randomly”

Always fix the intent layer

6. Advanced Pattern (This is your edge)

Chain intents instead of bloating one

Intent 1 — Base system

• scaffolds full app

Intent 2 — Add feature

Extend existing project:

- add multi-step UI wizard

- persist intent files

- export JSON

Intent 3 — Production hardening

Add:

- observability

- retry tuning

- config management

👉 This is how real systems scale

7. Anti-Patterns (What Devs Will Do Wrong)

❌ Writing like a prompt

build a really good scalable system

❌ Over-engineering

create 12 classes with these names

❌ Missing failure handling

→ works in demo, fails in prod

❌ Mixing conversation + structure

→ breaks determinism

8. The Dev Checklist (Use This Every Time)

Before running, check:

• Goal is outcome-based

• Inputs/outputs are explicit

• Constraints are defined

• Architecture is clear

• Behavior covers failures

• Output is fully specified

If any are missing:

👉 don’t run it yet

9. Final Developer Rule

The quality of your system is capped by the quality of your intent.

Not your coding skill.

Not the AI model.