Requirements Rules for Agentic Development

A practitioner’s guide for writing requirements in spec-driven AI development

Download: **https://github.com/docraticmethod/cascadia**

Audience

This guide is for architects, engineers, and technical founders who use AI coding assistants (Claude Code, Cursor, Copilot) to build real applications. There are many articles about how to prompt AI coding tools; this one is about the upstream document that decides what the AI builds. No spec-driven development experience necessary.

• Includes a fill-in-the-blank REQUIREMENTS.md template at the end.

Good requirements are the key to agentic development

What goes in, comes out

Requirements are the thing you write when you tell a coding agent what to build. In theory they’re a contract. In practice they’re a wish, expressed in English, that has to survive translation by a series of language models each acting in good faith on what the previous one wrote down.

Write a requirement well and the coding agent builds what you asked for. Write it badly and it builds something else, or builds most of it minus the part you assumed was obvious.

The part that disappeared

In my last POC, the requirement said the application would fetch event data from the web. Strategy carried that forward. Architecture carried that forward. System instructions, somewhere along the way, decided this was a stretch goal.

The built application sat there politely, waiting for me to hand it an input file.

How requirements get edited at every layer

A requirement in Cascadia’s AI-assisted workflow goes through three rewrites before any code is generated. Strategy gets rewritten from requirements. Architecture gets rewritten from strategy. System instructions get rewritten from architecture. Finally, code gets generated from system instructions.

At each rewrite, the model resolves whatever is ambiguous in whichever direction takes the least work to express. Implicit becomes absent. Vague becomes generic. Assertions become assumptions the next layer feels free to ignore. By the time the coding agent generates the code, it has been independently transformed by four well-meaning collaborator agents.

How to use this guide

This guide has four parts:

1. The Writing-Style Rules: They’re the small grammatical and rhetorical habits that decide whether a requirement survives translation.
2. The Required Requirements Sections: Each one names a class of architect decision the cascade cannot make on your behalf, and what happens when you skip it.
3. The Template Appendix: This is a fill-in skeleton. Copy it, replace the angle-bracket placeholders, delete what doesn’t apply.
4. The Self-Check: A checklist for the last pass before you submit.

Where these rules came from

The rules below come from four reference POCs — two emergency department triage prototypes, one recidivism risk triage, and one SF AI events triage. Each one broke in a different place. The rules are what I wrote down so the next one would break in a new place instead of an old one. They were written for Cascadia, a spec-driven build system with four explicit layers, but they apply to any AI-assisted workflow where requirements get rewritten before they become code.

Writing-style rules

Imperatives, not assertions

If the application has to do something, tell it to do the thing. Don’t describe the world after the thing is done. This is the most common failure mode.

Post-conditions describe a state the cascade may assume is already true; imperatives describe work the cascade must propagate into system instructions.

Write: “Fetch events from <source> within <window>. Build the input data file at <path>. Validate against the input schema."

Don’t write: “The input data file exists and validates.”

Both sentences contain the same information. The first one survives the cascade. The second one gets read by the architecture layer as a precondition already satisfied — a thing it doesn’t have to make happen, because someone else already did.

Name things the cascade should preserve

If a term, category, label, or enum value should appear verbatim in the built application, name it explicitly in REQUIREMENTS. The cascade is fluent. It paraphrases. Attend / Consider / Skip becomes Recommended / Maybe / Pass, and now your taxonomy has two versions, one of them not yours. Anchor the words upstream and they survive.

Declare implementation choices that look like options

Anything the architect has already decided — LLM versus non-LLM, model identity, library, framework, schema validator — belongs in REQUIREMENTS as a constraint, not in STRATEGY as a tactic. The cascade treats tactics as open to revision and constraints as fixed inputs. A choice you made on Monday and put in the wrong layer becomes a choice the strategy layer remakes on Tuesday, possibly differently, possibly without telling you.

Specify visual treatment as a required deliverable, not as polish

If the dashboard needs to look a certain way, say so, and say it is required. Otherwise the strategy layer reads the visual spec as nice-to-have and demotes it to “stretch,” and the architecture layer ships you a dashboard that works. It will be gray. It will have Helvetica. You will know.

Specify date and times if ranges matter

AI does not know when “now” is. It will pick a “now” that is plausible and wrong. For any workflow that fetches, queries, or processes time-sensitive data — for example events, news, financial data — state the current date and the relevant window in REQUIREMENTS. Otherwise you will get last year or last month’s data.

Required Requirement Sections

1. Context

What the application is for, who uses it, and the bounds of its claims. If you don’t bound the application here, the cascade will assume the most general case and over-build.

• The end-user: One person, a role, a team — be specific.
• The decision: What the LLM model in the application supports (triage, rank, score, classify, route, recommend).
• The deployment surface: Single laptop, POC, internal tool, hosted demo, production.
• Validation posture: What the system is and is not validated against. Especially important in regulated or research domains: state explicitly that the system is a prototype, that no real decisions are made from its output, and that no real PII is processed.

2. Inputs

Where the data comes from, what shape it is, and how it gets into the application.

• Data shape: Structured fields, free-text content, nested data, mixed.
• Data Source: File on disk, scraped from a URL, API fetch, user upload, generated synthetically.
• **Data Acquisition tasks: *If the application is responsible for acquiring its own data, say so explicitly and in imperative form. See writing-style rule on imperatives.
• Temporal scope (when relevant): Any data-fetching workflow needs an explicit currentDate and a window (e.g., “the next 30 days from currentDate”). Do not rely on the LLM to know what “now” is; do not rely on downstream layers to infer the window. State it.
• Completeness expectations: Will real inputs be incomplete (missing fields, ambiguous text)? Should test data reflect that incompleteness, or should test data represent a pre-curated set where everything is well-formed?

3. Domain framework (or decision rubric)

The structured knowledge the application reasons over. The cascade will not invent domain knowledge. If the framework is incomplete here, the strategy and architecture layers will paper over the gap with generic language, and the application will produce generic output.

• Ranking or Evaluation: The factors, signals, categories, or criteria the application weighs.
• How to weigh: Whether factors are positive, negative, or modulating (logistics, cost, context). Keep these categories non-overlapping — the same dimension should not appear in two categories. If “fee” is negative, “free” is not also positive; either negate the negative or split into a logistics modulator.
• Citations or sources: if the framework is research-grounded.
• Domain-specific vocabulary: Terms the cascade should preserve verbatim (clinical terms, legal terms, regulatory categories).

4. Test data

Declare your Fixture-scope philosophy

What the fixture set looks like, and what claim the fixture is trying to support. — Be explicit. The wrong philosophy choice produces the wrong test data and the wrong demo.

• Real-world variability vs. Pre-curated quality

A) Real-world variability — fixtures span the realistic distribution including bad data, missing fields, ambiguous cases. Appropriate when the deliverable is a research prototype, a triage system that must handle reality, or a methodology test of how the system behaves under noise.

B) Pre-curated quality — fixtures are all viable options to be ranked, no bad data, no missing fields beyond reasonable ambiguity. Appropriate when the application is acting as a personal assistant or curator surfacing only good options to a decision-maker.

• Coverage requirements: Enumerate the case shapes the fixture must include (must-rank-high case, must-rank-low case, ambiguous case, missing-data case, logistics-extreme case, a mix of mid-tier cases). Each shape is a behavioral assertion about the system.
• Size cap: State the maximum number of cases as a budget tied to model-call cost and runtime ceiling. The architecture template will flag if exceeded; the cap belongs in REQUIREMENTS.
• Privacy and source: State whether data is synthetic, real-but-public, real-and-redacted, or mined from a specified source. If mined, identify the source.

5. Outputs

What the application produces, per case and globally.

• Per-case outputs: Fields, structure, reasoning visibility. State that a missing-information section is rendered for every case (possibly empty), not only for cases flagged as substantially incomplete.
• Recommended actions: If the application emits action recommendations, name the action categories (e.g., Attend / Consider / Skip) so the cascade does not invent its own taxonomy.
• Explanations: Whether prose rationales are required, what they should reference (specific factors, framework citations, contextual notes).
• Checklists or follow-ups: Any per-case operational checklist the user should see.

6. Sequencer (if the application produces a ranked list)

How the application orders cases.

• Composite logic: What inputs the ordering weighs. State urgency, value, and conservatism handling explicitly and on equal footing — do not let one dominate by accident of phrasing.
• Per-entry vs. global rationale: Be explicit: does each ranked entry include its own rationale (N entries → N rationales), or is there a single global ordering explanation? The cascade has misread “each entry includes a rationale” as the latter. Sharpen the wording.
• Missing-data treatment: Where do cases with substantial missing data rank? Above confirmed low-value, below confirmed high-value, is the standard conservative choice — but it must be declared.

7. Output surface (dashboard or UI)

What the user sees.

• Layout: Panel structure, navigation, scroll behavior.
• Information hierarchy: What fields are primary (always visible, prominent) versus secondary (in detail view). The architecture template handles structural invariants (collapsed state, scroll independence) but not which fields are primary — that is a requirements-level call.
• Default state: What is selected on load, what is collapsed, what is expanded.
• Visual treatment: Color scheme, typography, look-and-feel. State that the visual treatment is a required deliverable, decided at requirements time and executed without iteration. The cascade has demoted aesthetic specifications to “stretch” when the requirements treated them as suggestion rather than mandate.

8. Implementation

Explicit declarations the cascade cannot infer.

• LLM commitment: If the application is LLM-driven, declare it at requirements time as an architect-level commitment, not as a strategy-level option. Otherwise the strategy layer may treat LLM use as a tactic open to alternatives, and downstream layers will inherit ambiguity about whether non-LLM extraction paths are in play.
• Model specification: Declare the exact model the target application will use (e.g., claude-sonnet-4–6). Without this, the cascade will guess, and the built application will fail open to a default that may not exist, requiring manual fixup. This is one of the cheapest fixes available and prevents a recurring class of silent failure.
• Other concrete dependencies: Schema validators, specific libraries, runtime versions — anything the architect has already decided and does not want the cascade to choose.

Self-check before submitting to Cascadia

Before clicking Submit on REQUIREMENTS, the architect runs this checklist.

• [ ] Context names the user, the decision, the deployment surface, and the validation posture.
• [ ] Inputs declare source, shape, and acquisition (imperative form if the application acquires its own data).
• [ ] Temporal scope is declared if any data is time-sensitive.
• [ ] Completeness expectations are stated.
• [ ] Domain framework lists factors with non-overlapping categories.
• [ ] Test data declares its fixture-scope philosophy (variability vs. pre-curated).
• [ ] Test data lists required case shapes and a size cap.
• [ ] Outputs specify per-case fields including missing-information handling for every case.
• [ ] Recommended-action taxonomy is named if applicable.
• [ ] Sequencer composite logic states urgency, value, and conservatism on equal footing.
• [ ] Per-entry vs. global rationale is unambiguous.
• [ ] Output surface declares information hierarchy (primary vs. secondary fields), not just structural layout.
• [ ] Visual treatment is declared and marked as a required deliverable.
• [ ] LLM commitment is declared at requirements level.
• [ ] Target application model is specified by exact identifier.
• [ ] All action-bearing statements use imperatives, not assertions.

Appendix: REQUIREMENTS.md Template

Copy and fill. Replace angle-bracket placeholders.

Delete sections that genuinely do not apply (e.g., Sequencer for a non-ranking application).

<Project Name>

Context

<One paragraph: who uses this, what decision it supports, where it runs, what it is and is not validated against.>

Inputs

<Data shape, source, acquisition. If the application fetches its own data, write the fetch as an imperative.>

Temporal scope: currentDate is <YYYY-MM-DD>. The relevant window is <e.g., the next 30 days from currentDate>.

Completeness expectations: <Will real inputs be incomplete? Should test data reflect that?>

<Domain framework or decision rubric>

<The structured knowledge the application reasons over. Factors organized as positive, negative, modulating — non-overlapping categories.>

Test data

Fixture-scope philosophy: <real-world variability OR pre-curated quality>. <One-sentence justification.>

Coverage requirements:

• <Must-rank-high case shape>

• <Must-rank-low case shape>

• <Ambiguous case shape>

• <Missing-data case shape (if variability philosophy)>

• <Logistics-extreme or domain-extreme case shape>

• <A mix of mid-tier cases>

Size cap: <N> cases total.

Source and privacy: <Synthetic / real-public / real-redacted / mined from <source>>.

Outputs

For each case:

• <Per-case fields, including missing-information section rendered for every case>

• Recommended action: <Action1 / Action2 / Action3>

• <Explanation requirements>

• <Checklist or follow-up requirements>

Sequencer

<Composite logic. State urgency, value, and conservatism on equal footing. Specify per-entry rationale: N entries produce N rationales.>

Output surface

Layout: <panel structure, scroll, navigation>

Information hierarchy:

• Primary (always visible): <fields>

• Secondary (in detail view): <fields>

Default state: <selected on load, collapsed, expanded>

Visual treatment: <color scheme, typography, look-and-feel>. This visual treatment is a required deliverable, decided at requirements time and executed without iteration.

Implementation

LLM commitment: This application is LLM-driven. The factor assessments, rationales, and ordering are produced by LLM calls. This is a requirements-level commitment, not a strategy-level option.

Target application model: <exact model identifier, e.g. claude-sonnet-4–6>

*Other dependencies:** <schema validator, libraries, runtime versions the architect has already chosen>

Copyright © 2026 Blake Rogers. All rights reserved.

Quotation and citation for academic, journalistic, or commentary purposes is welcome under fair use. For permission to reproduce, adapt, or redistribute substantial portions, contact saltyfog@gmail.com.