Set up an agent-ready repo in 15 minutes

Introduction

An agent without context guesses. It guesses your package manager, your conventions, and which files are off-limits. Each wrong guess costs you a review cycle.

In this tutorial you'll add four small files to a repo. Together they make any agent start each session knowing your stack, your commands, your red lines, and the decisions you've already made.

What you'll build:

• A context file the agent reads automatically
• A commands section it can run without asking
• A short list of red lines
• A decisions log that carries context between sessions

Create the context file

Each agent looks for its standing instructions in a specific file. Pick the one your tool reads; the content is the same.

Create the file and start with two lines: what the project is, and what it's built with.

# Project: knsept-site
Astro static site + one Cloudflare Worker for the API. TypeScript everywhere.

Add the commands it can run

Agents verify their work by running things. Give them the exact commands, so they don't invent npm test in a repo that uses pnpm vitest.

## Commands
- Dev: `npm run dev`
- Build: `npm run build`
- Typecheck: `npx tsc -p worker`
- Never install packages with another package manager.

## Commands
- Dev: `pnpm dev`
- Test: `pnpm vitest run`
- Lint: `pnpm lint`
- Never use npm or yarn in this repo.

## Commands
- Run: `uv run main.py`
- Test: `uv run pytest -q`
- Add deps with `uv add`, never pip.

Write your red lines

Red lines are the few things that must never happen without you asking. Keep the list to five or fewer, so each one carries weight.

## Red lines
- Don't touch auth, billing or migrations unless the task says so.
- No new dependencies without asking first.
- If a change needs files outside the task's scope, stop and ask.
- Never commit secrets. Read them from env vars.

Add a decisions log

Sessions end and context resets. A decisions log is how the next session knows why things are the way they are. Create DECISIONS.md and point to it from the context file:

## Memory
Read DECISIONS.md before starting. Append a short entry when we decide something.

Each entry should be a few lines long:

## 2026-10-16 Signups stored in D1, not a third-party list
- Decided: D1 table `subscribers`, one row per email+list.
- Because: no vendor lock-in; export is one query.
- Watch out: the token doubles as the playbook access key.

Run your first mapped session

Test the setup with a real, small task, and make the agent map before it edits:

Before writing any code, map the territory for: add a "copied" toast to code blocks.
List the modules involved, every bridge this crosses, and anything you can't see both sides of.
Then stop and show me the map.

Check the map against what you know. If the agent named your real commands and respected the red lines, the setup is working.

Next steps

You now have a repo that briefs every agent session automatically. From here:

1. Read Map before you build to get more out of the mapping step.
2. Add the verification loop from the docs.
3. Follow the Ship with AI agents module to go further.