Appendix A: How to Write the Perfect Intent File

Appendix A: How to Write the Perfect Intent File

A Complete Field Guide for Intent-Driven Engineering Practitioners

Companion to: Intent-Driven Engineering — From Vibe Coding to Deterministic Systems Source references: LearnTeachMaster.org · docs.claude.com · Anthropic Official Documentation

Before We Start: Three Ways to Talk to an AI

This appendix does not just tell you how to write an intent file — it shows you all three approaches in action, with real keystrokes, real AI systems, and real code examples so you can feel the difference yourself.

By the end of this chapter you will have seen:

• The Vibe Way — chaotic, reactive, inconsistent

• The Prompt Way — structured but still brittle

• The Intent Way — deterministic, repeatable, production-grade

Every section maps exactly which AI system to use, how many keystrokes are required, and what the output looks like. The complete intent file template is at the end.

Section 1: The Vibe Way

Vibe coding is how most developers first interact with AI. It feels fast. It produces something. But the output is inconsistent, hard to reproduce, and dangerous in production systems.

As LearnTeachMaster.org defines it: "Without structured intent, AI may generate inconsistent implementations, architectural boundaries may be violated, and systems may drift away from their original goals."

What Vibe Coding Looks Like

The developer fires off whatever is in their head. No structure. No constraints. No architecture defined.

Platform: Claude.ai (browser) or ChatGPT Keystrokes typed: 38 characters

make me a node api for orders

What comes back is a Node.js + Express app with no authentication, no validation, no error handling, no database connection strategy, and no alignment with any architecture your team has made. It works in a demo. It does not belong in production.

Output: A random Express API with in-memory storage, no tests, no observability, no contract. Cannot be promoted to production. Took 38 keystrokes to create a liability.

The Hidden Costs of Vibe Coding

Cost CategoryWhat Actually HappensTime LostHidden assumptionsAI picks a random architecture you did not intend2–8 hrs reworkMissing constraintsNo auth, no DLQ, no observability baked in1–3 days retrofitInconsistent outputRe-run same prompt, get different resultUnpredictableFragile architectureWorks in demo, breaks in load testSprint lostKnowledge trappedOnly the prompter understands what was builtOngoing tech debt

The LearnTeachMaster.org curriculum describes vibe coding as exploration — not execution. The intent system is execution.

Section 2: The Prompt Way

Prompt engineering is a real discipline. Anthropic has published extensive official guidance at docs.claude.com. It is better than vibe coding — but it has a fundamental ceiling. Prompts are reactive. The engineer must invent all the structure themselves.

What Anthropic's Official Docs Say

The official Claude Prompt Engineering Overview (platform.claude.com/docs) states that before writing any prompt you need:

1. A clear definition of the success criteria for your use case

2. Some ways to empirically test against those criteria

3. A first draft prompt you want to improve

The Anthropic documentation describes it this way: "Think of prompt engineering like giving instructions to a brilliant new hire who has zero context on your project. The clearer you are, the better they perform."

This is good advice. But it still puts the burden of clarity entirely on the engineer.

The Six Official Anthropic Prompt Techniques

TechniqueWhat It DoesLimitationProvide clear contextGives Claude background before the taskEngineer must know what context is neededUse positive examplesShow Claude what good output looks likeEngineer must produce examples firstUse negative examplesShow Claude what to avoidEngineer must know failure modes in advanceChain of thoughtAsk Claude to reason step-by-stepStill reactive — engineer asks, AI respondsRequest XML structureGet structured, parseable outputSchema must be designed by the engineerSpecify length/formatControl output size and shapeEngineer must know the right format upfront

Source: Anthropic Prompt Engineering Overview — platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview

Prompt Engineering in Action

Platform: Claude.ai or Claude API Workbench Keystrokes typed: ~420 characters — 11x more than vibe coding, but still incomplete

Create a Node.js REST API using TypeScript. The API should handle order management. Use Express framework. Connect to PostgreSQL. Include authentication using JWT. Add error handling middleware. Follow RESTful conventions. Return JSON responses. Use async/await throughout. Add input validation.

This is dramatically better than vibe coding. But notice what is still missing:

• No deployment target (Lambda? ECS? Fargate?)

• No observability requirements (metrics, traces, logs)

• No event-driven requirements (Kafka? SQS? None?)

• No API specification standard (TMF? OpenAPI? Custom?)

• No team conventions or organizational constraints

• No definition of "done" — what does success look like?

Key Insight: Prompt engineering puts the cognitive burden on the engineer to invent completeness. Intent engineering inverts this: the AI asks the structured questions and the engineer supplies the answers. This is the shift the LearnTeachMaster curriculum describes as moving from "prompt trial and error" to "deterministic outcomes."

Section 3: The Intent Way

Intent-Driven Engineering inverts the model entirely. You do not write a prompt and hope. You declare a high-level goal, the AI system interrogates you with structured questions, your answers become the intent file, and the intent file drives deterministic output.

LearnTeachMaster.org defines it as: "Instead of starting with implementation details, development begins with defining what the system is meant to accomplish and how it should behave."

The Five Stages of Intent Creation

StageActorActionOutput1. Declare IntentHumanState the high-level directional goalA single sentence of intent2. AI InterrogatesAI SystemAsks structured, targeted questionsA question set covering all domains3. Human AnswersHumanShort, precise, targeted answersCompleted answer set4. Compile Intent FileAI SystemAssembles answers into structured artifactThe intent file (single source of truth)5. Deterministic OutputAI SystemGenerates code, infra, docs from intentProduction-grade system scaffold

The Interrogation Phase in Detail

This is where the intelligence happens. The AI does not wait for a perfect prompt — it asks the questions that eliminate ambiguity.

Platform: Claude.ai (conversation mode) Declared intent: "Create a Node.js + TypeScript TMF641 API on Fargate + PostgreSQL + Kafka" Keystrokes for the declaration: 72 characters

The AI then asks structured questions across every domain:

DomainAI AsksHuman AnswersAPI StandardWhat TMF specification version?TMF641 Service Order v4.1DeploymentWhat deployment model? (Lambda / Fargate / container)AWS Fargate — ECS clusterPersistenceWhat persistence layer and schema strategy?PostgreSQL via RDS, Flyway migrationsIntegrationWhat integration patterns? (sync / async / event-driven)Event-driven with Kafka — MSK managedObservabilityWhat observability and alerting requirements?Full stack: Datadog APM + PagerDutyResilienceWhat failure handling requirements?DLQ on all Kafka consumers, retry x3SecurityWhat auth model and secret management?OAuth 2.0 + AWS Secrets ManagerContractsWhat API contract format and versioning?OpenAPI 3.1, semantic versioningTestingWhat test coverage requirements?Unit 80%+, integration tests requiredTeamWhat team conventions and existing tooling?Terraform for infra, GitHub Actions CI

Total keystrokes for all answers: ~380 characters — similar to a prompt, but covering 10 structured domains instead of guessing 2–3.

Section 4: Anatomy of a Perfect Intent File

The intent file is the compiled artifact produced from the interrogation. It is not a prompt. It is not documentation. It is the single source of truth that drives code generation, infrastructure provisioning, and architectural decisions.

The Seven Required Sections

SectionWhat It ContainsWhy It's RequiredINTENTOne-sentence system purpose statementAnchors every decision to the original goalSYSTEMRuntime, language, framework, platform stackEliminates technology ambiguityARCHITECTUREPatterns, service boundaries, deployment modelPrevents architectural driftDATAPersistence strategy, schema approach, migration toolDefines data contractINTEGRATIONEvent patterns, messaging, external APIsSpecifies connectivity contractCONSTRAINTSSecurity, auth, compliance, limitsHard requirements — never negotiableQUALITYObservability, testing, resilience, DLQ rulesDefines "done" — what production-ready means

A Complete Intent File — Full Example

This is a production-grade intent file for the TMF641 Service Order API used in LearnTeachMaster.org training. This is the exact format Claude Code uses to generate a working system scaffold.

# INTENT FILE — TMF641 Service Order API # LearnTeachMaster.org | Intent-Driven Engineering v1.0 # Generated: [date] | Author: [engineer] | Version: 1.0.0 ## SECTION 1: INTENT purpose: > Implement a production-grade TMF641 Service Order Management API compliant with TM Forum standards, deployed on AWS Fargate, integrated with Kafka for async event processing, and built to support organizational-scale reuse across product domains. ## SECTION 2: SYSTEM runtime: Node.js 20 LTS language: TypeScript 5.x (strict mode) framework: Express 4.x api_standard: TMF641 Service Order v4.1 api_contract: OpenAPI 3.1 api_versioning: semantic (v1, v2 path prefix) package_manager: npm with lockfile ## SECTION 3: ARCHITECTURE pattern: Layered — Controller / Service / Repository / Domain deployment: AWS ECS Fargate (containerized) container: Docker (multi-stage build) iac: Terraform (modules, remote state in S3) ci_cd: GitHub Actions (build → test → push → deploy) port: 3000 health_check: GET /health — liveness + readiness ## SECTION 4: DATA database: PostgreSQL 15 via AWS RDS orm: Prisma (schema-first) migrations: Flyway (version-controlled SQL) connection_pool: PgBouncer (max 20 connections) schema_strategy: domain-aligned, snake_case columns ## SECTION 5: INTEGRATION messaging: Apache Kafka via AWS MSK pattern: event-driven (produce on state change) events: - serviceOrder.created - serviceOrder.updated - serviceOrder.completed - serviceOrder.failed consumer_group: service-order-consumer-group dlq: enabled on all consumers (retry x3 then DLQ) ## SECTION 6: CONSTRAINTS auth: OAuth 2.0 (Bearer token, JWT validation) secrets: AWS Secrets Manager (no hardcoded credentials) logging: structured JSON (no PII in logs) rate_limiting: 100 req/min per client_id cors: allowlist-only (no wildcard origins in prod) input_validation: zod schemas on all endpoints error_format: RFC 7807 Problem Details ## SECTION 7: QUALITY observability: Datadog APM (traces, metrics, logs) alerting: PagerDuty (P1 on error rate > 1%) unit_coverage: 80% minimum (Jest) integration_tests: required (Supertest) contract_tests: Pact (consumer-driven) load_test: k6 (target 500 req/s before prod) sla: 99.9% uptime, p99 < 200ms

Why this works: An AI system reading this intent file has zero ambiguity. Every architectural decision is explicit. Every constraint is declared. Every quality gate is defined. Claude Code can now generate a complete, working project scaffold without asking a single follow-up question.

Section 5: AI Systems, Tools, and Keystrokes Required

The Complete Tool Map

StageTool / SystemKeystrokesWhat You TypeDeclare IntentClaude.ai or Claude Code50–100One sentence describing the system goalInterrogationClaude.ai (conversation mode)300–500Answers to 8–12 structured AI questionsIntent File AssemblyClaude Code (agentic mode)0AI compiles your answers into the fileCode GenerationClaude Code (CLI)15generate from intent.ymlInfra GenerationClaude Code + Terraform0Driven entirely from intent fileReview & CommitGitHub / Git CLI30–50git add, commit, pushCI/CD TriggerGitHub Actions (automated)0Automatic on push

Keystroke Comparison Across All Three Methods

MethodKeystrokes to StartRework KeystrokesTotal Real CostDeterministic?Vibe Way3810,000+ImmeasurableNoPrompt Way4202,000–5,000HighRarelyIntent Way500 (one-time)50–200MinimalYes — always

Installing and Using Claude Code

Claude Code is the command-line AI system from Anthropic used to execute intent files. It operates in agentic mode — reading the intent file and generating complete project structures.

Prerequisites: Node.js 18+

npm install -g @anthropic-ai/claude-code claude auth login claude --version

Running an intent file:

mkdir tmf641-service-order && cd tmf641-service-order # Place your intent.yml here, then run: claude "Read intent.yml and generate the complete project structure including all source files, Terraform modules, Dockerfile, GitHub Actions workflow, and test suite. Follow every specification exactly."

Claude Code will then:

1. Parse all 7 sections of the intent file

2. Generate src/ directory with TypeScript source

3. Generate terraform/ with ECS + RDS + MSK modules

4. Generate Dockerfile (multi-stage)

5. Generate .github/workflows/deploy.yml

6. Generate tests/ with Jest + Supertest scaffolds

7. Generate prisma/schema.prisma

8. Generate openapi.yml contract

Starting the Interrogation in Claude.ai

For the interrogation phase (Stage 2), open Claude.ai in a new conversation and paste this trigger prompt exactly:

I am using Intent-Driven Engineering. I will declare a system intent. Your job is to interrogate me with structured questions across all domains: runtime, architecture, data, integration, constraints, and quality. Ask one domain at a time. I will answer each set. When complete, compile my answers into a properly formatted intent file. My intent: Create a Node.js + TypeScript TMF641 Service Order API deployed on AWS Fargate with PostgreSQL and Kafka.

Keystrokes: ~450 characters — the only prompt you need to write to get a complete intent file.

Source: docs.claude.com — Anthropic's prompt engineering guidance recommends using "XML tags to structure complex inputs" and "request specific output formats." The intent file trigger prompt above applies both principles at once.

Section 6: Code Examples — What the Intent File Generates

Generated Express Router — TMF641 Service Order

Claude Code generates this from SECTION 2 (system) + SECTION 6 (constraints) of the intent file:

// src/routes/serviceOrder.routes.ts // AUTO-GENERATED from intent.yml — do not edit by hand // TMF641 Service Order API v4.1 import { Router } from 'express'; import { ServiceOrderController } from '../controllers/serviceOrder.controller'; import { authenticate } from '../middleware/auth.middleware'; import { validate } from '../middleware/validation.middleware'; import { serviceOrderSchema } from '../schemas/serviceOrder.schema'; import { rateLimiter } from '../middleware/rateLimiter.middleware'; const router = Router(); const controller = new ServiceOrderController(); // TMF641 compliant routes — auth + validation + rate limit on all router.get('/serviceOrder', authenticate, rateLimiter, controller.list); router.get('/serviceOrder/:id', authenticate, rateLimiter, controller.get); router.post('/serviceOrder', authenticate, rateLimiter, validate(serviceOrderSchema.create), controller.create); router.patch('/serviceOrder/:id', authenticate, rateLimiter, validate(serviceOrderSchema.update), controller.update); router.delete('/serviceOrder/:id', authenticate, rateLimiter, controller.delete); export default router;

Generated Kafka Producer — Driven by Intent SECTION 5

No Kafka-specific instructions needed in any prompt — fully driven by the integration section of the intent file:

// src/events/serviceOrder.producer.ts // Intent: event-driven with Kafka MSK, DLQ enabled, retry x3 import { Kafka, Producer, CompressionTypes } from 'kafkajs'; import { ServiceOrderEvent } from '../types/events'; import { logger } from '../utils/logger'; export class ServiceOrderProducer { private producer: Producer; constructor(private kafka: Kafka) { this.producer = kafka.producer({ retry: { retries: 3 }, // intent.yml: retry x3 then DLQ compression: CompressionTypes.GZIP, }); } async emit(event: ServiceOrderEvent): Promise<void> { const topic = `serviceOrder.${event.type}`; try { await this.producer.send({ topic, messages: [{ key: event.id, value: JSON.stringify(event), headers: { correlationId: event.correlationId } }] }); logger.info({ topic, eventId: event.id }, 'Event emitted'); } catch (err) { logger.error({ topic, err }, 'Producer error — routed to DLQ'); throw err; } } }

Generated Terraform — ECS Fargate from Intent SECTION 3

# terraform/modules/ecs/main.tf # Generated from intent.yml SECTION 3: deployment = AWS ECS Fargate resource "aws_ecs_cluster" "service_order" { name = "${var.project_name}-cluster" setting { name = "containerInsights" value = "enabled" # intent: full observability (Datadog) } } resource "aws_ecs_task_definition" "service_order_api" { family = "${var.project_name}-task" requires_compatibilities = ["FARGATE"] network_mode = "awsvpc" cpu = var.cpu memory = var.memory execution_role_arn = aws_iam_role.ecs_execution.arn task_role_arn = aws_iam_role.ecs_task.arn container_definitions = jsonencode([{ name = "service-order-api" image = "${var.ecr_repository_url}:${var.image_tag}" portMappings = [{ containerPort = 3000, protocol = "tcp" }] # Secrets from AWS Secrets Manager — intent: no hardcoded credentials secrets = [ { name = "DATABASE_URL", valueFrom = var.db_secret_arn }, { name = "KAFKA_BROKERS", valueFrom = var.kafka_secret_arn }, ] logConfiguration = { logDriver = "awslogs" options = { "awslogs-group" = "/ecs/${var.project_name}" "awslogs-region" = var.aws_region } } }]) }

Section 7: The Ten Rules for Writing a Perfect Intent File

These rules are distilled from the LearnTeachMaster.org curriculum, Anthropic's official prompt engineering documentation, and production experience across engineering teams.

RulePrincipleViolationCorrect1Declare, do not explain"I want to build something that handles orders maybe using Node""purpose: TMF641-compliant Service Order API on Fargate"2Every section must be presentOmitting CONSTRAINTS sectionAll 7 sections always required — no exceptions3Be specific on technology versions"use postgres""database: PostgreSQL 15 via AWS RDS"4Name the deployment model"deploy to AWS""deployment: AWS ECS Fargate (containerized)"5Specify the event contract"uses kafka""events: serviceOrder.created, serviceOrder.updated, serviceOrder.failed"6Define failure handling explicitly"handle errors""dlq: enabled on all consumers (retry x3 then DLQ)"7Quantify quality gates"good test coverage""unit_coverage: 80% minimum (Jest) — fails CI if below"8Name the auth model exactly"needs security""auth: OAuth 2.0 Bearer token, JWT, validated on every request"9Reference the API standard"TMF API""api_standard: TMF641 Service Order v4.1 — TMForumOpen_API"10Version the intent file itselfNo version or date"version: 1.0.0 | date: [date] | author: [name]"

The "Done" Test for Your Intent File

Before submitting an intent file to Claude Code, run this self-check. If any answer is "no," the file is not complete.

• Can someone who was not in the room understand every decision from this file alone?

• Does it specify the exact deployment target, not just the cloud provider?

• Does it name the auth model, not just say "secured"?

• Does it define what happens when something fails (DLQ, retry, circuit breaker)?

• Does it give a quantified quality bar (test %, SLA, latency target)?

• Does it reference a specific API standard or contract format?

• Does it state the IaC tooling (Terraform, CDK, Pulumi)?

• Does it have a version number and an author?

Section 8: Side-by-Side — Vibe vs Prompt vs Intent

DimensionVibe WayPrompt WayIntent WayStarting artifactA feelingA text paragraphA structured YAML fileKeystrokes to start38420500 (covers everything)Who defines structure?Engineer (implicitly)Engineer (explicitly)AI system (via interrogation)Architecture decisionsImplicit / randomPartially explicitFully explicit and versionedReproducible output?NeverRarelyAlwaysTeam scalabilityBreaks at 2 peopleStruggles at 5 peopleScales to entire organizationProduction-ready?Never directlyWith significant reworkYes — by designAI system usedAny chat AIClaude.ai / API WorkbenchClaude.ai + Claude CodePrimary reference(none)Anthropic Prompt Engineering DocsLearnTeachMaster.org + Claude DocsOrganizational valueIndividual skillIndividual + some team valuePlatform capability at org scale

Section 9: The Perfect Intent File Template

Copy this template. Fill every field. Leave nothing blank. Version it every time you change it.

# INTENT FILE # Project: ___________________ # Version: 1.0.0 | Date: ___________ | Author: ___________ ## SECTION 1: INTENT purpose: > [One to three sentences. What system. What standard. What outcome.] ## SECTION 2: SYSTEM runtime: # e.g. Node.js 20 LTS language: # e.g. TypeScript 5.x strict mode framework: # e.g. Express 4.x api_standard: # e.g. TMF641 v4.1 api_contract: # e.g. OpenAPI 3.1 ## SECTION 3: ARCHITECTURE pattern: # e.g. Layered — Controller/Service/Repository deployment: # e.g. AWS ECS Fargate container: # e.g. Docker multi-stage iac: # e.g. Terraform with remote state ci_cd: # e.g. GitHub Actions ## SECTION 4: DATA database: # e.g. PostgreSQL 15 via RDS orm: # e.g. Prisma (schema-first) migrations: # e.g. Flyway ## SECTION 5: INTEGRATION messaging: # e.g. Apache Kafka via AWS MSK pattern: # e.g. event-driven, async events: # List all domain events dlq: # e.g. enabled, retry x3 ## SECTION 6: CONSTRAINTS auth: # e.g. OAuth 2.0 Bearer + JWT secrets: # e.g. AWS Secrets Manager logging: # e.g. structured JSON, no PII rate_limiting: # e.g. 100 req/min per client_id input_validation: # e.g. zod on all endpoints ## SECTION 7: QUALITY observability: # e.g. Datadog APM alerting: # e.g. PagerDuty P1 on error > 1% unit_coverage: # e.g. 80% minimum (Jest) integration_tests: # e.g. required (Supertest) sla: # e.g. 99.9%, p99 < 200ms

Closing: The Discipline Shift

The intent file is not documentation that follows the code. It is the architecture that precedes the code. It is the reason the output is deterministic.

As the Intent-Driven Engineering presentation states: "The teams that don't adopt this will stay stuck refining prompts."The intent file is the artifact that separates prompt engineers from intent architects.

Write the intent. Feed the machine. Build the system.

LearnTeachMaster.org — Intent-Driven Engineering Curriculum — Free & Open Learning Platform Anthropic Claude Documentation — docs.claude.com — platform.claude.com/docs