PRDs, Specs, and Project Context

Workflow

1. Pick the deliverable.
2. Gather evidence, constraints, and dependencies.
3. Choose the canonical context surface for the target tool or team workflow.
4. Write decisions first.
5. Add acceptance criteria, rollout gates, and source-backed facts. For delivery across more than one session or worker, add a delivery-milestones table.
6. Validate with the relevant checklist before handoff. For source inventories, run python3 scripts/validate_sources.py --scan-only; it excludes archives and symlinks and exits 2 for invalid or empty scan roots and unreadable source files. Inventory success does not verify claims or live URLs.

Quick Reference

Need	Start Here
core PRD	assets/prd/prd-template.md
AI feature PRD	assets/prd/ai-prd-template.md
technical design	assets/spec/tech-spec-template.md
story map or backlog framing	assets/stories/story-mapping-template.md
acceptance criteria	assets/stories/gherkin-example-template.md
delivery milestones (multi-session work)	references/delivery-milestones.md
planning checklist	assets/planning/planning-checklist.md
agentic handoff	assets/planning/agentic-session-template.md
minimal agent context files	assets/minimal-claudemd.md, assets/minimal-agents.md
cross-tool context layering	assets/cross-tool-context.md
stack-specific project context (fill in the blanks, don't write from scratch)	assets/web-app-context.md, assets/api-service-context.md, assets/cli-context.md, assets/library-context.md, assets/react-context.md, assets/nodejs-context.md, assets/python-context.md, assets/go-context.md

Expert Judgment: Why Specs Fail Coding Agents

Before handoff, check whether an agent can satisfy the written requirements while producing behavior the author did not intend.

Ambiguity classes that kill agent runs

Scan for these six ambiguity classes:

1. Referential ambiguity — "the user," "the form," "it" without a fixed noun-phrase, ID, or schema reference. The agent binds to the nearest plausible referent, which is wrong for the case the author had in mind.
2. Silent-default ambiguity — a case is never mentioned (duplicate email, empty list, concurrent edit), so the agent invents a default. That default is rarely audited against the rest of the system.
3. Scope-boundary ambiguity — the spec describes new behavior but never states what must stay unchanged. Agents over-refactor adjacent code or leave a now-dead path that nobody asked them to remove.
4. Temporal/ordering ambiguity — steps are implied but not sequenced ("validate and save" — validate before or after the side effect that can't be undone?).
5. Measurement ambiguity — "fast," "reliable," "secure," "clean" with no unit, threshold, percentile, or test method attached.
6. Authority ambiguity — the spec and the existing code disagree, and nothing states which one wins. The agent picks one; the next agent (or the next session) may pick the other.

Over-specification vs. under-specification: the calibration judgment

• Over-specification dictates implementation (a named library, exact variable names, line-level pseudocode) when only the outcome mattered. Cost: the agent thrashes when the mandated approach doesn't fit the codebase, or ships literally what was written instead of what was meant, and the mismatch isn't visible until review.
• Under-specification gives a title and one paragraph and leaves every non-happy-path implicit. Cost: the agent invents contract details (error shape, retry count, empty-state behavior) that conflict with assumptions already baked into three other call sites — expensive to discover after the fact, not before.

Calibrate detail level to three variables, not to habit or template length:

Blast radius	Reversibility	Agent autonomy	Right level of detail
High (payments, auth, deletion, PII)	Low (hard to roll back)	Any	Spec every edge case explicitly, plus a "must NOT" list
Medium	Medium	Supervised turn-by-turn (human reviews each step)	State decisions + open questions; let the review loop resolve remaining edge cases
Low (prototype, internal tool, behind a flag)	High (cheap to revert)	Any	Outcome + happy path; let the agent propose and flag edge cases
Medium or High	Any	Unattended/autonomous run (no human in the loop until done)	Spec every edge case — there is no reviewer to catch drift mid-run

Acceptance-criteria testability: the judgment beyond the checklist

references/acceptance-criteria-patterns.md covers format and common mistakes. Two judgment calls sit above that checklist:

• The "can't picture the failing test" tell. An AC that reads well but generates zero tests is unfalsifiable. If you cannot describe the specific test that would fail if the behavior were wrong, the AC is not done — rewrite it before handoff, don't ship it and hope the agent infers the missing half.
• The "two competent engineers" tell. The most common single point of spec failure is not a missing AC — it's an AC that is simultaneously true for two materially different implementations. Ask: "could two competent engineers build different things and both honestly claim this AC is satisfied?" If yes, add a discriminating clause (a concrete input/output pair, a specific error code, an explicit ordering) until the answer is no.

Decision and unknown ledger

Keep unresolved product choices out of declarative requirements. For each unknown, record the decision needed, current assumption, owner, deadline or blocking milestone, affected requirements, and what evidence will close it. Mark acceptance criteria that depend on the assumption so an implementer cannot mistake a placeholder for approved behavior.

A repository shows how the system behaves today, not what the business requires. Never infer SLAs, pricing, compliance or retention duties, priorities or target users from code; enter them in the ledger as assumptions to confirm until the user or an authoritative document states them. Block on the user only for unknowns whose wrong guess risks security exposure, data loss, an irreversible migration, contract or API breakage, material cost, or a destructive external action; otherwise record the assumption and proceed.

When implementation shows an acceptance criterion cannot be met, do not drop it or work around it silently. Mark it [revised], state the constraint, adjust its scope or verification method, bump the spec revision, and re-present only the changed criteria. Require explicit confirmation only when the revision changes a blocking decision or weakens a safety or correctness guarantee.

When the decision lands, update the requirement and its acceptance criteria together, then close the ledger entry with the decision source. A PRD is implementation-ready only when every blocking unknown is closed, explicitly deferred outside scope, or represented as a safe runtime/configuration choice with a named default and fallback.

Cross-Tool Context Rules

Treat project memory as layered. The table names each tool's usual surfaces; which files a runtime actually loads, and in what precedence, is a lookup owned by agents-memory.

Tool	Primary Surface	Supporting Surfaces
Claude Code	AGENTS.md when native loading is verified for every contributor; otherwise CLAUDE.md importing AGENTS.md	scoped Claude files, agents, skills, hooks
GitHub Copilot	.github/copilot-instructions.md	additional GitHub instructions, AGENTS.md
Cursor	.cursor/rules/ or root AGENTS.md	root CLAUDE.md, scoped rule files
portable baseline	AGENTS.md	link outward instead of duplicating deep guidance

Whether Claude Code reads AGENTS.md natively, and what takes precedence when both files exist, changes between releases: do not state a support status in a spec. Keep AGENTS.md the single source. Follow the agents-memory lookup step and verify loaded files with /memory for every contributor's version, provider, and configuration. If native loading is verified for all and no CLAUDE.md-family file suppresses it, no bridge is needed. Otherwise import @AGENTS.md at the top of CLAUDE.md (Claude-only content below) or use a CLAUDE.md → AGENTS.md symlink.

Quality Gates

PRD and spec quality

• clear problem statement and evidence
• named owner and success criteria
• measurable acceptance criteria
• metrics with formula, timeframe, and source
• explicit risks, rollout gates, and rollback conditions

AI feature quality

• baseline alternative documented
• eval objective and dataset plan defined before build
• permission, prompt-injection, and data-exfiltration risks covered
• monitoring, incident response, and kill switch specified

Project-context quality

• file paths and commands match the repo
• guidance is routed to the correct tool surface
• no secrets or sensitive data
• shared and tool-specific instructions do not conflict

Navigation

References — Core (load first)

• references/agentic-coding-best-practices.md — agent-aware writing rules; load for any spec or context-file task
• references/requirements-checklists.md — gating checklists for PRD, spec, and context-file quality
• references/acceptance-criteria-patterns.md — Gherkin, EARS, table, and binary-check patterns
• references/security-review-checklist.md — permission, injection, and data-exfiltration gate for AI features
• references/tool-comparison-matrix.md — Claude Code vs Copilot vs Cursor vs Codex capability comparison
• references/code-graph-spec-patterns.md — spec patterns for code-graph and multi-repo context
• references/docs-audit-commands.md — shell commands for auditing existing project documentation
• references/operational-guide.md — quick-start entrypoints and common workflow recipes; load when orientation is needed

References — Spec-driven & prompt craft

• references/spec-driven-dev-landscape.md — GitHub Spec Kit, EARS notation, Kiro, BMAD-METHOD: pipeline shapes and a lookup step; load for spec-gated agentic pipelines
• references/prompt-engineering-patterns.md — task-contract, context-packaging, and output-contract patterns for chat and coding agents; load when authoring prompts embedded in specs, alongside assets/prompting/prompt-playbook.md and assets/prompting/structured-prompt-examples.md
• references/vibe-coding-patterns.md — iterative prompt-agent loops, human/agent role split, and hygiene rules; load for rapid-prototyping or vibe-coding workflows

References — Codebase context extraction

• references/architecture-extraction.md — step-by-step commands to extract entry points, layers, and data flows from an existing codebase; load when writing a tech spec cold, then fill assets/architecture-context.md
• references/convention-mining.md — scripts to detect naming, file, and import conventions from a codebase; load when populating a conventions section, then fill assets/conventions-context.md
• references/tribal-knowledge-recovery.md — git-history and comment-mining techniques to recover undocumented decisions; load when onboarding to a legacy codebase, then fill assets/tribal-knowledge-context.md

Stakeholder & team process (owned by product-management)

• product-management's references/prd-review-facilitation.md — review-type selection, agenda template, feedback labeling, and iteration workflow; load when running a PRD review

• product-management's references/prd-stakeholder-alignment.md — RACI mapping, async/sync review patterns, conflict resolution, and decision-log template; load when managing multi-stakeholder sign-off

• product-management's references/pm-collaboration-guide.md — interview debrief structure and PRD handoff for human PM teams; load for stakeholder-interview-to-PRD tasks

• product-management's references/traditional-prd-writing.md — section-by-section PRD guidance for human teams (Cagan/Wiegers lineage); load when the audience is a PM team, not a coding agent

• data/sources.json

Additional assets

• assets/metrics/agentic-coding-metrics-template.md — load when a spec or pilot must measure coding-assistant impact
• assets/key-files-context.md — load when documenting the files an agent must know in CLAUDE.md or AGENTS.md
• assets/dependencies-context.md — load when documenting external services and integrations in CLAUDE.md or AGENTS.md

Output Format: HTML vs Markdown for Spec Artifacts

Agent-consumed context files (CLAUDE.md, AGENTS.md, .cursor/rules/) stay Markdown. For long, read-once, human-facing artifacts (PRDs over ~100 lines, exploration specs comparing options, interactive specs), consider HTML, keep acceptance criteria extractable as a table or code block, and end interactive specs with an export control ("copy as JSON / prompt / diff"). Decision table, tradeoffs, and recipe: references/html-vs-markdown-output.md.

Boundary: docs-ai-prd vs docs-codebase

• docs-ai-prd owns requirements, specs, acceptance criteria, and context-file strategy
• docs-codebase owns README, runbooks, API reference, changelogs, and canonical documentation quality

If you are deciding what context an agent needs or how a spec should be structured, stay here. If you are rewriting repository docs, use docs-codebase.

Related Skills

• ../docs-codebase/SKILL.md
• ../dev-context-engineering/SKILL.md
• ../dev-workflow-planning/SKILL.md
• ../qa-docs-coverage/SKILL.md
• ../product-management/SKILL.md
• ../software-architecture-design/SKILL.md

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.