Buy Template Now $65→
Skip to main content

AI Prompting


This template is built to be AI-friendly from the ground up.

Instead of relying on an AI tool to guess at your conventions, the template stores project context, design guidelines, architecture rules, and change history directly inside the repository. This gives every AI tool the same starting point, so it can make accurate, consistent modifications instead of reinventing patterns each session.

Think of it as the difference between hiring a contractor who's worked on your house for years versus a new one every single day. Without shared documentation, every AI session is the new contractor — capable, but starting from nothing, guessing at decisions someone already made. The ai/ directory is what turns every session into the contractor who already knows the house.

This approach works with:

  • ChatGPT
  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Future AI coding agents

Why AI Prompting?

AI tools don't automatically remember:

  • Your design system
  • Your component architecture
  • Previous modifications
  • Folder structure conventions
  • Project-specific rules

Each new session starts from zero — unless that knowledge lives somewhere the AI can read it. By documenting these things inside your repository, every AI session starts with the same context, regardless of which tool you're using or how much time has passed since the last change.

This matters more than it might seem at first. A typical AI coding session, without this structure, looks like:

  1. You describe what you want.
  2. The AI infers your conventions from whatever files it happens to read.
  3. It makes a reasonable, but not necessarily consistent, decision.
  4. Three sessions later, you have three slightly different patterns for the same kind of component.

With a documented ai/ directory, every session instead looks like:

  1. The AI reads PROJECT_CONTEXT.md, DESIGN_SYSTEM.md, and CHANGELOG.md.
  2. It already knows your border radius, your naming conventions, and what was changed last week.
  3. It makes the same decision a previous session would have made.
  4. Your codebase stays coherent, even across dozens of disconnected sessions and different tools.

Benefits include:

  • More consistent designs
  • Better code quality
  • Fewer architectural mistakes
  • Easier collaboration between humans and AI
  • Change tracking between AI sessions
  • Faster development, since less time is spent re-explaining the project
  • A growing, durable record of why the project looks the way it does — useful for onboarding human developers too, not just AI

How It Works

The system is built around one idea: the ai/ directory is the single source of truth.

Every file in it answers a different question an AI tool needs answered before it can safely touch your code:

| File | Answers the question |
|---|---|
| `PROJECT_CONTEXT.md` | What is this project, and what are its rules? |
| `DESIGN_SYSTEM.md` | What should this *look* like? |
| `FILE_STRUCTURE.md` | Where does this file belong? |
| `COMPONENT_RULES.md` | How should components be written? |
| `SEO_ARCHITECTURE.md` | How does SEO work here? |
| `CHANGELOG.md` | What has already changed? |
| `DECISIONS.md` | Why was it changed that way? |
| `TASKS.md` | What's left to do? |
| `PROMPT_TEMPLATE.md` | What order should the AI read all of this in? |

Root-level files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md) act as pointers — short instruction files that tell each AI tool to go read the ai/ directory before doing anything else. The tool-specific files stay thin on purpose; the actual rules live in one place so they never drift out of sync.

How an AI Session Actually Flows

When you ask an AI tool to make a change in a project structured this way, the practical sequence looks like this:

  1. Entry point — the tool reads its instruction file (AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md, depending on the tool).
  2. Context loading — that file tells it to read ai/PROJECT_CONTEXT.md, ai/DESIGN_SYSTEM.md, ai/FILE_STRUCTURE.md, ai/COMPONENT_RULES.md, and ai/CHANGELOG.md.
  3. Orientation — it now knows the stack, the visual language, where files belong, and what's already changed recently.
  4. Execution — it makes the requested change, following the rules it just read instead of inventing its own.
  5. Memory write-back — it appends an entry to CHANGELOG.md (and DECISIONS.md, if an architectural choice was made) describing what changed and how to undo it.

That last step is what makes the system circular rather than one-directional: each session doesn't just consume context, it contributes to it, so the next session inherits an even more complete picture than the last one had.

Recommended Structure

root/
├── AGENTS.md
├── CLAUDE.md
│
├── .github/
│   └── copilot-instructions.md
│
├── ai/
│   ├── PROJECT_CONTEXT.md
│   ├── DESIGN_SYSTEM.md
│   ├── FILE_STRUCTURE.md
│   ├── COMPONENT_RULES.md
│   ├── SEO_ARCHITECTURE.md
│   ├── CHANGELOG.md
│   ├── DECISIONS.md
│   ├── TASKS.md
│   └── PROMPT_TEMPLATE.md
│
├── app/
├── components/
├── content/
└── lib/

The ai/ directory acts as the single source of truth for all AI tools.

Inside the ai/ Directory

Zooming into just the ai/ folder, each file falls into one of three categories: context (what the project is), rules (how to build in it), and memory (what's already happened). Grouping them this way makes it easier to reason about what belongs where as the directory grows.

ai/
│
├── PROJECT_CONTEXT.md        # Context — project identity, stack, goals
├── DESIGN_SYSTEM.md          # Rules   — visual language, tokens, motion
├── FILE_STRUCTURE.md         # Rules   — where files live and why
├── COMPONENT_RULES.md        # Rules   — coding standards for components
├── SEO_ARCHITECTURE.md       # Rules   — metadata, sitemap, structured data
├── PROMPT_TEMPLATE.md        # Rules   — the read-order workflow itself
│
├── CHANGELOG.md              # Memory  — what changed, and how to revert it
├── DECISIONS.md              # Memory  — why it changed that way
└── TASKS.md                  # Memory  — what's pending vs. completed

| Category | Files | Purpose | |---|---|---| | Context | PROJECT_CONTEXT.md | Tells the AI what it's working on before anything else | | Rules | DESIGN_SYSTEM.md, FILE_STRUCTURE.md, COMPONENT_RULES.md, SEO_ARCHITECTURE.md, PROMPT_TEMPLATE.md | Constrain how changes should be made | | Memory | CHANGELOG.md, DECISIONS.md, TASKS.md | Record what's already happened, and why |

As a project grows, it's common for this flat structure to evolve into subfolders — for example, splitting DESIGN_SYSTEM.md into a design/ folder with separate files per domain once the design system gets too large for one document to stay scannable:

ai/
├── PROJECT_CONTEXT.md
├── FILE_STRUCTURE.md
├── COMPONENT_RULES.md
├── SEO_ARCHITECTURE.md
├── PROMPT_TEMPLATE.md
│
├── design/
│   ├── tokens.md            # Colors, spacing, radii, typography
│   ├── components.md        # Per-component visual patterns
│   └── motion.md            # Animation timing and easing rules
│
├── changelog/
│   ├── 2026-06.md           # One file per month, instead of one giant log
│   └── 2026-05.md
│
├── DECISIONS.md
└── TASKS.md

Splitting CHANGELOG.md by month (or by feature area, if that fits your project better) keeps any single file from becoming too large for an AI tool to comfortably read in full — which matters once a project has been actively developed for months. There's no fixed threshold for when to split; a reasonable signal is when a single file regularly takes up a large share of the context an AI tool has available, or when you find yourself scrolling past irrelevant history to find a recent entry.

PROJECT_CONTEXT.md

Defines the purpose, architecture, and goals of the project. This is the file that gives an AI tool its bearings — what's being built, in what stack, and under what constraints — before it writes a single line of code.

Example

# Project Context
 
Template Name:
Pulse UI
 
Framework:
Next.js
 
Language:
TypeScript
 
Styling:
Tailwind CSS
 
Animations:
Motion
 
Purpose:
Premium SaaS template.
 
Architecture Goals:
 
- Reusable components
- Content-driven pages
- SEO-first architecture
- AI-friendly development
 
Always:
 
- Use TypeScript interfaces
- Use content files
- Create reusable components
 
Never:
 
- Hardcode content
- Create page-specific UI components
- Duplicate logic

This file helps AI understand the project's purpose before making changes.

DESIGN_SYSTEM.md

Defines visual design rules — the vocabulary an AI tool needs to generate UI that looks like it belongs, rather than something bolted on. Spacing, radii, motion, and tone all live here so design decisions aren't reinvented component by component.

Example

# Design System
 
## Philosophy
 
Modern SaaS.
Minimal.
Premium.
 
## Border Radius
 
Cards:
rounded-3xl
 
Buttons:
rounded-xl
 
Inputs:
rounded-xl
 
## Containers
 
Max Width:
1400px
 
Content Width:
1280px
 
## Animations
 
Duration:
0.4s - 0.6s
 
Preferred:
- fade
- slide
- scale
 
Avoid:
- bounce
- elastic

This file ensures design consistency across all AI-generated changes.

FILE_STRUCTURE.md

Explains where files belong, so an AI tool placing a new component or content file doesn't have to guess — and doesn't quietly invent a new convention that only it knows about.

Example

components/ui
 
Reusable UI primitives.
 
components/marketing
 
Landing page sections.
 
components/docs
 
Documentation components.
 
content/marketing
 
Marketing page content.
 
content/docs
 
Documentation content.
 
lib/seo
 
SEO utilities.

This prevents AI from placing files in the wrong locations.

COMPONENT_RULES.md

Defines component development standards — the coding conventions that keep AI-generated components indistinguishable from hand-written ones.

Example

# Component Rules
 
- Use TypeScript.
- Export interfaces.
- Add JSDoc comments.
- Keep components reusable.
 
Never:
 
- Hardcode text.
- Hardcode SEO.
- Mix content with presentation.
 
Always:
 
- Use props.
- Use content files.
- Keep styling consistent.

SEO_ARCHITECTURE.md

Documents the project's SEO system, so an AI tool extends existing metadata and structured-data patterns instead of introducing a parallel, inconsistent one.

Example

# SEO Architecture
 
Global SEO:
content/seo/global.ts
 
Page SEO:
content/marketing/*.ts
 
Metadata Helper:
lib/seo/generateMetadata.ts
 
Structured Data:
components/seo/StructuredData.tsx
 
Sitemap:
app/sitemap.ts
 
Robots:
app/robots.ts

This helps AI follow existing SEO conventions.

CHANGELOG.md

The changelog acts as persistent memory for future AI sessions. Since AI tools don't retain memory between conversations, this file is what lets a new session pick up where the last one left off — including how to undo it if something needs to be rolled back.

Whenever modifications are made, a summary should be added to this file.

Example

# Changelog
 
## 2026-06-20
 
### Hero Component
 
Files:
 
- components/marketing/Hero.tsx
 
Changes:
 
- Added image column
- Improved CTA layout
- Added FadeIn support
 
Reason:
 
Improve visual hierarchy
 
Rollback:
 
hero-before-image-layout

Future AI sessions can read this file to understand previous changes.

DECISIONS.md

This file records key architectural decisions made during the development of this template.

Unlike CHANGELOG.md, which tracks what changed, this file tracks why decisions were made. It helps both developers and AI systems understand the long-term intent behind the codebase — so a future change doesn't accidentally undo a deliberate tradeoff made earlier.

Why This File Exists

In large SaaS templates, decisions are often made during:

  • Refactors
  • AI-assisted changes
  • Feature removals
  • Design system updates
  • SEO architecture changes

Without documentation, future changes may unintentionally break assumptions baked into earlier work. This file prevents that.

Format

## YYYY-MM-DD
 
### Decision
What was decided.
 
### Reason
Why this decision was made.
 
### Alternatives Considered
Other approaches that were rejected.
 
### Impact
What parts of the system this affects.

Example Decision

## 2026-06-20
 
### Decision
 
AI context files are stored in `/ai` instead of `/docs/ai`.
 
### Reason
 
Shorter path improves discoverability and reduces friction for AI tooling and developers.
 
### Alternatives Considered
 
- `/docs/ai`
- `/documentation/ai`
- `/meta/ai`

Relationship to Other AI Files

  • CHANGELOG.md → What changed
  • TASKS.md → What needs to be done
  • DECISIONS.md → Why things are the way they are

Together, these three files form the AI memory layer of the template.

TASKS.md

Acts as a lightweight project roadmap, giving an AI tool a sense of priority — what's already done and what's still open — without needing to scan the whole codebase to infer it.

Example

# Pending
 
- Improve pricing table
- Add docs search
- Create integration pages
 
# Completed
 
- Added SEO system
- Added sitemap support
- Added structured data

This helps AI understand current priorities.

PROMPT_TEMPLATE.md

Provides a standard workflow for AI agents — the sequence of steps a tool should follow on every task, so context is read in the right order and nothing important gets skipped.

Example

# AI Workflow
 
Before making changes:
 
1. Read:
   - PROJECT_CONTEXT.md
   - DESIGN_SYSTEM.md
   - FILE_STRUCTURE.md
   - COMPONENT_RULES.md
   - CHANGELOG.md
 
2. Follow architecture rules.
 
3. Preserve design consistency.
 
4. Update CHANGELOG.md.
 
5. Return:
 
   - Modified files
   - Summary of changes
   - Changelog entry

AI Instruction Files

Many AI coding tools can automatically load repository instructions. These are the entry points: short, tool-specific files that simply point back to the ai/ directory.

AGENTS.md

Recommended for general AI tooling.

# AI Agent Instructions
 
Read the following files before making changes:
 
- ai/PROJECT_CONTEXT.md
- ai/DESIGN_SYSTEM.md
- ai/FILE_STRUCTURE.md
- ai/COMPONENT_RULES.md
- ai/CHANGELOG.md
 
Always:
 
- Preserve architecture
- Follow design rules
- Follow file structure conventions
- Update CHANGELOG.md after modifications

CLAUDE.md

Used by Claude Code.

# Repository Instructions
 
Read ai/* before making modifications.
 
Follow all design and architecture rules.
 
Update CHANGELOG.md after completing work.

.github/copilot-instructions.md

Used by GitHub Copilot and supported tools.

# AI Instructions
 
Read:
 
- ai/PROJECT_CONTEXT.md
- ai/DESIGN_SYSTEM.md
- ai/COMPONENT_RULES.md
- ai/CHANGELOG.md
 
Follow project conventions.

Using AI Prompting

When working with AI, begin prompts with:

Read AGENTS.md and all files inside ai before making changes.

Or, for a lighter-weight task:

Read PROJECT_CONTEXT.md, DESIGN_SYSTEM.md, and CHANGELOG.md before proceeding.

This ensures the AI has access to the project's context before generating code, rather than improvising based on whatever it can infer from the surrounding files.

Recommended Workflow

  1. Define project rules inside ai/.
  2. Create AGENTS.md.
  3. Configure tool-specific instruction files.
  4. Ask AI to read project context before making changes.
  5. Require updates to CHANGELOG.md.
  6. Review generated code.
  7. Commit changes to source control.

Common Pitfalls

A few mistakes tend to undermine this system even when the folder structure itself is set up correctly:

  • Letting CHANGELOG.md go stale. If an AI session makes changes but doesn't log them, the next session inherits an incomplete picture — and the gap compounds with every skipped entry.
  • Treating DECISIONS.md as optional. Without it, future sessions (AI or human) may "fix" something that was actually a deliberate tradeoff, because the reasoning was never written down.
  • Duplicating rules across files. If DESIGN_SYSTEM.md and COMPONENT_RULES.md both try to define spacing conventions, they will eventually disagree. Each rule should have exactly one home.
  • Letting PROJECT_CONTEXT.md drift from reality. If the stack or architecture changes but this file isn't updated, every subsequent AI session starts from an inaccurate premise.
  • Skipping the read step in prompts. The structure only works if you (or your tool's default instructions) actually tell the AI to read ai/ first. Without that instruction, the files might as well not exist.

Best Practices

  • Keep documentation concise and up to date.
  • Store design decisions inside DESIGN_SYSTEM.md.
  • Document architecture inside PROJECT_CONTEXT.md.
  • Track modifications in CHANGELOG.md.
  • Use TASKS.md for ongoing work.
  • Avoid duplicating instructions across multiple files.
  • Treat ai/ as the single source of truth.

Following this structure allows AI tools to understand your project's design language, architecture, and history — resulting in more consistent, reliable code generation across every session, regardless of which AI tool you use.

NextScripts