Free guide · Nov 3, 2026

How to Actually Code Using AI: The Context Kit

Four small markdown files that live in your repo, so your AI coding agent stops starting from zero every session. Works with Claude Code, Codex, Cursor, GitHub Copilot, Windsurf, and similar tools.

AGENTS.md

Tech stack, conventions, project structure, rules

Update: When your stack or rules change

FLOW.md

How the app works end to end: requests, APIs, data

Update: When you add a feature or service

DECISIONS.md

Why you chose X over Y, and what you rejected

Update: Every time you make a technical choice

PLAN.md

The steps for the feature you're building right now

Update: Before every new feature

Where are you starting?

Pick one to see your prompt.

Start a new project with AI as your architect

Use this when you're starting from an idea, not existing code. The AI interviews you, recommends options with pros and cons for every big choice, lets you pick, and only then writes all four files.

new-project-prompt.txt

You are my senior software architect. I want to build a new project, and together we'll create four context files: AGENTS.md, FLOW.md, DECISIONS.md and PLAN.md. Don't write any code or files until I say so.

Work in three phases.

PHASE 1: UNDERSTAND THE IDEA
- Ask me to describe what I want to build.
- Then ask follow-up questions ONE AT A TIME until you clearly understand: who it's for, the main features, what a user does from start to finish, expected scale (users, data), my skill level and the languages I know, budget, and deadline.
- Keep questions short. Where it helps, suggest example answers I can pick from.
- When you understand the idea, summarize it in 5 to 8 bullet points and ask me to confirm or correct it. Don't move on until I confirm.

PHASE 2: MAKE THE DECISIONS TOGETHER
Go through each technical decision ONE AT A TIME, in this order: frontend, backend, database, auth, hosting/deployment, styling, testing, and anything else this project specifically needs (payments, file storage, real-time, AI APIs, etc.).

For each decision, show:
- 2 or 3 realistic options
- For each option: pros, cons, cost, and how hard it is for someone at my skill level
- Your recommendation for MY project and why, in one or two lines
Then ask me to choose. If I'm unsure, help me decide with one more question. Remember what I picked AND what I rejected, with the reasons.

After all decisions, show a one-screen summary of the full stack and ask me to confirm.

PHASE 3: WRITE THE FILES
Once I confirm, create these files in the project root. Start every file with a 1 to 2 line description of what the file is for and when to update it.

1. AGENTS.md: tech stack with versions, planned folder structure (one line per folder), commands to install/run/test/build, coding conventions for this stack, and a Rules section. Include the rule: "Read FLOW.md and DECISIONS.md before making architectural changes, and always create a plan in PLAN.md before building a feature."
2. FLOW.md: how the app will work end to end, as numbered steps. Trace the main user action from UI to backend to database and back. List the planned API endpoints, the auth flow, and any external services.
3. DECISIONS.md: one entry per decision from Phase 2 with today's date, what we chose, why, and the rejected options with the reason for each. End with a "Do not suggest" list of the options I rejected.
4. PLAN.md: a plan for the first milestone only (project setup + the first core feature), with goal, approach, files to create, a task checklist of small testable steps, and open questions.

After writing the files, list anything you assumed so I can check it, then stop and wait. Don't start coding until I approve PLAN.md.

Tip: if you already know some answers ("I want Next.js and Supabase"), say so in your first reply and the AI will skip those decisions.

Your project root will look like this:

your-project/

your-project/
├── AGENTS.md
├── FLOW.md
├── DECISIONS.md
├── PLAN.md        ← created per feature (see below)
└── src/ ...

Each file below has a ready-to-paste prompt that makes the AI write it for you, plus a template if you'd rather fill it in yourself.

AGENTS.md: the instruction manual

AGENTS.md is the first file your AI reads. It tells the AI how this project works and how you want code written, so you stop repeating yourself every session.

What to put in it

Tech stack and versions
Project structure: which folder holds what
Commands to install, run, test and build
Coding conventions: naming, formatting, patterns to follow
Rules: things the AI must always or never do

AGENTS.md prompt

Read this codebase and create AGENTS.md in the project root. Include: tech stack with versions, folder structure with one line per important folder, commands to install, run, test and build, the coding conventions you can see in the code, and a "Rules" section. Only include what you can confirm from the code. Mark anything unsure as "TODO: confirm". Keep it under 150 lines.

Prefer to fill it in yourself? Show the template

AGENTS.md

# AGENTS.md

## Tech stack
- Frontend: React 18 + TypeScript, Tailwind CSS
- Backend: Node.js 20, Express
- Database: PostgreSQL 16 with Prisma
- Hosting: Vercel (frontend), Railway (backend)

## Project structure
- /client: frontend app
- /server/routes: API route handlers
- /server/services: business logic
- /server/prisma: database schema and migrations

## Commands
- Install: npm install
- Run locally: npm run dev
- Test: npm test
- Build: npm run build

## Conventions
- camelCase for variables and functions, PascalCase for components
- Keep business logic in /services, not in routes
- Use async/await, never .then() chains

## Rules
- Always run tests before saying a task is done
- Never edit migration files that are already committed
- Ask before adding a new dependency
- Read FLOW.md and DECISIONS.md before making architectural changes

The last rule matters. It tells the AI to read your other two files before big changes.

FLOW.md: how your app actually works

FLOW.md shows the AI the big picture in one read. Without it, the AI only sees the few files it opened and misses how they connect, which is where most broken changes come from.

What to put in it

How a request travels from frontend to backend to database and back
Main API endpoints and what each one does
How services or modules talk to each other
Auth flow: login, tokens, protected routes
Background jobs, queues, webhooks, third-party APIs

FLOW.md prompt

Trace how this application works end to end and write FLOW.md in the project root. Pick the most important user action (e.g. sign up, place an order) and describe every step from the UI click to the database and back, naming the actual files and functions involved. Then list the main API endpoints with one line each, the auth flow, and any background jobs or external services. Use numbered steps. Only describe what's in the code.

Prefer to fill it in yourself? Show the template

FLOW.md

# FLOW.md

## Main flow: user places an order
1. User clicks "Checkout" in client/pages/Cart.tsx
2. Frontend calls POST /api/orders with the cart items and auth token
3. server/middleware/auth.ts verifies the JWT
4. server/routes/orders.ts validates the request body
5. server/services/orderService.ts checks stock and calculates the total
6. Payment is created through the Stripe API
7. Order is saved to the orders table via Prisma
8. A job is added to the queue to send the confirmation email
9. API returns the order ID and the frontend shows the success page

## API endpoints
- POST /api/auth/login: returns a JWT
- GET /api/products: list products with pagination
- POST /api/orders: create an order
- GET /api/orders/:id: order details (owner only)

## Auth
- JWT in an httpOnly cookie, expires after 7 days
- Protected routes use the requireAuth middleware

## External services
- Stripe: payments
- Resend: emails
- Redis + BullMQ: background job queue

DECISIONS.md: why you built it this way

DECISIONS.md stops the AI from suggesting things you already considered and rejected. It records what you chose, why, and what you said no to.

What to put in each entry

The decision: what you chose
Why: the reasoning, in one or two lines
Rejected: the alternatives you considered and why not
Date: so you know how old the decision is

DECISIONS.md prompt

Create DECISIONS.md in the project root. Look at the codebase and list the main technical choices: database, framework, ORM, auth, hosting, state management, styling, testing. For each, write the decision and the likely reason, marked "(inferred, confirm)". Then ask me, one at a time, why I made each choice and what alternatives I rejected, and update the file with my answers.

Add a decision later (use after any big choice)

Add a decision

We just decided to [decision]. Add an entry to DECISIONS.md with today's date, the reasoning we discussed, and the alternatives we rejected.

Prefer to fill it in yourself? Show the template

DECISIONS.md

# DECISIONS.md

## PostgreSQL instead of MongoDB (2026-03-10)
- Why: our data is relational (users, orders, products) and we need joins and transactions for payments
- Rejected: MongoDB (weak multi-document transactions for our use case), MySQL (team knows Postgres better)

## Docker for local development (2026-04-02)
- Why: same environment for every developer; Postgres and Redis start with one command
- Rejected: installing services locally (version mismatches between machines)

## REST instead of GraphQL (2026-04-15)
- Why: simple CRUD app, small team, easier caching
- Rejected: GraphQL (extra complexity we don't need yet)

## Do not suggest
- Switching to a NoSQL database
- Adding Redux; React Query + context is enough for us

The "Do not suggest" list is the fastest way to stop repeat suggestions.

PLAN.md: plan first, then code

Before any feature, make the AI write a plan and wait for your OK. You see every file it will touch before it touches anything, and you catch wrong approaches when they cost nothing to fix.

The workflow

Describe the feature and ask for a plan, not code (prompt below).
Read PLAN.md. Check the files it lists and the approach it picked.
Push back on anything wrong: "Don't add a new table, reuse orders".
Approve and let it build one task at a time, ticking tasks off as it goes.
When the feature is done, update FLOW.md and DECISIONS.md if anything changed, then delete or archive PLAN.md.

Create the plan

PLAN.md prompt

I want to build: [describe the feature].

Don't write any code yet. First read AGENTS.md, FLOW.md and DECISIONS.md. Then create PLAN.md with:
- Goal: one or two lines on what this feature does
- Approach: how you'll build it and why
- Files to change or create, with one line on what changes in each
- Tasks: a checklist of small steps, each one testable on its own
- Risks and questions: anything unclear or that could break existing features

Stop after writing PLAN.md and wait for my approval.

Start building

Plan approved. Work through PLAN.md one task at a time. After each task, run the tests, tick it off in PLAN.md, and tell me what changed. Stop and ask if you need to do anything that isn't in the plan.

Prefer to fill it in yourself? Show the template

PLAN.md

# PLAN.md: Add password reset

## Goal
Users can reset a forgotten password through an emailed link.

## Approach
Signed token stored in a new password_resets table, expires in 30 minutes. Reuse the existing Resend email service.

## Files
- server/prisma/schema.prisma: add PasswordReset model
- server/routes/auth.ts: add POST /forgot-password and POST /reset-password
- server/services/authService.ts: token creation and validation
- client/pages/ForgotPassword.tsx: new page
- client/pages/ResetPassword.tsx: new page

## Tasks
- [ ] Add PasswordReset model and migration
- [ ] Token create and validate functions + tests
- [ ] API endpoints + tests
- [ ] Email template
- [ ] Frontend pages
- [ ] End-to-end test of the full flow

## Risks and questions
- Should old sessions be logged out after a reset?
- Rate limit the forgot-password endpoint to stop email spam

Keep it working

Out-of-date context is worse than none, because the AI will trust it. After each feature, paste this:

After each feature

We just finished [feature]. Check whether AGENTS.md, FLOW.md or DECISIONS.md are now out of date. Show me the changes you'd make, then update the files after I approve.

Making sure your tool reads the files

Codex, Cursor, GitHub Copilot and most other agents read AGENTS.md from the project root automatically.
Claude Code reads CLAUDE.md instead. Create a CLAUDE.md that contains one line, @AGENTS.md, and Claude Code will load your AGENTS.md from it.
FLOW.md and DECISIONS.md aren't loaded automatically by any tool. The "Read FLOW.md and DECISIONS.md" rule in AGENTS.md is what makes the AI open them.
If you're unsure, start a new chat and ask "What does AGENTS.md say about our rules?" If it can't answer, the file isn't being loaded.

Setup checklist

Run the setup prompt and answer its TODOs
Read through AGENTS.md and add your own rules
Add your real reasons and rejected options to DECISIONS.md
Add CLAUDE.md with @AGENTS.md if you use Claude Code
Commit all the files to git
Use the plan-first prompt for your next feature

Want more AI tools like this? Follow me

Instagram YouTube LinkedIn GitHub

How to Actually Code Using AI: The Context Kit

Where are you starting?

Start a new project with AI as your architect

Set up everything in one prompt

AGENTS.md: the instruction manual

What to put in it

FLOW.md: how your app actually works

What to put in it

DECISIONS.md: why you built it this way

What to put in each entry

Add a decision later (use after any big choice)

PLAN.md: plan first, then code

The workflow

Create the plan

Start building

Keep it working

Making sure your tool reads the files

Setup checklist

Want more AI tools like this? Follow me

More from me

AI Stickman Videos

Override

All projects