Intent Capture — Drafting intent.md Before Building

Intent capture is the practice of recording a problem statement and its constraints in the originator’s own words before any architecture, technical plan, or application code is generated. Storing this record as a version-controlled intent.md file creates an immutable audit trail and gives downstream AI agents the context they need to avoid solving the wrong problem.

Scorecard question: How do you capture problem statements before any code or plan is written (intent.md)? Max‑score answer (3 pts): Standardized intent.md template in repo; product owner reviews and commits before Stage 2 Design.

Why this matters in 2026

When developers skip intent capture, AI coding tools immediately produce code for the wrong requirements. Traditional requirements gathering takes weeks of committee meetings and ticketing handoffs, degrading nuance at each step. In an AI-native SDLC, the originator brainstorms with an AI assistant in natural language, producing a structured intent.md proto-spec in hours rather than weeks.

The committed intent.md establishes the single source of truth for product owners, engineers, and AI agents. It answers what is wanted, why it matters, who is affected, and what constraints exist—before an implementation plan consumes context or introduces code churn.

What “max score” actually looks like

A max-score Q4 setup exhibits four concrete attributes:

1. Standard template: The repository maintains an agreed template in intent/ (or repository root) with structured sections: Problem, Proposed Outcome, Affected Users/Systems, Constraints, and Open Questions.
2. AI-assisted elicitation: The originator uses Claude Code, Cursor, or Codex to interview them about the requirements, surface edge cases, and draft the file.
3. Product owner sign-off: The product owner reviews, iterates, and commits intent.md before Stage 2 (Design) begins.
4. Tool-agnostic storage: The markdown file lives in git, making it accessible to any agent harness without copy-pasting from web portals.

Step-by-step implementation

1. Add the intent template to your repository.

   Create intent/TEMPLATE.md at your repository root:

   # Intent: INTENT_TITLE
   Author: AUTHOR_NAME (TEAM). Status: draft.
   
   ## Problem
   WHAT_IS_BROKEN_OR_MISSING
   
   ## Proposed outcome
   WHAT_BETTER_LOOKS_LIKE
   
   ## Affected users and systems
   USERS_AND_SYSTEMS
   
   ## Constraints
   CONSTRAINTS
   
   ## Open questions
   OPEN_QUESTIONS

2. Conduct the elicitation interview.

   Instruct your agent to interview you without generating code or technical designs:

   Claude Code

   I have an idea for FEATURE_NAME. Interview me about the business problem,
   who is affected, what success looks like, and what constraints exist.
   After our discussion, write intent/FEATURE_SLUG.md using intent/TEMPLATE.md.
   Do not write any code or implementation plans.

   Cursor

   Switch to Ask mode (so no source code files are touched) and run:

   Interview me regarding this feature request. Ask clarifying questions one
   by one about users, latency constraints, and out-of-scope items.
   Then output intent/FEATURE_SLUG.md following our template.

   Codex

   Use /plan in the Codex CLI:

   /plan Capture this requirement as intent/FEATURE_SLUG.md. Interview me first.
   Do not modify any application code.

3. Refine and review the drafted intent.

   Check that the agent captured your actual intent and answered open questions. Clarify any misunderstood constraints.

4. Commit the approved artifact.

   Commit intent/FEATURE_SLUG.md to git:

   git add intent/FEATURE_SLUG.md
   git commit -m "docs(intent): capture problem statement for FEATURE_SLUG"

5. Route to the product owner for stage sign-off.

   The product owner approves the file on the branch or pull request. Once accepted, the change moves to Stage 2: Design (spec.md).

Common pitfalls

• Jumping straight to code: Skipping intent.md because a feature feels small. Small features without defined constraints cause expensive rewrites when edge cases appear later.
• Letting engineers write requirements in isolation: The originator (product manager, business user, support engineer) must participate in the elicitation interview to preserve domain nuance.
• Storing intent only in web portals: Writing notes in proprietary web dashboards or Slack threads disconnects the agent from the original context. Keep the markdown file in git.

How to verify you’re there

• An intent/ directory exists in your repository with an established template.
• Every non-trivial pull request links to or derives from an accepted intent.md.
• Time from first conversation to committed intent.md takes hours, not weeks.
• The product owner approves intent.md before any engineering implementation begins.

Further reading

AI-Native SDLC Plan Stage Comprehensive guide to capturing intent as proto-specs in the AI-native lifecycle.

The Artifact Chain Understand how intent.md flows into spec.md, plan.md, and REVIEW.md.

Take the Developer Scorecard Assess your setup across all 25 questions.