4 MD Files for AI Coding Workflow

PRD.md — What & Why

Purpose

PRD.md explains what will be built and why the product is being built. Its focus is on the product, user needs, and requirements. Technical implementation details are not the main concern at this stage.

Simple Overview

Think of the PRD as an agreement about the product before coding begins. After reading the PRD, the AI or developer should be able to answer two questions:

What needs to be built?

When can we say that the feature is working correctly?

Structure

Overview
- Explains the basic overview of the product.
- Contains the product name, a short description, and the problem it aims to solve.
Goals
- Explains the main goals of the product.
- Defines the success criteria, which are the conditions that indicate whether the goals have been achieved.
Users
- Explains who will use the product.
- There can be more than one user type.
- Each user type describes:
  - Who they are.
  - What they need.
  - The problems or pain points they experience.
Core Features
- Explains the main features that need to be built.
- Each feature includes:
  - Description: what the feature is for.
  - User story: the feature requirement from the user’s perspective.
  - Requirement: what the system must do.
  - Acceptance criteria: the conditions that determine whether the feature is working correctly.
User Flows
- Explains how users interact with the product.
- Includes:
  - Main flows.
  - Alternative flows.
  - Error conditions or edge cases.
Business Rules
- Explains the rules the system must follow.
- Includes business rules, validation, and specific constraints.
Non-Functional Requirements
- Explains the qualities or characteristics the system needs, rather than specific features.
- Examples:
  - Performance: how quickly the system should respond.
  - Scalability: the system’s ability to handle increased usage.
  - Accessibility: how easily the product can be used by different users.
  - Compatibility: the devices or environments that must be supported.
Scope
- Defines the boundaries of the product.
- In Scope: what will be built.
- Out of Scope: what is intentionally not being built.
Success Metrics
- Defines the metrics used to determine whether the product or feature is successful.
Open Questions

Stores questions that do not have answers yet.
This section helps prevent assumptions from being made without clarification.

Role in the Workflow

PRD is one of the initial foundations of the AI coding workflow.

Before deciding how the UI should be built or how the system should be implemented, we need to determine what we actually want to build.

PRD then becomes a reference for the following documents, especially DESIGN.md and ARCHITECTURE.md.

When coding with AI, PRD also helps the AI understand the product context, user needs, features that need to be built, and the conditions for considering a feature complete.

Key Takeaways

PRD answers: “What are we building and why?”
Its focus is on the product and user needs, not technical implementation details.
Every feature should have requirements and acceptance criteria so the AI knows what to do and when the result is considered correct.
User flows and business rules help the AI understand how the product should behave in different situations.
Scope prevents the AI from inventing unnecessary additional features.

Creating PRD.md

Open https://chatgpt.com/gpts
Search for “prd”
Choose “Product Requirements Document (PRD) Writer” by timflemingux.com

DESIGN.md — What It Looks & Feels Like

Purpose

Explains how the product will look and feel when used. DESIGN.md serves as the UI/UX reference, so developers or AI do not have to guess what the interface should look like or how it should behave.

Simple Overview

If PRD answers “What are we building?”, then DESIGN.md answers “What will the product look and feel like?”

It covers visual rules, UI components, layout, pages, responsive behavior, and how the UI responds when users perform actions.

Structure

Design Principles
- Basic principles that guide the design.
- Examples include simplicity, consistency, and ease of use.
- These principles help ensure that design decisions are not based solely on personal preference.
Design System
- Visual rules used consistently throughout the product.
- Examples include colors, typography, spacing, borders, and other visual rules.
Components
- A list of UI components used in the product.
- Examples include buttons, inputs, cards, modals, navigation bars, tables, and so on.
- The goal is to ensure that the same components have consistent appearance and behavior.
Layout
- Explains how UI elements are arranged on a page.
- Examples include sidebar structure, headers, content areas, grids, and spacing between elements.
Pages
- Explains which pages exist in the product and what each page looks like.
- This section translates requirements from the PRD into an interface that users can see.
Responsive Behavior
- Explains how the interface changes across different screen sizes.
- For example, how sidebars, tables, or cards adapt to desktop, tablet, and mobile.
States
- Explains UI conditions when certain situations occur.
- Loading: what users see while data is being loaded.
- Empty: what is displayed when there is no data yet.
- Error: what is displayed when something goes wrong.
- Success: what is displayed when an action succeeds.
Interactions
- Explains how the UI responds to user actions.
- Hover: changes when the cursor is over an element.
- Focus: the appearance when an element is selected or focused.
- Click: what happens when an element is clicked.
- Drag: behavior when an element can be dragged.
- Animation: animations used in the interface.
- Transitions: changes between UI states that make interactions feel more natural.
Accessibility
- Explains how the design remains usable by different users, including users who rely on assistive technologies.
- Keyboard navigation: the UI can be used without a mouse.
- Focus states: users can identify which element is currently active.
- Contrast: text and elements have sufficient contrast.
- Screen reader behavior: important information can be understood by screen readers.
Assets
- Lists the visual assets used in the product.
- Examples include icons, images, illustrations, and logos.
- The goal is to ensure developers use appropriate and consistent assets.
References
- References used to create the design.
- These may include Figma, screenshots, or other design references.
- This section helps others understand the source or reference behind the design.

Role in the Workflow

DESIGN.md is used after the product requirements have been clearly defined in PRD.

PRD provides the needs and requirements. DESIGN.md then translates those needs into the UI experience and visual design.

After that, DESIGN.md can be used as a reference for determining how the design should be implemented in ARCHITECTURE.md and eventually implemented through AGENTS.md.

Simply:

PRD → “What does the user need?” DESIGN → “How does the user see and use the feature?”

Key Takeaways

DESIGN.md is a UI/UX guideline, not a product requirements document.
Its focus is what is visible, how the layout works, and how the UI behaves.
Design systems and components keep the interface consistent.
States and interactions explain what happens when users interact with the application.
References help developers or AI understand the intended design, because apparently humans can interpret the word “modern” in 17 different ways.

Creating DESIGN.md

Refero Styles
- Can be used to find existing DESIGN.md references.
Google Stitch
- Can be used to help create designs and generate DESIGN.md references.

ARCHITECTURE.md — How It Works

Purpose

Explains how the system will be built technically. If PRD.md answers “what are we building and why?”, and DESIGN.md answers “what does it look like?”, then ARCHITECTURE.md answers “how does the system work behind the scenes?”.

Simple Overview

ARCHITECTURE.md is a technical guide to use before coding begins.

It defines the technologies being used, how the application is divided into different parts, how data moves through the system, how APIs work, how users are authenticated, and how the application will eventually be deployed.

The goal is not to create extremely complicated technical documentation just to make the project look like a Fortune 500 company project. The goal is to ensure that developers and AI have the same technical understanding before implementation begins.

Structure

Architecture Overview
- Explains the overall system.
- Defines the architecture pattern being used.
- Provides diagrams to help understand the relationships between system parts.
- For example, how the Frontend, Backend, Database, and external services interact.
Tech Stack
- Defines the main technologies being used.
- Frontend: framework/library used to build the UI.
- Backend: framework/runtime used to run application logic.
- Database: where data is stored.
- Infrastructure: the environment and components that run the application.
Project Structure
- Explains how the code is organized within the project.
- For example:
```
src/
├── ...
├── ...
└── ...
```
- The goal is to ensure developers and AI know where specific code should belong.
System Components
- Explains the main parts of the system.
- Frontend handles the UI and user interactions.
- Backend handles application logic.
- Database stores data.
- External Services handle third-party services when needed.
Data Flow
- Explains how a request travels through the system.
- Example: User Request → Application Logic → Database → Response
- If external services are used, their flow is also described.
Data Model
- Explains what data is stored.
- Defines entities, relationships between data, and important constraints.
- This section helps developers understand the data structure before creating the database.
API Architecture
- Explains how the Frontend and Backend communicate.
- Includes:
  - API style
  - Authentication
  - Response format
  - Error handling
Authentication & Authorization
- Explains how the system knows who the user is and what the user is allowed to do.
- Authentication = verifying the user’s identity.
- Authorization = determining the user’s permissions.
- This section also explains roles and permissions if they are used.
State Management
- Explains how application state/data is managed.
- For example, what data is managed on the frontend and how state changes are handled.
Error Handling
- Defines how the system handles errors.
- For example, when an API fails, the database has a problem, or a user’s request is invalid.
Security
- Explains the security decisions and mechanisms required.
- Focuses on protecting data, access, and communication between system components.
Performance
- Explains what needs to be considered so the system continues to perform well.
- Examples include query optimization, caching, or reducing unnecessary work.
- Not every performance technique needs to be used. Only those relevant to the project.
Architectural Decisions
- Records important technical decisions made during system design.
- Each decision includes:
  - Context → the problem or situation.
  - Decision → the chosen solution.
  - Reason → why that solution was chosen.
- The goal is to understand why the system was built this way, rather than only seeing the final result.
External Integrations
- Explains external services used by the application.
- Examples include payment providers, email services, storage, authentication providers, or third-party APIs.
- Explains how the system communicates with those services.
Deployment
- Explains how the application is run and released.
- Includes:
  - Environments → such as development, staging, and production.
  - Build → how the application is prepared to run.
  - Deployment → how the application is delivered to the target environment.

Role in the Workflow

ARCHITECTURE.md is used after the product requirements and UI design are sufficiently clear.

PRD.md tells us what needs to be built.

DESIGN.md tells us what the product looks like and how it is used.

ARCHITECTURE.md then translates those requirements into a technical design.

After that, AGENTS.md can provide instructions to AI on how to use these designs during coding.

Therefore, ARCHITECTURE.md acts as a bridge between product design and code implementation.

Key Takeaways

ARCHITECTURE.md explains how the system works technically.
It helps developers and AI share the same technical understanding before coding.
It covers more than the tech stack, including code structure, data flow, APIs, security, deployment, and architectural decisions.
Architectural Decisions are important for documenting the reasoning behind technical decisions.
Diagrams and tools only help explain the architecture. The most important things are the decisions and relationships between system components.

Creating ARCHITECTURE.md

Use AI with the following prompt:

ARCHITECTURE.md GENERATOR

ROLE
Act as a Senior Software Architect.

INPUT
Use PRD.md and DESIGN.md as the primary sources for creating ARCHITECTURE.md.

PRD.md describes product requirements.
DESIGN.md describes UI/UX, pages, components, interactions, states, and user flows.

WORKFLOW

Do not create ARCHITECTURE.md immediately.

1. ANALYZE
   Read both documents and identify requirements, features, user flows, data, integrations, and technical decisions that have already been defined.

2. FIND GAPS
   Identify information that is:
   * clear
   * inferable
   * unclear
   * conflicting

   Do not invent important technical decisions.

3. INTERVIEW
   If important information is unclear, ask the user. Multiple rounds of questions are allowed.

   Prioritize information that affects architecture: platform, tech stack, database, authentication, authorization, API, integrations, infrastructure, deployment, security, and performance.

   If the user does not know, briefly explain the available options and trade-offs.

4. GENERATE
   Once sufficient information is available, create ARCHITECTURE.md.

REQUIRED STRUCTURE

ARCHITECTURE.md MUST contain 15 sections:

1. Architecture Overview
   System overview, architecture pattern, diagram.

2. Tech Stack
   Frontend, Backend, Database, Infrastructure.

3. Project Structure
   Folder structure and code organization.

4. System Components
   Frontend, Backend, Database, External Services.

5. Data Flow
   Request and data flow between components.

6. Data Model
   Entities, relationships, constraints.

7. API Architecture
   API style, authentication, response format, error handling.

8. Authentication & Authorization
   Authentication method, roles, permissions.

9. State Management
   Application state management.

10. Error Handling
    Error handling strategy.

11. Security
    Relevant security mechanisms.

12. Performance
    Relevant performance and scalability considerations.

13. Architectural Decisions
    Every decision MUST include Context, Decision, Reason.

14. External Integrations
    External services, purpose, communication, authentication, failure handling.

15. Deployment
    Environments, build, deployment.

RULES

* Do not invent information.
* Do not change requirements from PRD or DESIGN.
* If PRD and DESIGN conflict, ask the user.
* Avoid overengineering.
* Use the simplest architecture that satisfies the requirements.
* If something cannot yet be determined, write "Needs clarification".
* Do not add technology or components without a reason.

VALIDATION

Before finalizing, ensure:

* PRD requirements are covered.
* DESIGN requirements are covered.
* The data model supports the features.
* The API supports frontend requirements.
* Authentication and authorization are consistent.
* Security matches the architecture.
* Deployment matches the infrastructure.
* Project structure matches the architecture.
* There are no conflicts between sections.
* There is no unnecessary complexity.

If there is a critical issue, return to INTERVIEW.

OUTPUT

After all information is sufficient, output only ARCHITECTURE.md.

The document must be clear, consistent, simple, and usable as technical context for developers and AI coding agents.

Goal: explain how the system is built, how its components relate to one another, and the reasoning behind technical decisions.

AGENTS.md — How AI Should Work

Purpose

AGENTS.md is an instruction manual for the coding agent. It tells the AI how to work on the project, which rules to follow, and which boundaries must not be crossed.

Simple Overview

If PRD.md explains what needs to be built, DESIGN.md explains what it should look like, and ARCHITECTURE.md explains how the system is built, then AGENTS.md explains how the AI should do the work.

In other words, this document is more like an instruction manual for an AI coding agent, rather than documentation about the software itself.

Structure

Project Context
- Provides a brief overview of the project so the AI understands the context before working.
Source of Truth
- Defines which documents should be used as references when information conflicts.
- The order is:
  1. AGENTS.md
  2. PRD.md
  3. DESIGN.md
  4. ARCHITECTURE.md
  5. Existing code
- This prevents the AI from arbitrarily choosing information from different sources.
General Rules
- General rules for modifying code.
- Examples include following existing patterns, not adding unnecessary dependencies, not recreating existing functionality, and not changing code unrelated to the task.
Before Coding
- Defines what the AI should do before starting to code:
  1. Read the relevant documentation.
  2. Inspect the existing implementation.
  3. Identify the affected areas.
  4. Create a change plan.
  5. Only then implement the changes.
- The goal is to prevent the AI from immediately “going straight to coding” just because a human gave it a one-line task.
Coding Standards
- Defines the coding standards that must be followed.
- Examples include programming language rules, naming conventions, file naming, component patterns, and error handling.
Architecture Rules
- Defines how the architecture should be applied in the code.
- For example, where business logic, API calls, database access, and dependency rules should live.
UI Rules
- Guides the AI to implement the UI according to DESIGN.md.
- The AI should reuse existing components and provide states such as loading, error, and empty.
Testing Rules
- Defines what needs to be tested, which framework is used, the required coverage, and how to run tests.
Git Rules
- Defines how the AI should work with Git.
- Examples include commit, branch, and rules against modifying files unrelated to the task.
Forbidden
- Lists things the AI is explicitly not allowed to do.
- Examples include exposing secrets, bypassing validation, changing the database schema without a migration, deleting tests to make them pass, or installing dependencies without a reason.
Definition of Done
- Defines when a task is considered complete.
- It is not simply “the code has been written”. Requirements must be met, the UI and architecture must follow the documents, tests must pass, there must be no lint/type errors, and there must be no unrelated changes.

Role in the Workflow

AGENTS.md is used when the AI begins coding.

The AI uses the previous documents as context:

PRD.md → understands the requirements.

DESIGN.md → understands the UI/UX.

ARCHITECTURE.md → understands the technical structure.

AGENTS.md → understands how to apply everything while coding.

This means the AI is not simply given a task like “build the dashboard page”. It also has rules for how that task should be implemented within the project.

Key Takeaways

AGENTS.md is an instruction manual for the coding agent.
It defines how the AI works, not the product itself.
It establishes rules, standards, boundaries, and the process to follow before coding.
Definition of Done helps the AI determine whether its work is actually complete.
The ultimate goal is to keep the AI consistent with the requirements, design, architecture, and existing codebase.

Creating AGENTS.md

Use AI with the following prompt:

ROLE
Act as a Senior Software Engineer and Coding Agent Architect.

TASK
Create AGENTS.md based on PRD.md, DESIGN.md, ARCHITECTURE.md, and the provided codebase information.

PURPOSE
AGENTS.md is an instruction manual for the coding agent. It explains how the AI should work, which rules it must follow, what it is forbidden from doing, and when a task is considered complete.

RULES
- Use only information from the provided input.
- Do not invent requirements, architecture, frameworks, tools, or conventions.
- Prioritize patterns already present in the codebase.
- Create rules that are practical and directly actionable for the coding agent.
- If information is unavailable or ambiguous, write "Needs clarification" instead of guessing.
- Avoid unnecessary explanations.
- Do not change the intent of PRD, DESIGN, or ARCHITECTURE.
- AGENTS.md must be specific to the project, not a generic coding guide.

SOURCE OF TRUTH
Use the following priority:
1. AGENTS.md
2. PRD.md
3. DESIGN.md
4. ARCHITECTURE.md
5. Existing code

AGENTS.md STRUCTURE

# AGENTS.md

## 1. Project Context
Briefly explain the project context based on the provided documents.

## 2. Source of Truth
Explain the source-of-truth priority and how the agent should resolve conflicts between sources.

## 3. General Rules
Create relevant general rules, such as:
- Follow existing patterns.
- Avoid unnecessary dependencies.
- Do not recreate existing functionality.
- Prefer simple solutions.
- Do not modify unrelated code.

## 4. Before Coding
Define the workflow before coding:
1. Read the relevant documentation.
2. Inspect the existing implementation.
3. Identify affected files/components.
4. Create a change plan.
5. Implement the changes.

Adjust this if the input defines a different workflow.

## 5. Coding Standards
Define standards supported by the input/codebase:
- Language conventions
- Naming conventions
- File naming
- Component conventions
- Error handling

Do not invent conventions.

## 6. Architecture Rules
Turn ARCHITECTURE.md into rules the agent can follow:
- Business logic location
- API calls
- Database access
- Dependency rules
- Other architectural constraints

## 7. UI Rules
Create rules based on DESIGN.md:
- Follow DESIGN.md.
- Reuse existing components.
- Do not create new components unless necessary.
- Handle loading, error, empty, and other required states.

## 8. Testing Rules
Define:
- What must be tested.
- Testing framework.
- Required coverage, if any.
- How to run tests.

Do not invent testing requirements.

## 9. Git Rules
Define:
- Commit conventions
- Branch conventions
- Rules for unrelated file changes

Use only conventions available in the input.

## 10. Forbidden
Define actions the coding agent must not perform.

Consider:
- Exposing secrets.
- Bypassing validation.
- Changing the database schema without a migration.
- Deleting tests to make them pass.
- Adding dependencies without a reason.

Only include rules relevant to the project.

## 11. Definition of Done
Define the criteria for considering a task complete.

When relevant, include:
- Requirements are implemented.
- UI follows DESIGN.md.
- Architecture follows ARCHITECTURE.md.
- Tests pass.
- No lint/type errors.
- No unrelated changes.

OUTPUT
- Output only the complete AGENTS.md content.
- Use Markdown.
- Use the same language as the primary input documents.
- Keep it concise, clear, and actionable.
- Write instructions directly to the coding agent.
- Do not explain the process used to create AGENTS.md.