Chapter 3: Prompt Documents: Prompts That Survive Sessions

Series: LLM Development Guide

Chapter 3 of 15

Previous: Chapter 2: Planning: Plan Artifacts, Constraints, Definition of Done

Next: Chapter 4: Work Notes: External Memory + Running Log

What you’ll be able to do

You’ll be able to create prompt documents that:

• Encode intent precisely so you don’t re-explain yourself.
• Align to plan phases so scope stays tight.
• Include verification steps and explicit stop points.
• Tell the model how to update work notes and propose commits.

TL;DR

• A prompt doc is an artifact, not a chat message.
• Use one prompt file per phase.
• Always include: role, context, task, constraints, deliverables, verification, session management.
• Put negative constraints in writing (“MUST NOT”).
• Keep prompts copy/pasteable and path-specific.

Table of contents

• Why prompt docs matter
• Anatomy of a good prompt
• A template you can copy
• Verification
• Failure modes

Why prompt docs matter

If you’re doing anything bigger than a one-off snippet, the prompt itself becomes part of the system.

Prompt docs:

• Reduce “prompt drift” across sessions.
• Make handoffs possible.
• Create an audit trail of what was asked.
• Force you to pin down deliverables and done-ness.

Anatomy of a good prompt

At minimum, include these sections:

• Role: what expertise you’re invoking.
• Context: plan path, work-notes path, reference implementation paths.
• Task: what to do now.
• Constraints: what must and must not happen.
• Deliverables: exact files and outputs expected.
• Verification: commands and expected results.
• Session management: how to update work notes.
• Commit discipline: atomic commits, propose messages, wait for approval.

If your prompt is missing verification and stop rules, you’re inviting “looks right” output.

A template you can copy

# Phase <X> - <Phase Name>

## Role
You are a senior software engineer.

## Context
- Plan: plan/<phase>.md
- Work notes: work-notes/<phase>.md
- Reference implementations:
  - <path 1>
  - <path 2>

## Task
Implement the next logical unit for this phase.

## Constraints (follow exactly)
- MUST follow patterns in the reference implementations.
- MUST keep changes scoped to this phase.
- MUST include tests when applicable.
- MUST propose verification commands.
- MUST NOT add new dependencies unless explicitly approved.

## Deliverables
1. <file path> - <what it contains>
2. <file path> - <what it contains>

## Session management
As you work:
- Update work-notes/<phase>.md:
  - Decisions (with rationale)
  - Assumptions
  - Open questions
  - Session log entry
- After each logical unit, pause and show the updated notes section.

## Verification
After implementing the logical unit, run or propose:
- <command>
- Expected: <exit 0 / output contains X>

## Commit discipline
After verification:
1. Summarize what changed and why.
2. Propose a conventional commit message.
3. Wait for approval before continuing.

Refs: work-notes/<phase>.md

Notes:

• Use real paths.
• Put constraints in a dedicated section.
• Repeat the most important constraints near the end.

Verification

You can verify prompt docs are usable by checking two things:

• You can paste the entire file verbatim into a new session.
• A new session produces the same behavior because paths and constraints are explicit.

Concrete checks:

# Prompts exist and are non-empty.
find prompts -type f -name '*.md' -maxdepth 2 -print -exec test -s {} \;

# Prompts mention work-notes paths.
rg -n "work-notes/" prompts

Expected results:

• Each prompt file is non-empty.
• Each prompt references a work-notes file.

Failure modes

• Prompts that say “use the config file” without a path.
• Constraints buried in prose instead of a dedicated section.
• Prompts that do not mention verification.
• Prompts that do not tell the model to stop after a logical unit.

Continue -> Chapter 4: Work Notes: External Memory + Running Log