The 5-file starter pack for AI coding
Five concise project files that give a coding agent stable product context, technical decisions, working rules and next steps.
Every new coding-agent session starts with only the context it can see. The model may have the same capabilities, but it does not automatically carry every product decision, failed experiment or next task from your previous conversation.
A real team solves this with durable project documents. These five files give an agent the same kind of briefing: what you are building, how it is put together, how work is done, what comes next and how to run it.
The exact filenames are flexible. Their responsibilities are not.
The one-hour plan
Write them in this order. The order keeps product intent ahead of implementation, implementation ahead of working rules, and working rules ahead of the task queue.
| Minutes | File | The question it answers |
|---|---|---|
| 0 to 15 | PRD.md |
What are we building, and what are we deliberately not building? |
| 15 to 35 | ARCHITECTURE.md |
How is it put together, and what has already been decided? |
| 35 to 45 | Tool instruction file | How should an agent work in this repository? |
| 45 to 55 | TASKS.md |
What is next, in order? |
| 55 to 60 | README.md |
How does somebody run and operate this project? |
Two rules decide whether the pack works.
First, short beats exhaustive. A document that hides its important rule inside twenty pages is poor context. Second, treat the first draft as a hypothesis. Correct it from the real code and update it when the project changes.
Already have a half-built app? Do not write from memory. Later in this article you will find one prompt per file that asks the agent to draft from repository evidence and mark unknowns instead of guessing.
File 1, PRD.md defines what and why
The product requirements document keeps the product boundary visible when somebody is tempted to add one more feature. One page is enough for an early project.
# [App name]
## What it is
[One paragraph describing what it does and for whom.]
## Who it is for
- Primary user: [who they are and what they need to accomplish]
- Not for: [the audience or job this version deliberately does not serve]
## Core features, ranked
1. [The capability that must work]
2. [ ]
3. [ ]
4. [ ]
5. [ ]
## Not building in this version
- [ ]
- [ ]
- [ ]
## Done looks like
[One sentence a stranger could verify, such as: A user can add an expense on a phone
and see it included in this month’s total.]
The “Not building” section often creates the most value. An expense tracker might say no multiple currencies, team accounts, receipt scanning, budgets or bank sync in its first version. Each line protects the core from a week of accidental scope.
You know the file is working when “Does this feature fit the PRD?” can stop work that does not serve the current product. It needs attention when shipped behavior contradicts it.
File 2, ARCHITECTURE.md records how it is built
Architecture is the set of technical boundaries and decisions that should not be reinvented in every conversation. Keep it concise and factual.
# Architecture
## Approved stack
- Frontend: [tool and version]
- Backend: [tool and version]
- Database: [tool and version]
- Authentication: [tool and version]
- Hosting: [provider]
- Payments, email and storage: [providers in use]
Ask before changing this stack.
## How data flows
[One representative path, such as: form submission -> validate -> API -> database ->
response -> update the interface]
## Where things live
- [folder] -> [what belongs here]
- [folder] -> [what belongs here]
Anything that fits nowhere should trigger a design conversation before creating a new
home.
## Decisions already made
| Decision | Reason | Avoid |
| --- | --- | --- |
| [Dates are stored in UTC] | [The verified reason] | [Do not store local time] |
| [ ] | [ ] | [ ] |
## Known rough edges
- [A specific compromise that exists today and the evidence for it]
The decisions table stops architectural drift, which is when different sessions solve the same problem in incompatible ways. Record the decision and the reason you actually know. If the reason cannot be recovered, write “reason not recorded” rather than inventing one.
The file needs attention when its versions, boundaries or data flow no longer match the code.
File 3, the tool instruction file defines how to work
This is the file a coding tool loads as project guidance. The name depends on the tool:
AGENTS.md, CLAUDE.md, Cursor project rules and other systems use different entry
points. Use the file your tool actually reads, and keep it focused on how work happens
in this repository.
# How to work in this project
## Commands
- Development: [project command]
- Test: [project command]
- Build: [project command]
- Deploy: [project command or documented manual process]
## Rules
- Stay inside the requested scope.
- Read the product and architecture documents before planning a feature.
- Prefer the approved stack and existing project utilities.
- Ask before changing dependencies, data models, authentication or infrastructure.
- Never print or commit secret values.
- Preserve unrelated working tree changes.
- Read the diff and run relevant checks before claiming completion.
## Never do this
- Never hide a skipped or failing check.
- Never make a destructive or irreversible change without explicit approval.
- Never invent a second pattern when the architecture already records one.
- Never turn unrelated cleanup into part of a focused fix.
## Workflow
1. Read the current task and relevant project context.
2. State the scope, assumptions and checks.
3. Build the smallest coherent slice.
4. Run the relevant verification.
5. Update any project document this change made inaccurate.
Commands save typing. The “Never” list saves recovery time. Every rule should answer a real failure mode, not express a vague preference.
File 4, TASKS.md records what is next
The task file prevents every session from beginning with a new guess about priority. Keep current work small and ordered. Move completed work out of the active list while preserving enough history to see progress.
# Tasks
## Now
- [ ] [One task with a testable finished state]
- [ ] [ ]
- [ ] [ ]
## Next
- [ ] [ ]
- [ ] [ ]
## Later or maybe
- [ ] [Ideas that are deliberately not active]
## Done
- [x] [Completed task and date]
If you cannot describe the finished state in one sentence, the task probably needs to be split. “Build the dashboard” is not a useful unit. “Show this month’s total at the top of the dashboard” is observable and bounded.
The file needs attention when completed items remain at the top. An agent that trusts the queue may otherwise repeat finished work.
File 5, README.md explains how to run it
The README is for future you, collaborators and tools diagnosing an environment problem. A newcomer should be able to start the project without a private explanation.
# [App name]
[One sentence describing the project.]
## Run it locally
1. [Clone the repository]
2. [Install dependencies]
3. Copy the example environment file to the local environment file
4. Fill in the required values using the sources below
5. [Run the development command and open its local address]
## Environment variables
| Name | Purpose | Where to obtain it |
| --- | --- | --- |
| [DATABASE_URL] | [ ] | [ ] |
| [PAYMENT_SECRET_KEY] | [ ] | [ ] |
Record names only. Never put secret values in this file.
## Deploy
- Host: [ ]
- Deployment process: [ ]
- Rollback process: [ ]
## Gotchas
- [The specific requirement that would waste a newcomer’s first hour]
The rollback line is easy to skip and valuable when a release fails. Write it while the system is healthy. Test the setup on a fresh checkout occasionally, because copied setup instructions can drift even when the application still works on your machine.
How the five files work together
At the start of a session:
Read the project instruction file and TASKS.md. Take the first active task that matches
my request. Tell me the scope and the checks before changing anything.
Before adding a feature:
Read PRD.md. Does [feature] fit the audience, core features and current exclusions? If
it conflicts, show me the conflict and wait for a product decision.
When the implementation starts to drift:
Read ARCHITECTURE.md. Does this approach contradict a recorded boundary or decision?
Quote the relevant rule and propose the smallest compliant approach.
At the end of a session:
Update the task status, then tell me whether this change made PRD.md, ARCHITECTURE.md,
the project instructions or README.md inaccurate. Propose only the necessary edits.
The maintenance rule is simple:
| What changed | Update |
|---|---|
| You accepted or rejected a product capability | PRD.md |
| You chose or replaced a technical boundary | ARCHITECTURE.md |
| You learned a durable working rule | The tool instruction file |
| You started or finished planned work | TASKS.md |
| You changed setup, configuration names or deployment | README.md |
Update the document in the same change that makes it inaccurate. Engineers call this keeping documentation atomic with code. The review then sees the behavior and its updated explanation together.
Generate the files from an existing codebase
If the app already exists, ask the agent to draft from evidence. Run these prompts one at a time and review each result.
Draft PRD.md
Inspect this codebase and draft a one-page PRD.md.
Use repository evidence to describe what the app does, its apparent primary user and
its central capabilities. Separate explicit exclusions from your inferences. Mark every
uncertain product claim [CONFIRM] instead of guessing. Do not change code.
Code can show what exists, but it cannot always reveal who the product is for or what was deliberately rejected. Those claims need a person or an existing product record.
Draft ARCHITECTURE.md
Inspect manifests, configuration and representative code paths. Draft a concise
ARCHITECTURE.md with the exact stack versions, boundaries, folder responsibilities and
one verified data flow.
List important technical decisions that are directly supported by code or existing
records. Mark the reason [CONFIRM] when it is not documented. Do not infer intent from
an implementation choice alone. Do not change code.
Draft the project instruction file
Inspect package scripts, existing instructions and repeated code conventions. Draft
the instruction file for [tool]. Include verified development, test, build and deploy
commands. Describe conventions that are consistently present, not preferences you
would introduce.
Leave a proposed rule marked [CONFIRM] when the evidence is weak. Never print secret
values. Do not change application code.
Draft TASKS.md
Inspect explicit TODO markers, current planning records, failing checks and clearly
unfinished user flows. Draft a TASKS.md that cites the evidence for every item.
Do not treat every hardcoded value, missing catch block or unconventional pattern as a
bug. Separate confirmed work from possible review findings, and do not change code.
Draft README.md
Inspect the project scripts, example configuration and deployment records. Draft a
concise README.md with the verified local setup, environment variable NAMES and their
purposes, deployment process, rollback process and known setup problems.
Never print or copy an environment variable value, credential or token. Mark missing
information [CONFIRM] instead of guessing. Do not change code.
Then audit the pack:
Compare PRD.md, ARCHITECTURE.md, the project instruction file, TASKS.md and README.md
with the current repository.
For each file, report:
1. statements contradicted by code or another authoritative record,
2. missing information the file is responsible for,
3. duplicated material that should have one owner,
4. sections long enough that the important rule is hard to find.
Do not rewrite anything until I review the findings.
Run the audit after meaningful product, architecture or setup changes. The goal is not more documentation. The goal is reliable context.
What not to put in these files
The common failure is not only a missing file. It is a bloated, duplicated or stale one that people and agents stop trusting.
| File | Keep out |
|---|---|
PRD.md |
Implementation details, interface copy and undocumented guesses |
ARCHITECTURE.md |
Tutorials, generated diagrams nobody owns and copied code that will drift |
| Tool instruction file | Material already owned by another document, link to it instead |
TASKS.md |
Vague work, duplicate ideas and findings with no evidence |
README.md |
Secret values, private credentials and obsolete setup steps |
Do not turn current-state documents into diaries. Git already preserves their history. Keep each file responsible for the state somebody needs now.
Where the pack lives in different tools
The approach is tool independent. Only the automatically loaded instruction file and its supported scope change.
| Tool | Project instruction location | Other project documents |
|---|---|---|
| Claude Code | CLAUDE.md |
Use the project’s established locations |
| Codex | AGENTS.md |
Use the project’s established locations |
| Cursor | Project rules under .cursor/ |
Reference the other documents from the rule |
| Windsurf | Its supported project rules file | Reference the other documents from the rule |
| Tools without automatic project files | A documented session starter prompt | Keep the documents in the repository |
Check your tool’s current documentation before relying on a filename or precedence rule. In a monorepo, broad rules belong at the root and workspace-specific rules belong near the code they govern.
Why this works
The model is not forgetting because it suddenly became weaker. It can only reason from the context available in the current task. Project files change that context from “whatever somebody remembered to repeat” to a stable briefing that travels with the code and can be reviewed by the whole team.
That is what experienced teams gain by writing decisions down. They are not removing the need for judgment. They are making sure the next decision starts from the same known ground.
Common questions
- Do I need these exact five filenames?
- No. The responsibilities matter more than the names. Match the instruction filename your tool reads automatically and keep product, architecture, work queue and setup information wherever your team already maintains them.
- Should every file live in the repository root?
- Start there for a small project. In a monorepo or large codebase, keep broad rules at the root and place narrower instructions near the workspace they govern so the context stays relevant.
- Should an AI generate all five files for me?
- It can draft them from repository evidence, but you must review assumptions and product claims. Mark unknowns instead of letting a confident guess become a permanent project rule.
- Is stale documentation better than no documentation?
- Not always. Stale commands and architecture claims can mislead both people and agents. Keep each file short, assign it a clear responsibility and update it in the same change that makes it inaccurate.
Keep reading
20 things AI leaves out of the login it built you
The gaps AI leaves in auth, from email verification to password reset and sessions, each with a copy-ready prompt and a browser check that proves it works.
Your AI agent is stuck in a loop: 12 prompts that break it
Twelve copy-ready prompts for when your AI agent keeps saying it fixed the bug and ships the same fix, cheapest first, each with a way to tell it worked.
12 security holes AI leaves in your app, and how to close them
A copy-ready prompt to close each of the twelve security holes AI leaves in most apps, and a browser check under each one to prove it actually shut.