Vague prompt
add team invites
Learn
Writing AI-friendly software requirements
AI-friendly requirements make intent explicit before a coding agent writes code. They define the goal, scope, behavior, constraints, edge cases, architecture context, and acceptance criteria the agent needs to build the right thing without guessing.
Short answer
AI-friendly requirements remove the guesses from the prompt.
A normal requirement may be clear to the person who wrote it because they already know the product, architecture, and constraints. A coding agent does not. An AI-friendly requirement writes down the context the agent would otherwise infer: what should happen, who it affects, what must not change, how success will be checked, and which technical boundaries matter.
The point is not longer requirements. The point is fewer hidden assumptions.
The problem
Coding agents are fast enough to turn ambiguity into code.
A vague requirement can produce a convincing implementation that is still wrong. The agent may choose the wrong data model, skip an edge case, ignore a permission rule, or invent an architecture that conflicts with the rest of the system.
Missing scope becomes extra work.
The agent changes files or flows that should have been out of bounds.
Missing constraints become invented design.
The agent guesses ownership, state, or API shape.
Missing edge cases become bugs.
Expiration, retries, duplicates, permissions, and failure states get skipped.
Missing acceptance criteria make review subjective.
Nobody can quickly tell whether the task is done.
Missing architecture causes drift.
The local change works, but the system shape bends.
AI-friendly requirements make the important context visible before implementation starts.
Template
A good requirement gives the agent goal, scope, constraints, and done.
The best format is simple enough to write quickly and structured enough for an agent to follow.
# Requirement: {feature or change}
## Goal
What outcome should this create?
## Background
What existing behavior, product rule, or technical context matters?
## Scope
What should be included?
## Non-goals
What should not be changed?
## User / system behavior
What should happen in the important flows?
## Data, API, and architecture context
Which components, models, APIs, events, or constraints matter?
## Edge cases
What unusual states, errors, permissions, retries, limits, or lifecycle cases
must be handled?
## Acceptance criteria
How will we know the implementation is correct?
## Open questions
What still needs human decision before implementation?A coding agent can work with prose, but structure makes the requirement easier to read, plan from, and review against.
Clarity
The requirement should answer the questions the agent would otherwise guess.
Before handing work to a coding agent, scan the requirement for missing information. Ambiguity is not always bad during brainstorming, but it is expensive during implementation.
- Who is affected? Which user, role, team, tenant, or system actor?
- When does it happen? Which state, event, lifecycle moment, or trigger?
- What changes? Which behavior, data, API, screen, or workflow?
- What must not change? Which existing contracts, flows, or constraints are out of scope?
- What can fail? Expiration, retries, duplicates, permissions, invalid input, race conditions, or partial completion.
- What proves it works? Tests, acceptance criteria, screenshots, logs, or manual review steps.
If a human reviewer would ask it, the agent probably needs it too.
Architecture
Requirements for coding agents need technical intent.
Product behavior is not enough. A coding agent also needs to know how the change should fit into the existing system. Without architecture context, the agent may create a solution that works locally but violates the broader design.
- Which component or service should own this behavior?
- Which files, modules, or packages are relevant?
- Which API contracts, events, or schemas must remain stable?
- Which database models or migrations are allowed?
- Which security, privacy, tenancy, or permission rules apply?
- Which existing pattern should the agent follow?
- Which performance, reliability, or rollout constraints matter?
The requirement should tell the agent where the change belongs, not just what the user should see.
Example
Turn vague intent into buildable context.
Weak requirement
Add team invites.Why it is weak: It does not define who can invite, what roles can be assigned, how tokens expire, what happens to existing users, how duplicates work, what API shape is expected, or how the feature will be reviewed.
Stronger requirement
# Requirement: Team invitations
## Goal
Allow organization admins to invite new members by email and assign them a role
before they join.
## Scope
- Admins can create an invitation for an email address.
- Invitations have one assigned role: member or admin.
- Invited users receive an email with a single-use acceptance link.
- Accepted invitations attach the user to the organization.
## Non-goals
- Do not add SSO-based invites.
- Do not change billing seat enforcement in this task.
## Behavior
- Pending invitations can be accepted, revoked, or expire after 7 days.
- Existing organization members cannot be invited again.
- If the email belongs to an existing user, accepting links that account.
- If the email is new, accepting creates the account before joining the org.
## Architecture context
- Organization membership is owned by the org module.
- Invitation tokens must be stored hashed.
- Email sending should use the existing notification service.
- Audit events should be emitted for create, revoke, and accept.
## Acceptance criteria
- Admin can create an invitation with role member or admin.
- Non-admin cannot create invitations.
- Expired and revoked invitations cannot be accepted.
- Duplicate pending invites for the same email and org are rejected.
- Tests cover create, accept, revoke, expire, and permission failure paths.The strong requirement does not write the code. It gives the agent fewer dangerous decisions to invent.
Planning
Good requirements become safer tasks.
A structured requirement is easier to decompose. Instead of asking a coding agent to implement the entire feature in one leap, turn the requirement into ordered tasks with clear acceptance criteria.
01
Data model and migration
Invitation table, token hashing, indexes, lifecycle states.
02
Backend API
Create, revoke, accept, duplicate handling, permission checks.
03
Email flow
Invitation email, acceptance link, expiration behavior.
04
UI flow
Invite form, pending invite list, revoke action, error states.
05
Tests and review
Unit tests, integration tests, acceptance criteria, docs update.
Requirements define what should be true. Plans make the path to that truth reviewable.
Drift
Requirements should not disappear after the code is merged.
AI-friendly requirements are most valuable when they stay connected to the project. If the implementation changes the behavior, the requirement or related design docs should be updated. Otherwise, the next agent run starts from stale intent.
- Review against acceptance criteria. Check whether the implementation matches the requirement.
- Record changes. If the final behavior differs from the original plan, write that down.
- Update decisions. Capture important tradeoffs and reasons.
- Preserve execution history. Future agents should know what happened, not only what was requested.
The requirement is part of project memory, not a disposable prompt.
Windy
Windy turns requirements into agent-readable project memory.
Windy gives developers and coding agents one shared source of truth for requirements, specs, architecture, diagrams, plans, tasks, and execution history. Humans review and shape that memory in the web app. Coding agents read and write it over project-scoped MCP.
Windy Docs — the requirement and design memory.
Requirements, specs, architecture notes, diagrams, contracts, schemas, and decisions.
Windy Plans — the execution layer.
Ordered tasks, objectives, dependencies, acceptance criteria, prompts, and execution logs.
Your coding agent still writes the code. Windy gives it requirements it can build from — and a place to update the source of truth when behavior changes.
Pitfalls
Common mistakes when writing requirements for coding agents.
Writing only a feature title.
"Add exports" is not enough context for a safe implementation.
Skipping non-goals.
Agents need to know what not to change.
Leaving out permissions.
Role and access rules are easy for agents to miss if they are implicit.
Ignoring lifecycle states.
Pending, failed, expired, revoked, retried, and archived states often matter.
Forgetting architecture.
Requirements should say where the change belongs in the system.
Not defining done.
Acceptance criteria turn review from opinion into a checklist.
Letting requirements go stale.
If behavior changes, the requirement or source of truth should change too.
FAQ
Questions, answered.
They are requirements written with enough explicit context for a coding agent to implement safely: goal, scope, behavior, constraints, architecture, edge cases, and acceptance criteria.
No. A prompt is a single instruction. A requirement is a reviewable source-of-truth artifact that can be planned from, linked to, updated, and reused across agent runs.
Detailed enough to remove dangerous ambiguity. Small changes can use short requirements. Cross-cutting changes need architecture, constraints, edge cases, and a plan.
Yes. Coding agents need to know where the change belongs, which contracts must stay stable, and which constraints must be respected.
Yes. Acceptance criteria give both the agent and the human reviewer a clear definition of done.
Windy stores requirements in project Docs, connects them to Plans and tasks, and exposes the source of truth to coding agents over MCP.
Related
Keep exploring.
Your coding agent still writes the code. Windy gives it requirements it can build from.
Windy stores requirements in project Docs, connects them to Plans and tasks, and exposes the source of truth to coding agents over MCP.
windylogic.ai