AI PM Skills
Back to library

AI Pair-Programming Spec Format

Engineers using AI coding assistants (Cursor, GitHub Copilot, Claude, Windsurf) get better code when the input is precise. When a PM writes a spec that's also a well-structured AI prompt, the engineer can paste it directly and get a first draft that's 70–80% right.

Context

What an AI coding assistant needs from a spec:
  • One-sentence task summary (scoped, not aspirational)
  • Exact input/output definitions
  • Explicit acceptance criteria (testable, not descriptive)
  • Tech constraints (stack, libraries, patterns)
  • Edge cases (the AI won't invent them — you must provide them)
  • What NOT to build (AI tends to over-engineer unless scoped)

    • Step 1 — Extract the coding task

    CODING TASK SCOPE:

    Deliverable: [One specific code artefact]
    

    Done when: [The engineer can run [test/demo] and observe [result]]
    

    NOT in scope: [Exclusions]

    Step 2 — Write the AI pair-programming spec

    TASK

    [What the engineer is building — verb-first, specific]

    CONTEXT

    [Maximum 3 bullet points — only what the AI needs. Not history, not rationale.]

    INPUT/OUTPUT SPECIFICATION

    Input: [Exact schema]

    Output / Rendered state: [Exact description]
    

    State (if applicable): [What state is managed]

    ACCEPTANCE CRITERIA

    AC-1: GIVEN [state] WHEN [action] THEN [observable result]

    AC-2: GIVEN [state] WHEN [action] THEN [observable result]

    TECHNICAL CONSTRAINTS

  • Framework/language
  • Styling approach
  • State management
  • Libraries allowed / NOT allowed
  • Performance constraints

    • EDGE CASES

    [List every edge case. If you don't list it, the AI won't handle it.]

    DO NOT BUILD

    [Explicit exclusions to limit AI over-engineering]

    EXAMPLE

    [One example of input and expected output — the single biggest quality lever]

    Step 3 — Add engineer handoff notes

    Human-readable note: non-obvious context, most important AC, where to find the existing pattern.

    Step 4 — Version and maintain

  • v1.0 — Initial spec (before engineering starts)
  • v1.x — Minor updates: clarifications, edge cases
  • v2.0 — Major changes: new ACs, changed I/O schema
  • Do not update after engineer has started without notification

    • Quality check before delivering

    Task is one sentence and scoped to one deliverable
    Input/output schema is exact — no "something like"
    Every AC uses GIVEN/WHEN/THEN structure
    Edge cases listed — not "handle edge cases appropriately"
    "Do not build" list included
    At least one example provided
    Suggested next step: Ask the engineer: "Is there anything ambiguous that would make you rewrite this before feeding it to your AI tool?"