AI Instructions

AI Instructions define the operating behavior of the AI coding agent. They establish how the agent reads the documentation, follows the implementation roadmap, preserves documented decisions, handles ambiguity, verifies implementation, and communicates its work.

Even complete product documentation does not automatically define how an AI coding agent should behave when implementing it.

The problem is not simply that AI can make mistakes. The problem is that without explicit operating rules, the agent may make decisions that were never approved.

AI Instructions are created once the product documentation and implementation roadmap provide enough context to define how an AI coding agent should operate against them.

AI Instructions sit at the boundary between specification and execution. They are not a replacement for the documents above them.

• Product

  Uses it to protect documented product decisions during AI implementation.

• Design

  Uses it to ensure documented experience decisions are not silently changed.

• Engineering

  Uses it to keep implementation within the defined technical architecture and roadmap.

• AI agent

  Uses it as the operating contract for implementation behavior.

These are the fields AI Instructions can define.

1. 01

   Documentation Hierarchy

   Which documents the agent must consult and how they relate.

2. 02

   Source of Truth

   How the agent should treat documented decisions.

3. 03

   Implementation Behavior

   How the agent should approach tasks.

4. 04

   Decision Boundaries

   What the agent may decide independently and what requires human input.

5. 05

   Specification Gap Handling

   What happens when required information is missing.

6. 06

   Conflict Handling

   What happens when documented decisions disagree.

7. 07

   Scope Control

   How the agent prevents unrelated changes.

8. 08

   Verification

   How the agent checks its work.

9. 09

   Change Reporting

   How the agent communicates modifications.

10. 10

    Progress Reporting

    How the agent communicates completed and remaining work.

11. 11

    Human Escalation

    When the agent must stop and request a decision.

12. 12

    Completion Criteria

    What must be true before an implementation task is considered complete.

This document defines behavior, not an exhaustive list of prompt-engineering techniques.

• Product vision
• Feature requirements
• Business rules
• User flows
• UI design
• Database structure
• API contracts
• Technical architecture
• Implementation order
• Application source code
• Project management processes

This is a methodology example. It illustrates instruction structure, not a specific AI tool's configuration format.

1. 01

   Read before implementing.

   The agent must inspect the relevant documentation before beginning a task.

2. 02

   Follow the Development Roadmap.

   The agent should implement the defined task sequence rather than choosing a new sequence without justification.

3. 03

   Preserve documented decisions.

   The agent must not silently change approved product, design, data, API, or architectural decisions.

4. 04

   Stay within task scope.

   The agent should not introduce unrelated features, refactors, or architectural changes.

5. 05

   Surface Specification Gaps.

   Missing decisions must be reported rather than invented.

6. 06

   Surface conflicts.

   Contradictory documentation must be reported rather than silently resolved.

7. 07

   Verify before reporting completion.

   The agent must perform the relevant tests and checks defined by the task.

8. 08

   Report meaningful changes.

   The agent should clearly communicate what was implemented, what was verified, and what remains blocked.

9. 09

   Prefer explicitness over assumption.

   When an important decision is unclear, do not infer silently.

10. 10

    Do not rewrite the specification through implementation.

    If implementation reveals that a documented decision needs to change, surface the change rather than silently modifying the source documentation.

AI should not treat the documentation as a collection of unrelated files. It should use the documents as a connected specification system.

A Specification Gap exists when implementation requires a decision that the documentation does not define.

The exact missing decision should remain the focus. The agent does not invent the solution.

Sometimes two documents may contain contradictory decisions. The AI agent must not silently choose one.

1. 1Identify the conflicting statements.
2. 2Identify the affected task.
3. 3Identify the affected documents.
4. 4Do not silently choose a winner.
5. 5Request clarification.
6. 6Resume only after the decision is resolved.

Do not define a universal document precedence hierarchy such as “PRD always overrides BRD” unless the methodology has explicitly established one. The agent should identify the conflict rather than inventing a precedence rule.

• Writing vague instructions such as "build it correctly."
• Repeating the entire PRD, FSD, or architecture document inside the AI Instructions.
• Giving AI permission to make product decisions silently.
• Telling AI to "use its best judgment" for unspecified business behavior.
• Failing to define what happens when documentation is incomplete.
• Failing to define what happens when documents conflict.
• Letting AI change documented decisions during implementation without reporting the change.
• Allowing AI to expand task scope because related improvements appear useful.
• Treating verification as optional.
• Giving AI a roadmap without task-level acceptance criteria.
• Letting AI implement the entire product in one uncontrolled pass.
• Writing instructions that depend on one specific AI coding tool.
• Confusing implementation-level decisions with product-level decisions.