How to Write a Technical Specification for an AI Coding Agent

A good PRD tells an AI coding agent what product to build. A technical specification tells it how the approved product should work inside a software system.

Without that second layer, an agent has to make important engineering decisions while writing code. It may choose a data structure that does not fit the existing application, create an API that conflicts with another module, overlook access-control rules, or implement a workflow without considering what happens when something fails.

The result can look complete while hiding problems that appear during integration or production.

A technical specification reduces this guesswork. It documents the system’s architecture, component responsibilities, data contracts, integrations, security requirements, operational expectations and verification criteria.

This guide explains how to write one for an AI coding agent, including a practical structure, a reusable template, a worked example and rules for controlling implementation decisions.

What is a technical specification for an AI coding agent?

A technical specification is an engineering document that describes how a defined product requirement should be implemented and verified.

It connects product intent to engineering work.

For an AI coding agent, it should answer questions such as:

• Which parts of the existing application are involved?
• What components need to be created or changed?
• How do those components communicate?
• What data is stored and who can access it?
• What happens when an operation succeeds or fails?
• Which security and operational constraints must be respected?
• What tests or observable results prove the implementation is correct?
• Which decisions can the agent make, and which require approval?

A useful technical specification is specific enough to guide implementation but does not attempt to predict every line of code.

It should describe the required system behaviour, constraints and interfaces. The agent can then inspect the repository and work out the implementation details that fit the existing codebase.

PRD vs technical specification vs implementation plan

These documents are related, but they should not be treated as interchangeable.

Document	Purpose	Main question
PRD	Defines product requirements and scope	What should the product do, and why?
Technical specification	Defines engineering design and constraints	How should the system implement it?
Implementation plan	Organises the work into phases and tasks	In what order should the work happen?
Task prompt	Assigns the immediate work to the agent	What should the agent do now?

For example, a PRD might say:

“Workspace members can create and assign tasks to other members.”

The technical specification should define the relevant data relationships, permission checks, API behaviour, failure handling and verification requirements.

The implementation plan can then divide the work into database changes, service logic, interface changes and tests.

The task prompt tells the coding agent which approved phase or task to work on.

This separation keeps product decisions, engineering decisions and execution instructions from becoming one large, difficult-to-maintain document.

If you have not defined the product requirements yet, start with How to Write a PRD an AI Coding Agent Can Actually Build From. If the release scope is unclear, begin with How to Scope a SaaS MVP.

What makes a technical specification agent-ready?

A document can be technically detailed and still be difficult for an agent to follow.

The most useful specifications have five characteristics.

1. Traceable requirements

Every important engineering decision should connect to an approved product requirement, constraint or operational need.

2. Explicit interfaces

Components should have clear responsibilities and defined inputs, outputs and failure behaviour.

3. Measurable requirements

Words such as “fast,” “secure” and “reliable” are not enough. The specification should explain how those qualities will be measured or verified.

4. Defined decision boundaries

The agent should know which changes are already approved, which require confirmation and which are prohibited.

5. Observable verification

The specification should explain what must be tested and what evidence is required before the work is considered complete.

The rest of this guide uses an eight-part structure to cover these requirements.

The eight sections of a technical specification

1. Context, scope and existing system

Start by explaining what engineering work the specification covers.

Include:

• Project and feature name.
• Specification owner.
• Version and approval status.
• Related PRD and product requirement IDs.
• Current system or repository context.
• In-scope engineering work.
• Explicit technical exclusions.
• Confirmed constraints and unresolved decisions.

Do not assume the coding agent understands the current application simply because it can access the repository.

It should inspect the existing code before proposing changes. The specification provides the target and constraints; the repository shows the current reality.

Identify the existing system

For an existing project, document the relevant parts of the codebase:

Area	Information to provide
Application structure	Relevant applications, packages and modules
Frontend	Framework, routing and important UI areas
Backend	Services, API layer and business logic
Data	Database, important entities and existing relationships
Authentication	Current authentication and session approach
Integrations	External services and communication methods
Deployment	Runtime environments and deployment constraints
Testing	Existing test frameworks and relevant test commands

Use real repository details, not assumptions.

If the project already uses a particular authentication provider, database or component pattern, state whether the feature must follow that choice or whether alternatives can be considered.

Define scope boundaries

A specification should not silently turn a feature into a larger redesign.

For example:

In scope:

• Add task assignment to existing workspace projects.
• Enforce workspace membership when assigning tasks.
• Display assignment status in the task view.

Out of scope:

• Replacing the current authentication system.
• Redesigning the complete project dashboard.
• Adding a new notification provider.
• Rebuilding the database structure for unrelated modules.

This makes it easier to identify when an agent is solving a different problem from the one approved.

2. System architecture and component responsibilities

Explain how the affected parts of the system fit together.

You do not need to design a huge architecture diagram for every feature. A simple description of the components, their responsibilities and the direction of communication is often enough.

For example, a typical SaaS task workflow might involve:

1. Browser interface.
2. API or server action.
3. Authentication and authorization checks.
4. Task application service.
5. Database.
6. Notification worker, if notifications are in scope.

Describe each component’s job.

Component	Responsibility	Must not do
Task interface	Collect user input and display task state	Enforce security by itself
API layer	Validate the request and coordinate the operation	Trust client-supplied permissions
Authorization layer	Check whether the actor can perform the operation	Assume that authentication implies permission
Task service	Apply approved task rules	Bypass required authorization checks
Database layer	Store and retrieve task data	Return records from unrelated workspaces
Notification worker	Deliver approved notifications	Change task ownership or status

This is an illustrative division of responsibilities. Existing projects may use different architectural patterns.

Document important boundaries

Explain where responsibilities begin and end.

For instance:

• The interface can hide actions the user is not allowed to perform.
• The server must still enforce permissions.
• The business service owns the task assignment rules.
• The database layer must respect the project’s tenant-isolation strategy.

These boundaries prevent the same rule from being implemented differently in multiple places.

Include a component or sequence diagram where useful

A simple flow can remove ambiguity:

User
  |
  v
Task Interface
  |
  v
API / Server Action
  |
  +----> Authentication
  |
  +----> Workspace Permission Check
  |
  v
Task Service
  |
  v
Database
  |
  v
Updated Task Response

For a more complex workflow, show the sequence of events, including asynchronous processing and failure paths.

Record significant architecture decisions

If you choose a particular approach, record why.

An Architecture Decision Record (ADR) is useful for significant choices such as:

• Choosing a shared database with tenant isolation instead of separate databases.
• Using a background job for a slow external operation.
• Keeping an existing authentication provider instead of replacing it.
• Selecting an API communication pattern.

A basic ADR should include:

Field	Purpose
Context	What problem or constraint led to the decision?
Decision	What approach was selected?
Alternatives	What other options were considered?
Consequences	What benefits and trade-offs follow?
Status	Proposed, accepted or superseded
Owner and date	Who approved it and when?

AWS’s architectural decision record guidance describes this approach and recommends preserving the context and consequences of significant decisions. See AWS: Architectural Decision Record Process.

Do not create an ADR for every small implementation detail. Use it for choices that affect system structure or future maintenance.

3. Data model and state transitions

AI coding agents need a clear understanding of the data they are working with.

For every important entity, specify:

• Entity name and purpose.
• Required fields.
• Field types and constraints.
• Relationships.
• Ownership.
• Uniqueness requirements.
• Lifecycle and state transitions.
• Data retention and deletion behaviour.
• Relevant indexes or query expectations.

You do not always need to prescribe the exact final database schema. But the specification should define the data contract that the implementation must preserve.

Example: Workspace task management

Imagine a SaaS product where users belong to workspaces and can create tasks within projects.

An illustrative relationship model:

Workspace
   |
   +---- Membership
   |
   +---- Project
             |
             +---- Task

A task may have the following fields:

Field	Type	Requirement
id	UUID	Unique task identifier
workspace_id	UUID	Owning workspace
project_id	UUID	Associated project
title	String	Required
description	Text	Optional
assignee_id	UUID	Optional member reference
status	Enum	Approved task states only
created_at	Timestamp	Creation time
updated_at	Timestamp	Last update time

The example does not prescribe a specific ORM or database.

It identifies the information the system needs to preserve.

Specify relationships and ownership

The specification should answer:

• Can a task exist without a project?
• Can the assignee belong to a different workspace?
• Can a workspace member access another workspace’s tasks?
• What happens to tasks when a project is archived?
• What happens when an assigned member leaves the workspace?

These decisions affect data integrity, authorisation and lifecycle behaviour.

For multi-tenant SaaS applications, workspace or tenant ownership is particularly important. Do not rely on a workspace ID supplied by the browser as proof that the current user can access that workspace.

Define state transitions

If an entity has states, list the allowed transitions.

For example:

TODO
  |
  v
IN_PROGRESS
  |
  v
COMPLETED

Then define what happens when a user tries an unsupported transition.

Can a completed task return to in-progress? Can an archived project accept new tasks? Can a task be deleted after completion?

The specification should document the intended rules rather than leaving them for the agent to invent.

Include migration and data compatibility requirements

For an existing application, state:

• Whether a database migration is required.
• Whether existing records need backfilling.
• Whether old and new application versions must work during rollout.
• Whether any fields or records may be deleted.
• How the migration will be tested.
• What the recovery or rollback approach is.

Destructive schema changes should not be silently performed just because an agent believes they are necessary.

4. API contracts and external integrations

Define how the affected components communicate.

This includes internal APIs, external service integrations, webhooks, queues and scheduled jobs where they are relevant.

For each interface, describe:

• Method or operation.
• Path or event name.
• Authentication requirement.
• Required permissions.
• Request structure.
• Response structure.
• Validation rules.
• Error responses.
• Side effects.
• Idempotency and retry behaviour, where relevant.

An API contract should make it possible for a developer or agent to understand what a caller can send and what a successful or unsuccessful operation returns.

Example: Assign a task

Illustrative endpoint:

PATCH /api/tasks/{taskId}/assignee

Request:

{
  "assigneeId": "user_123"
}

Expected behaviour:

• The caller must be authenticated.
• The caller must have permission to manage the task.
• The task must belong to the caller’s accessible workspace.
• The requested assignee must be eligible for that workspace.
• The assignment must not occur when any required check fails.

Possible responses:

Status	Meaning
200	Assignment updated
400	Invalid request
401	Authentication required
403	Caller does not have permission
404	Task or referenced resource not found
409	Conflict with a defined business rule
500	Unexpected server failure

Choose the exact status codes and response format to match the project’s existing API conventions.

The important part is that the expected behaviour is documented rather than left to inconsistent implementation choices.

Define error behaviour

Do not document only successful responses.

For each important operation, consider:

• Missing required fields.
• Invalid field values.
• Expired sessions.
• Insufficient permissions.
• Missing related records.
• Duplicate requests.
• Concurrent updates.
• External service timeouts.
• Database failures.

Also specify which failures are retriable and which require user action.

Use API contracts when appropriate

For HTTP APIs, an OpenAPI document can provide a structured description of paths, operations, request parameters and data schemas.

The OpenAPI Specification is a standard format for describing HTTP APIs. Its use is optional, but it can help keep API contracts consistent across frontend, backend and testing work.

Do not introduce an OpenAPI file simply for appearance if the project has a different established way of maintaining API contracts.

Document external integrations

For each external service, describe:

• Purpose.
• Service owner.
• Required credentials or permissions.
• Request and response expectations.
• Rate limits or known operational constraints.
• Timeout and retry rules.
• Failure behaviour.
• Whether a mock or sandbox environment exists.
• What data may be sent to the provider.

Never put real API keys, passwords or private tokens into a technical specification. Refer to the approved secret-management mechanism instead.

5. Security, privacy and access control

Security requirements must be explicit.

A coding agent should not have to decide which users can see particular records or whether a server-side permission check is necessary.

Document:

Authentication

• Which users must be authenticated?
• Which routes are public?
• How are sessions or tokens handled?
• What happens when authentication expires?

Authorization

• Which roles can perform each action?
• Which resources are private?
• How is resource ownership checked?
• Are permissions enforced on the server?

Tenant isolation

• How are workspace or tenant boundaries enforced?
• Can a user access another tenant’s data through a guessed identifier?
• Are background jobs and exports also tenant-scoped?

Input validation

• Which fields are accepted?
• What length, type and range limits apply?
• How are unexpected or malformed values handled?

Secrets and sensitive information

• Where are credentials stored?
• Which data must be excluded from logs?
• What information can be sent to external services?
• How are sensitive exports and backups protected?

Abuse protection

• Are rate limits needed?
• Can an endpoint trigger expensive operations?
• Are invitation or password-recovery flows protected against misuse?

For web application security requirements, OWASP’s Application Security Verification Standard provides a structured catalogue of security controls and verification requirements. Its stable version listed on the OWASP project page is ASVS 5.0.0, published 30 May 2025. You can reference a specific version and requirement rather than writing vague instructions such as “make it secure.”

Sources: OWASP ASVS.

Define permission boundaries explicitly

For a workspace application, an example permission matrix might look like this:

Action	Owner	Member	Viewer
View workspace projects	Yes	Yes	Yes
Create projects	Yes	Yes	No
Assign tasks	Yes	Yes	No
Manage workspace membership	Yes	No	No
Delete workspace	Yes	No	No

This is an illustrative policy. A real product must decide its own roles and permissions.

Do not rely only on hiding buttons in the interface. The backend must enforce the same permission model.

6. Non-functional and operational requirements

Functional requirements explain what the system does. Non-functional requirements describe the quality and operating conditions it must meet.

Important categories include:

Performance

• Response-time expectations.
• Expected concurrent usage.
• Database query constraints.
• Background job completion expectations.

Reliability

• Expected availability, if defined.
• Handling of temporary failures.
• Retry and recovery behaviour.
• Data consistency requirements.

Scalability

• Expected users or workload.
• Expected data growth.
• Known capacity constraints.
• Components that may become bottlenecks.

Accessibility and compatibility

• Supported browsers and devices.
• Keyboard navigation requirements.
• Relevant accessibility standard or target.
• Responsive behaviour.

Observability

• Which events should be logged?
• Which failures should be monitored?
• Which metrics indicate a degraded service?
• How can an operator trace a failed request?

Operations

• Deployment environments.
• Required environment variables.
• Database migration approach.
• Backup and restoration expectations.
• Rollback conditions.
• Required operational documentation.

Turn vague quality goals into measurable requirements

Consider these examples:

Vague statement	More useful specification
The API should be fast	Define the endpoint, workload, measurement method and response-time target
The application should be reliable	Define the required availability or recovery behaviour and how it will be observed
The system should scale	State the expected workload and which capacity limits need to be checked
The app should be secure	Identify authentication, authorisation, tenant isolation and verification requirements
The UI should be accessible	Name the accessibility target and describe the relevant interaction checks

Do not invent performance targets to make the document look complete.

If the expected workload is unknown, label it as an unresolved input and assign someone to decide it.

7. Acceptance criteria and verification

This section explains how you will determine whether the implementation meets the specification.

A coding agent should not be allowed to mark a feature complete merely because files were created or the page renders.

For every important requirement, identify the evidence that demonstrates it works.

Include:

• Requirement or design reference.
• Expected behaviour.
• Verification method.
• Relevant test layer.
• Expected result.
• Required test evidence.

Use observable acceptance criteria

Example requirement:

“Only authorised workspace members can assign tasks.”

Weak acceptance criterion:

“Task assignment works correctly.”

Better acceptance criteria:

1. Given an authenticated workspace owner, when they assign a task to an eligible workspace member, the assignment is saved and displayed.
2. Given a user without permission to manage tasks, when they attempt the same operation, the server rejects the request.
3. Given an assignment to a user outside the task’s workspace, the operation is rejected and the original assignment remains unchanged.
4. Given an invalid user identifier, the request returns the documented validation error.
5. Given a temporary database failure, the system does not report a successful assignment.

These statements define observable outcomes rather than subjective completion.

Map requirements to tests

Requirement	Test type	Evidence
Assign task to eligible member	Integration	Successful assignment response and stored relationship
Block unauthorised assignment	Integration / security	Rejected request
Prevent cross-workspace assignment	Integration / security	No cross-tenant modification
Handle invalid user ID	Unit / integration	Documented validation response
Handle database failure	Integration	Error path and unchanged task state

The test layers have different jobs:

• Unit tests check small pieces of logic.
• Integration tests check how components work together.
• End-to-end tests exercise a user journey across the application.
• Security checks examine access boundaries and failure cases.
• Performance tests evaluate the system against specified workload targets.

Not every feature needs every test type. Use the smallest set that provides sufficient evidence for the risk and behaviour involved.

Record the actual verification commands

The specification should identify the commands that are known to work in the repository.

For example:

• Type checking command.
• Lint command.
• Unit test command.
• Integration test command.
• Build command.

Do not guess these commands. The coding agent should inspect the package scripts, project documentation and existing CI workflow first.

The final report should identify what was actually run, what passed, what failed and what was not tested.

8. Agent execution boundaries: Always, Ask First and Never

A technical specification should define the agent’s authority, not only the software design.

This is especially important when the agent can edit files, execute commands, interact with services or make changes to a repository.

A practical model has three categories.

ALWAYS

Actions the agent can perform within the approved scope.

Examples:

• Read relevant repository files and existing project instructions.
• Follow established naming and architecture conventions.
• Reuse existing dependencies and shared components where appropriate.
• Add or update tests required by the approved specification.
• Run the documented local verification commands.
• Report assumptions, blockers and observed failures.
• Preserve existing behaviour outside the approved change.

ASK FIRST

Actions that require explicit approval.

Examples:

• Adding a new dependency or external service.
• Changing the authentication or authorization model.
• Performing a destructive or irreversible database migration.
• Changing cloud infrastructure or deployment configuration.
• Modifying billing or payment behaviour.
• Accessing external systems using new credentials.
• Changing public API contracts in a way that affects existing clients.
• Removing existing data or functionality.
• Committing, pushing or deploying, where these require separate approval.

NEVER

Actions that are prohibited.

Examples:

• Hardcoding secrets or credentials.
• Disabling security checks to make tests pass.
• Bypassing workspace or tenant authorization.
• Sending private user data to an unapproved service.
• Modifying production data without an approved procedure.
• Claiming tests passed when they were not run.
• Silently changing approved requirements to make implementation easier.

These are example boundaries. Each project should tailor them to its risk, tooling and approval process.

Coding-agent tools offer different permission mechanisms. Codex supports repository guidance through AGENTS.md; GitHub Copilot supports repository instructions; Claude Code provides permission and project configuration mechanisms. The exact file names and behaviour are tool-specific, so the specification should not assume one convention works everywhere.

Official references:

• OpenAI: Customization and project guidance
• GitHub: Custom instructions for Copilot
• Anthropic: Claude Code Best Practices

A practical technical specification template

The following Markdown template can be copied into a project and adapted to its architecture.

Save it under a clear path such as:

docs/specs/feature-name.md

# Technical Specification: [Feature Name]

## Document information
- Project:
- Feature:
- Owner:
- Status: Draft / Review / Approved
- Version:
- Date:
- Related PRD:
- Related requirements:

---

## 1. Context and scope

### Objective
[What engineering capability must be delivered?]

### Product requirements
- [Requirement ID and description]

### Existing system context
- Frontend:
- Backend:
- Database:
- Authentication:
- Relevant modules:
- Existing integrations:

### In scope
- 

### Out of scope
- 

### Constraints
- 

### Assumptions and unresolved decisions
- 

---

## 2. Architecture and components

### System context
[Describe the system and its external dependencies.]

### Architecture overview
[Describe the components and their relationships.]

### Component responsibilities

| Component | Responsibility | Inputs | Outputs |
|---|---|---|---|
| | | | |

### Data flow
1.
2.
3.

### Architecture decisions
- Decision:
- Reason:
- Alternatives:
- Consequences:

---

## 3. Data model and lifecycle

### Entities

| Entity | Field | Type | Required | Constraints |
|---|---|---|---|---|
| | | | | |

### Relationships
- 

### Ownership and isolation
- 

### State transitions
- 

### Migration and compatibility
- 

### Retention and deletion
- 

---

## 4. API and integration contracts

### API operations

| Operation | Method | Path / Event | Permission |
|---|---|---|---|
| | | | |

### Request contracts
[Fields, types, validation and required values.]

### Response contracts
[Success response and documented error responses.]

### External services
- Provider:
- Purpose:
- Authentication method:
- Data exchanged:
- Timeout and retry behaviour:
- Failure handling:

### Idempotency and concurrency
- 

---

## 5. Security and privacy

### Authentication
- 

### Authorization
- 

### Tenant isolation
- 

### Input validation
- 

### Secrets handling
- 

### Sensitive data and logging
- 

### Abuse protection
- 

### Security verification references
- Standard and version:
- Applicable requirements:

---

## 6. Non-functional and operational requirements

### Performance
- Measurement:
- Target:
- Workload:
- Test method:

### Reliability and recovery
- 

### Accessibility and compatibility
- 

### Logging and monitoring
- 

### Deployment and environments
- 

### Backups and rollback
- 

---

## 7. Acceptance criteria and verification

| Requirement ID | Expected behaviour | Test type | Evidence |
|---|---|---|---|
| | | | |

### Required commands
- Type check:
- Lint:
- Unit tests:
- Integration tests:
- Build:

### Manual verification
- 

### Completion report
- Changes made:
- Commands executed:
- Results:
- Failures:
- Untested areas:
- Known limitations:

---

## 8. Agent execution boundaries

### ALWAYS
- 
- 

### ASK FIRST
- 
- 

### NEVER
- 
- 

### Approval requirements
- Human owner:
- Decisions requiring approval:
- Stop conditions:

---

## Approval

- Technical owner:
- Product owner:
- Status:
- Date:
- Approved version:

This is a reusable starting point, not a mandatory format. A small feature may need only a subset of these sections. A high-risk change may need additional security, migration, recovery or performance detail.

Worked example: Specifying task assignment in a SaaS workspace

Consider a fictional SaaS application that allows teams to manage projects and tasks.

Its approved product requirement is:

“Workspace members with task-management permission can assign a task to another eligible member of the same workspace.”

The PRD explains why that capability is needed. The technical specification must define how to implement and verify it.

A. Architecture context

Illustrative component flow:

Task Details UI
      |
      v
Task Assignment API
      |
      v
Authentication Check
      |
      v
Workspace Permission Service
      |
      v
Task Assignment Service
      |
      v
Database
      |
      v
Updated Task Response

The diagram shows the intended responsibility boundaries. It does not prescribe a specific framework, database or deployment architecture.

B. Data requirements

The task must contain:

• A unique task identifier.
• Its owning workspace.
• Its current assignee, if one exists.
• Its associated project.
• A modification timestamp.

The membership relationship must establish whether a user is eligible to receive assignments in that workspace.

The task’s workspace and the assignee’s membership must be checked together.

C. API behaviour

The assignment operation accepts a task identifier and an assignee identifier.

The operation should:

1. Authenticate the caller.
2. Identify the task within its permitted workspace context.
3. Confirm the caller can manage task assignments.
4. Confirm the requested assignee is an eligible member.
5. Apply the assignment.
6. Return the updated task representation.

If any required check fails, the assignment must not be saved.

D. Security boundary

The backend must not trust a workspace identifier or user role supplied by the browser as proof of access.

The operation must verify access using authenticated identity and trusted membership data.

A request from a user who belongs to another workspace must not modify the task.

E. Acceptance matrix

Scenario	Expected result
Owner assigns task to eligible member	Assignment succeeds
Member without assignment permission tries to assign	Request rejected
Requested assignee belongs to another workspace	Request rejected
Requested member does not exist	Validation or not-found error
Database write fails	Assignment remains unchanged
Same request is repeated	Behaviour follows the documented update and idempotency rules

This is an illustrative engineering example, not a claim that the scenario has been implemented or tested in a real IndieOS project.

The key is that the specification gives the agent enough information to build the intended behaviour and gives a reviewer a way to check it.

How to hand the specification to an AI coding agent

Writing the document is only one part of the process. You also need to control how it is used.

1. Inspect the repository first

Before changing code, the agent should inspect:

• Repository structure.
• Existing project instructions.
• Relevant modules.
• Package scripts and commands.
• Existing tests.
• Current architecture and conventions.
• Existing dependencies and integrations.

For Codex, repository-level instructions can be maintained in AGENTS.md. OpenAI’s documentation describes how this guidance is discovered and applied. Other tools use their own conventions.

Do not create several competing instruction files containing duplicated rules.

2. Ask for a specification review before implementation

Provide the agent with the approved specification and ask it to review the existing codebase.

A useful prompt:

Read and analyse:

docs/specs/feature-name.md

Do not modify any files yet.

Inspect the relevant repository structure and existing project instructions.

Return:

1. A summary of the existing architecture relevant to this feature.
2. The components and modules that need to change.
3. The data model and API changes required.
4. The security and permission checks involved.
5. Dependencies and integration requirements.
6. Conflicts between the specification and existing code.
7. Blocking questions or unresolved decisions.
8. A proposed implementation sequence.
9. The tests and verification commands you can actually identify.

Do not invent missing requirements.

Separate:
- Decisions already approved.
- Decisions requiring confirmation.
- Implementation details that can follow existing project conventions.

Do not begin implementation.

This gives you an opportunity to catch misunderstandings before the agent makes changes.

3. Resolve contradictions before coding

If the specification says one thing and the existing application behaves differently, the agent should identify the conflict.

For example:

• The specification requires workspace-level access, but the existing API only checks whether a user is logged in.
• A new field conflicts with an existing database relationship.
• The approved workflow requires a background job, but the project currently processes everything synchronously.
• A proposed integration requires a new paid service.

These issues should be resolved deliberately. Do not let the agent silently choose whichever option is easiest to implement.

4. Convert the specification into bounded implementation phases

Large changes should be divided into tasks that can be independently reviewed.

An example:

Phase	Scope	Completion evidence
1	Data and migration changes	Migration and data checks
2	Business logic and permission enforcement	Unit and integration tests
3	API contract	Request and response tests
4	User interface	Relevant workflow tests
5	End-to-end verification	Complete user journey and regression checks

The order should follow actual dependencies in your architecture.

Each phase should have its own acceptance criteria and stop condition. Do not allow the agent to move to the next phase while required verification is failing.

OpenAI’s Codex execution-plan guidance describes self-contained implementation plans, observable acceptance criteria, progress tracking and explicit verification steps. A technical specification and an execution plan work together, but they are not the same document.

Source: OpenAI Cookbook: Using PLANS.md for Long-Horizon Work.

5. Verify the result instead of trusting the completion message

Ask for evidence:

• Which files changed?
• Which requirements were implemented?
• Which tests ran?
• Which commands passed?
• Which commands failed?
• What remains untested?
• Were any approved boundaries changed?
• Were any dependencies or external services added?

A statement such as “Implementation completed successfully” is not sufficient by itself.

You need observable behaviour and verification evidence.

Common mistakes when writing technical specifications for AI agents

Mixing the PRD and technical specification

The PRD defines product decisions. The technical specification explains how to implement them. Repeating the full product document in the engineering specification creates two sources of truth.

Reference the approved PRD and expand only the engineering details needed for implementation.

Describing architecture without component responsibilities

A diagram full of boxes and arrows is not enough. Explain what each component owns, what it receives and what it returns.

Ignoring existing code

A technically attractive design can be a poor fit for an established application. The agent must inspect the repository and preserve existing conventions unless a change is approved.

Using vague non-functional requirements

“High performance” and “enterprise-grade security” are not measurable requirements. Define the expected behaviour, measurement or verification method.

Omitting failure behaviour

Document what happens when data is missing, an external service fails, a request is repeated or a user lacks permission.

Ignoring tenant isolation

In a multi-tenant SaaS, checking that a user is authenticated does not establish that the user can access a particular workspace’s data.

Specify how tenant ownership and authorization are enforced across the affected components.

Giving the agent unrestricted authority

A specification should identify actions that require human approval. Adding dependencies, changing billing, altering access control, modifying infrastructure and performing destructive migrations should not be treated as ordinary implementation details.

Treating generated code as proof of completion

A file existing does not mean the feature works. Require relevant tests, integration checks and observable results.

Letting documentation drift from the code

When an approved design changes, update the specification or record the decision. Otherwise, future agent sessions may rely on stale instructions.

Technical specification review checklist

Before approving a technical specification, check:

• The related PRD and product requirements are identified.
• Existing repository conventions have been considered.
• Scope and non-goals are explicit.
• Architecture and component responsibilities are documented.
• Data relationships, ownership and lifecycle rules are clear.
• API and integration contracts are defined.
• Authentication and authorization requirements are explicit.
• Tenant isolation is addressed where relevant.
• Performance and reliability expectations are measurable or marked unresolved.
• Failure and recovery behaviour is documented.
• Acceptance criteria are observable and testable.
• Verification commands are identified from the real repository.
• Always, Ask First and Never boundaries are defined.
• Human approval requirements are clear.
• The specification has an owner and an approved version.

Frequently asked questions

Final takeaway

A good technical specification gives an AI coding agent a clear engineering target.

Document the system context, architecture, component responsibilities, data model, interfaces, security, operational requirements and verification criteria. Then define which actions the agent can perform, which require approval and which are prohibited.

Do not confuse a detailed document with a correct implementation. The specification provides the engineering contract; tests, reviews and observed behaviour show whether that contract was met.

The practical sequence is simple:

Scope the MVP → Write the PRD → Write the technical specification → Plan the implementation → Build and verify in stages.

That is how you move from a product idea to code that can be reviewed, tested and maintained.

---

Sources and further reading

1. OpenAI: Using PLANS.md for Long-Horizon Work — self-contained engineering plans, acceptance criteria, validation and progress tracking.
2. OpenAI: Codex Customization — project guidance, skills, memories and other customization mechanisms.
3. OpenAI: Codex AGENTS.md Guidance — persistent repository instructions and their scope.
4. GitHub: Custom Instructions for Copilot — repository-wide and path-specific agent guidance.
5. OpenAPI Specification — structured descriptions of HTTP API contracts.
6. OWASP Application Security Verification Standard — security requirements for web applications and services.
7. AWS: Architectural Decision Record Process — recording significant engineering decisions and their consequences.
8. Anthropic: Claude Code Best Practices — tool permissions and safe agent workflows.

Documentation checked on 1 November 2026. Tool capabilities and documentation formats change; confirm current support in the official documentation for your selected coding agent.