Separate product requirements from technical planning
The product document explains the user problem, approved scope, non-goals, and acceptance criteria. Technical requirements add the system constraints that an implementation must respect. An implementation plan describes how the agent proposes to meet both.
These are related artifacts, not interchangeable documents. Keep a business decision such as “only administrators may invite colleagues” separate from a proposed implementation technique. Engineering should verify repository details rather than allowing the PRD author or the model to invent them.
Begin with an approved product requirements document. If the decision is unresolved, a more detailed coding prompt will only conceal that uncertainty.
Prepare the minimum useful handoff
- Goal and decision: link the accepted requirement and identify the version being implemented.
- Existing behavior: describe what works today and what must keep working.
- Boundaries: state included changes, excluded capabilities, and areas requiring separate review.
- Behavioral scenarios: cover normal use and relevant invalid, empty, unauthorized, and failure cases.
- Verified technical constraints: include interfaces or dependencies that an engineer has confirmed.
- Completion evidence: specify what checks and explanation the reviewer expects.
- Stop conditions: list uncertainties that require a question rather than a guess.
AI coding specifications should constrain observable behavior without prescribing every line of code. Excessive implementation detail can make a correct alternative look like a failure.
Worked handoff: cancel an invitation
Hypothetical product change: a workspace administrator may cancel a pending invitation. The example illustrates a specification, not yourproduct.chat implementation details.
Decision: permit administrators to cancel pending invitations.
Included: pending invitations in the current workspace.
Excluded: deleting active members, changing roles, resending invitations.
R1: only an authorized administrator may cancel an invitation.
R2: after cancellation is confirmed, that invitation cannot be accepted.
R3: a cancelled invitation remains identifiable as cancelled.
R4: if the operation fails, do not display a successful cancellation.
Technical review needed before implementation:
- Confirm the existing permission checks and invitation states.
- Identify the authoritative cancellation operation.
- Check how concurrent acceptance and cancellation are handled.
Stop if a required state or permission rule is missing or conflicting.
Do not add a new membership policy without product review.The concurrency question is consequential: the PRD must not leave the agent to decide whether cancellation can remove someone who already joined. Resolve that behavior before implementation begins.
Write acceptance scenarios a reviewer can inspect
Normal behavior
Given an administrator and a pending invitation in their workspace,
when cancellation succeeds,
then the invitation is marked cancelled and its link cannot be accepted.Boundary behavior
Given a user without invitation-management permission,
when they attempt to cancel an invitation,
then the operation is rejected and the invitation is unchanged.
Given the invitation has already been accepted,
when cancellation is requested,
then existing membership is not removed by this operation.Also check failure messaging, a repeated request, and keyboard access to the cancellation controls. Agree on the expected handling of the acceptance race rather than writing a test around whatever implementation happens to appear.
The Given–When–Then structure is documented in the official Gherkin reference. The fictional scenarios here are our own examples; they do not require a particular test framework.
Review the plan, then review the result
Ask the agent to map its proposed steps to requirement IDs before coding. A plan that adds bulk membership management exceeds this example's scope even if the addition seems convenient.
After implementation, request a change summary, the checks actually run, failures or checks not run, and unresolved assumptions. Inspect the diff and verify the important behaviors independently of the agent's summary. Passing tests are evidence about those tests, not automatic authorization to release.
Link product questions back to the human review boundaries. The full AI coding workflow covers planning, execution, and outcome review within PM Harness.