Write Feature Specifications

This is a recommended operational technique, not a universal manual-authoring or document-approval procedure. A PE may supply a conversation, example, or demonstrated correction instead of a polished feature document. The agent analyzes and maintains intended behavior while implementing; humans inspect working outcomes and resolve consequential business decisions. Sample identifiers, headings, acceptance conditions, and per-feature files are optional project techniques. Enterprise rules may separately require approval for risky work.

Specification work preserves intended behavior for implementation, future change and independent verification. Agents can draft and maintain it alongside functional increments; humans primarily inspect outcomes rather than sign documents.

Responsible role: Product Engineer. Participants: stakeholders for consequential business decisions; architect or UX specialist for their concerns. Inputs: conversations, examples, corrections, current intent and approved technical boundaries. Outputs: maintained agent-readable behavior context, working increments and visible unresolved decisions. No universal document sign-off or polished manual feature file is required.

The Product Engineer can express intended outcomes through conversational AI, stakeholder discussion, examples, or a demonstrated correction. Agents may explore workflows, enumerate roles and failure cases, ask about unresolved rules, and maintain readable product context while implementing. The PE challenges invented assumptions by inspecting actual behavior and taking consequential policy questions to accountable humans.

The maintained record is distinct from a chat transcript and from observed code. Keep it version-controlled for later changes and independent verification. Humans need not approve every line of prose before a useful increment is built; the agent must not revise intended behavior merely to make a defect disappear.

1. Supply intent and boundaries. Give objectives, examples, current behavior and relevant constraints without exposing sensitive data.
2. Ask for analysis. Let the agent surface actors, workflows, assumptions and unanswered questions.
3. Resolve consequential decisions. Responsible humans settle material policy; keep other unknowns explicit.
4. Capture context while building. The agent may draft readable Markdown and implement a useful increment together. Identifiers and section structures are optional.
5. Inspect the product. Exercise outcomes and challenge missing behavior, invented assumptions and inconsistent rules.
6. Preserve intent. Version-control the maintained behavior record; a commit is not business acceptance.
7. Iterate and verify independently. Agents update context as outcomes change; a separate verifier tests intent against the product.

Initial stakeholder statement:

“Reviewers should be able to reject requests.”

A conversational assistant might ask whether a reason is required, whether any reviewer can reject any request, whether self-review is allowed, and whether the requester can see the decision.

After the stakeholder decides the rules, the Product Engineer records observable behavior such as:

“An authorized reviewer may reject a pending request only after entering a nonempty reason. The decision records the reviewer and decision time, and the requester can view the outcome and reason for their own request. A requester cannot review their own submission.”

This example demonstrates analysis and clarification, not AI-made policy. The specification can then provide separate acceptance conditions for an empty reason, unauthorized action, self-review, and requester visibility.

1. Choose a coherent feature boundary. A feature should represent meaningful user or system behavior. Avoid a single giant product specification when it becomes hard to maintain, but do not fragment one simple workflow into a separate file for every field or button.

2. State purpose and actors. Explain who needs the feature, what outcome it supports, who may use it, and any significant exclusions. Reference broader project objectives when useful.

3. Describe expected behavior. Write the primary flow in terms of observable outcomes rather than imagined source-code structure. Specify inputs, validations, state changes, feedback, and outputs where relevant.

4. Identify rules and exceptions. Include permissions, eligibility, limits, rejection or failure cases, and behavior when data or external dependencies are unavailable. If an exception materially changes acceptance, it belongs in the specification.

5. Add acceptance conditions. Write checks that can be evaluated by observation or test. Include representative positive and negative conditions. Avoid claims such as “works perfectly” or “has an intuitive interface” without concrete context.

6. Resolve and record uncertainty. Mark important open questions and obtain decisions from authorized stakeholders. Do not promote an agent's guess to an accepted business rule. If work proceeds while a noncritical issue remains open, identify the assumption as provisional.

7. Review for consistency. Check the specification against related features, approved security and technical constraints, terminology, and existing behavior. Cross-reference shared rules instead of restating them incompatibly.

8. Maintain it through iteration. Commit the specification as part of the durable project corpus. When stakeholders change accepted behavior, update the corresponding text and acceptance conditions before or together with implementation changes. Keep history in version control rather than creating confusing parallel copies.

Use the specification lifecycle: specifications/requests/ holds human-authored requests awaiting implementation; specifications/archive/ preserves implemented human-authored requests as historical records; specifications/current/ contains agent-maintained descriptions of currently required product behavior. Move implemented requests to the archive without rewriting their historical content, and update current-state specifications. Direct prompts and conversations can authorize development without a formal specification file; maintain the current-state record regardless of request format.

Vague: “Reviewers should have an easy way to reject requests.”

Better: “An authorized reviewer can reject a pending request only after entering a reason. The request moves to Rejected, records the reviewer and decision time, and displays the reason to the requester. A user without review permission cannot perform the action.”

This example does not prescribe a particular interface. It specifies meaningful behavior that can be implemented and verified.

An optional identifier and title; purpose; scope and exclusions; actors and permissions; preconditions; main behavior; business rules; exceptions; acceptance conditions; dependencies; cross-references; and unresolved decisions. This is a starting structure, not an instruction to fill sections that provide no value.

Product context is useful when it describes intended behavior clearly enough for implementation and independent observable checks, while material unresolved decisions remain assigned to accountable owners. Agents maintain this record as work evolves. Humans inspect and accept working outcomes; a completed prose review or specification sign-off is not a universal prerequisite. Enterprise risk approvals still apply where required. Keep the intended-behavior record version-controlled as outcomes evolve.

Writing implementation code disguised as requirements; repeating enterprise rules that are already authoritatively documented elsewhere; over-specifying cosmetic details; leaving permission or error behavior entirely implicit; and letting working code become the only reliable statement of expected behavior.