Try this if
- Your agent quietly drifts off what you agreed, and you only find out inside a decision you can't account for.
- You want a committed secret or a stray deploy stopped by a script, rather than by a line in a file an agent can reason its way around.
- You have a project that grew its own conventions and never wrote any of them down.
- Skip it if what you want is a framework installed or a requirements document written. This recipe writes the files an agent reads, never the project itself.
Every session with an agent starts from nothing. It opens your project the way a very good contractor opens a house he has never seen, entirely competent and entirely unbriefed, and gets to work. By the third session it has forgotten what you settled on Tuesday. It reformats a file you asked it to leave alone. It proposes the architecture you already ruled out.
The cost isn't the time it takes to put right. It's that none of it looks like failure while it's happening. The agent is confident, the work runs, and the drift only surfaces later inside a decision nobody can account for.
The answer turned out to be smaller than a better prompt. An agent reads certain files at the start of every session, and what is in those files is what it knows. All of it. So the job isn't to brief it better each time. It's to write those files once and keep them true, and every session after that opens from the same place.
None of it was designed up front, because the file set is an accumulation and every item in it is there because some project went wrong without it. The rule that a scaffolder must never write your content came from runs that improvised a stylesheet nobody asked for. The check that stops on a folder name one letter off came from a project that quietly misfiled documents for hours. Each rule learned in one project goes back into the thing that sets up the next, which is why this is a harness rather than a template, and why what it writes this year isn't what it wrote last year.
It asks before it writes, and your answers decide the shape
/context-engineering runs an interview and writes the file set at the end of it. The recipe at the bottom of this page runs a shorter version of the same interview, and it stops writing sooner.
The interview comes first. It asks what the project is, what you're building it with, where it deploys and what does the deploying, and whether a second tool is in play. The questions arrive one at a time. Then it states what it's about to generate and waits for you.
If you already wrote a requirements document, it reads that before anything else. The recipe asks you whether there is one and where. The full skill looks where /prd-creator, the recipe that interviews you and writes that document, puts it, and names what it finds, reading it only once you say yes. Either way, where your document answers a question it drafts the answer and shows you what it took, and where the document is silent it asks cold. So the smooth version on a project that doesn't exist yet is two recipes in a row. Talk out what you're building first, then scaffold around the document that came out of it. On a project that does exist, it reads the repo instead.
It decides whether your rules get a folder, and it decides from your answers. Four things can trigger the split, and every one of them is about the thing you're building rather than what you're building it with:
- it has two or more AI features of its own
- it has a design token file with a linter checking it
- it runs more than one distinct workflow
- it needs rules about voice
Any single one is enough. Below that bar the rules stay inline in one file, because a folder of two rule files for a single-workflow script is a second place to look and nothing else. When you do get the folder, the rules about committing and closing a session go in unscoped, so they load every session, and the rest name the paths they cover and stay out of the way until one is touched.
It uses the same shape four times, not once. The decisions log, the board, the session notes and the rules folder are each a thin index over one file per item. Scaffolding one of them that way and leaving the others as single growing files is the version of this that quietly stops working, so it does all four and tells you it did.
Most of what it does is refuse
It writes shape and never content. It won't author your design tokens, the named colors and sizes a project styles itself from, nor your requirements prose, nor your product vocabulary. On two separate validation runs, handed a brand book as source material, the agent improvised a tokens.css file nobody had asked for. That capability went off to become /design-system-bootstrap, the recipe that does build a token system, and this one got the prohibition in writing. The prohibition on its own wasn't enough, though, because it was already in force on both of those runs. What replaced it is a check of the literal path before every write, which fails on the first file outside the allowed set instead of asking the agent to remember a rule.
It never overwrites. A file that already exists is shown to you as a difference and waits for your consent. These are whole files rather than sections, so the choice is replace or leave, and leave is what happens if you say nothing. On one run the target project already held a requirements document written by the sibling recipe that produces them. The scaffold found the collision and asked.
It stops on a folder name that is nearly right. Before it writes the map of which document belongs where, it compares every folder already in your docs/ against every name it is about to route to. A singular against a plural, or a one-letter difference, is a question for you rather than something it settles quietly. That check exists because of a project holding a references folder of images and a routing target called reference. The generated map mentioned the collision in a footnote and routed past it anyway. The next document went into the wrong folder and nobody noticed for hours.
The hooks are the one thing it won't let you drop quietly. A hook is a script your tool runs at a fixed moment, before a commit or before a deploy, so a rule blocks instead of reminding. The default is on. Turning it off means naming what will enforce the rule instead. Two audited projects had written their failure modes down in careful prose and shipped no hooks at all. Nothing in either project made a rule fire.
What you get and what you don't
You get a file tree, and an agent that orients itself at the start of a session instead of asking you what the project is. You get the two or three rules that matter most as scripts that block rather than sentences that ask nicely. You don't get a working application or a design system.
You don't get the rules that will end up mattering, either. It fits what you give it and won't invent the rest, because a rule that hasn't yet cost anybody anything is a guess. The real ones arrive later, one at a time, each after something has gone wrong.
The recipe below is the smaller half. It writes the rules file, the tool pointer, the board, the decisions log, the session notes, the routing map, the permissions list, the hooks, and the topic rules when your project earns them. The full skill runs a longer interview and writes a good deal more from it. The structure of your requirements document and your architecture notes, filled from the answers it collects. A config file for Codex, if you named it. A topic rule for every AI feature you have and for your design system and your voice. The manifest that tells a session-opening routine where all of it lives. It also carries the templates and the worked examples a pasted prompt has no room for.
Run it against a project that already exists and has drifted, not only against a new one, and not only against an application. A folder of skills is a project. So is the system you run your own work out of. A scaffold laid over a year of accumulated habit mostly shows you what you have been doing without ever writing it down.
Then keep it moving. The rule each project teaches you is worth more in the thing that sets up the next one than in the project that earned it, which is what /mine is for and why this file set is not the one it was six months ago. Paste the recipe to try the shape tonight. The house the agent walks into is the one you left for it.
Take this spell for a spin
Paste this into your AI agent or a new chat. The post above says what it does. Some prompts set something up in your project that keeps working after, and others run once, right where you paste them. None of them pushes anything to a remote.
You are setting up the context files for a coding project I work on with an AI agent. The goal: every session on this project opens with the same picture of it, the rules, the open work and what was already decided, so the work does not drift from what we settled.
Before you write anything, ask me these and wait for my answers:
1. What the project is, in a sentence, and what I am building it with.
2. Whether I use more than one AI tool on it. Claude Code, Codex, Cursor.
3. Whether it deploys anywhere and to what, whether a push deploys it on its own or I run the deploy myself, and whether this project has a screen I look at in a running dev server before I commit a change to it. You need all three: the first two decide whether to write the hook that blocks the deploy tool's own command, and which command that is, and the third decides whether to write the one that blocks a second working copy.
4. Whether I already have a requirements document, and where. If I do, read it before you ask me anything else and use it to answer as much of the above as you can, then show me what you extracted rather than asking me again.
5. Four things about the project itself, asked together, because any one of them being true changes how the rules get organised: whether the thing I am building has two or more AI features of its own, counting them rather than taking a yes, whether it has a design token file with a linter checking it, whether it has more than one distinct workflow, and whether it needs rules about voice or tone. One AI feature on its own is not enough. My answer to question 2 is not the answer to this one. Which AI tools I write with and what I am building are different things, and only this question decides the shape.
6. Optionally, one rule I already know I want, in my own words. If I do not have one, do not press me for one and do not invent one. Most projects do not have a rule worth writing until something has gone wrong.
Then, using my answers, write these files and nothing else. Before you write any of them, show me the list of what you are about to create with one line each on what goes in it, and wait for me to say go. After that, write them all and show me the result, rather than stopping between each file.
- AGENTS.md at the project root. This is the canonical rules file. Open with what the project is, then the commands to install, run and check it, then a short list of the rules that must survive every session. Do not guess the commands. Read them out of package.json or its equivalent if one exists; if it does not, write the heading, leave the lines blank and tell me they are blank, because a wrong command written confidently is worse than an empty one. Keep it under 200 lines. If I gave you a rule in question 6, put it in, in my words.
- CLAUDE.md at the root, whose body is the single line `@AGENTS.md` under the generated-file comment every file here gets. That exact string is Claude Code's import syntax; a line of prose like "see AGENTS.md" looks the same to me and loads nothing, which is the one failure here I cannot detect by reading the file. If I named another tool with its own convention, add that tool's pointer too, in its own file.
- .claude/rules/ with one file per topic. Split by what the rule is about, not by how long the file is getting. Start with two, one for version control and deploying and one for how a session is scoped and closed, and write both of those as always-on, with no frontmatter naming paths, because they apply to everything I do. A rule that only applies to some of the project opens with a frontmatter block naming the file paths it covers, so the rule about styling is not loaded while the agent edits a build script. Tell me which of the two kinds you wrote. Write this folder only if something in my answer to question 5 was true. If none of it was, skip the folder and keep the rules inline in AGENTS.md instead. Tell me which shape you picked and which of the four triggered it.
- .claude/settings.json, whether or not I want hooks. It carries the list of commands my agent may run without stopping to ask me, and that list is reading commands only: git status, git diff, git log, grep, find, ls, cat, date, plus this project's own check and build commands if it has them. Nothing that writes, commits or pushes goes on it. If I want hooks, this is also the file they are registered in.
- BACKLOG.md at the root. One row per piece of open work, one line each, with a column for which lane it is in and a column for order. This file is an index and nothing else. When a row needs more than its one line, move the detail into its own file under docs/tickets/ and leave the row pointing at it. Create docs/tickets/ now with a short README saying what lands there, for the same reason docs/decisions/ gets one: a folder holding nothing does not survive a clone, and this board is pointing at it from the day it is written.
- docs/DECISIONS.md. An index. The first section is a short block of the constraints still binding right now, one line each. Below it, a table with one row per decision. Each decision gets its own file at docs/decisions/, named with the date and a slug, holding the context, the call and the reason. Do not leave docs/decisions/ empty: an empty folder is invisible to git and vanishes the first time this is cloned, so either write the first real decision into it or put a short README there saying what goes in it.
- docs/retros/ with a README that does two jobs: the format a session note follows, which is what was done, what was verified and how and what is still open, plus an index of the notes written so far.
- docs/README.md, one page saying which kind of document belongs in which folder under docs/, so a new file has an obvious home instead of landing loose at the top. Route at least these: decisions, retros, tickets, reference, research, audits. Before you write the page, list every folder already in docs/ and compare each one against every name on that list rather than against a shorter set of your own. A near-match instead of an exact one, a singular against a plural or a one-letter difference, is a stop: tell me both names and ask which wins. Do not resolve it yourself and do not write a page that routes to one name while mentioning the other, which is how two folders a letter apart end up collecting misfiled documents forever.
Write hooks too, unless I tell you not to. A hook is a script my tool runs at a fixed moment without being asked, so a rule blocks instead of reminding me it exists. Write the ones my answers call for: one that refuses to stage a .env file, always; one that refuses the deploy tool's own command line, if I said a push deploys on its own, because running it by hand opens a second way to deploy that nobody is watching; one that refuses to create a git worktree, if this project has a screen I confirm changes on in a running dev server, because a worktree is a second copy of the files and the dev server is not pointing at it. If I named a rule in question 6 and a hook could enforce it, write that one too. Register them in the settings file, make them executable, and tell me in plain words what each blocks and when. An unexecutable hook sits there looking correct and never fires, which is worse than not having it. If I say I do not want hooks at all, ask me what will enforce the rules instead and write my answer into AGENTS.md.
The decisions, the retros and the board are deliberately the same shape: a thin index plus one file per item. So is the rules folder, when the project is getting one. Keep them that way and say so when you show me the tree, naming however many of them this project ended up with, because the pattern is the thing that stops any of them growing into a file nobody rereads.
Rules for you while you do this:
- Write shape, not content. Do not author my design tokens, my requirements prose or my product vocabulary. Where content belongs, write the heading and leave it for me.
- Check every path before you write to it. It has to sit under .claude/, .codex/ or docs/, or be one of AGENTS.md, CLAUDE.md or BACKLOG.md. Test the path itself rather than deciding whether it feels like product code. If something I gave you implies a file outside that list, do not write it. Name it and leave it to me.
- Never overwrite a file that already exists. Show me the difference, tell me it is already there, and ask whether to overwrite it or leave it. Leave it unless I say otherwise. These are whole files rather than sections, so do not offer to merge them or to append anything to the existing one.
- Every file you write opens with a comment saying it was generated and can be hand-edited.
- Do not create a file you cannot say the purpose of in one line.
When they are written, list every file you created and every one you left alone because it already existed, with the reason for each one you skipped. Do not commit anything and do not stage anything. What goes into version control is my call on my own history.
Then tell me which of these files an agent will load on every session and which wait to be opened, because that distinction is the whole point and I will forget it.