Your repo is your AI’s memory.
Give it a decent one.

Open the folder. Have a look around.

I’ve put the example files in a starter you can explore here and download below. Click any filename to see what it is for and read a sample file. Each view adds to the last: “Add team docs” keeps the basics, and “Explore agent setup” adds nested instructions under app/.

# Working agreements

## Start here
- Read README.md for setup and verified check commands.
- Inspect recent Git commits, git status, and the staged and unstaged diffs for context.
- Check untracked files too. Verify commit messages against the current code.
- Read the PRD named in the request and any linked issue or pull request.
- Use docs/product.md for the user, scope, and definition of success.
- For interface work, read DESIGN.md; for system changes, read docs/architecture.md.
- For contributions, read CONTRIBUTING.md.
- For feature work, read the relevant plan in docs/prds/ and checks in docs/evals.md.
- For application work, read app/AGENTS.md; for billing, also read
  app/billing/AGENTS.md. These paths are relative to the repository root.

## While working
- Make the smallest change that satisfies the agreed task.
- Keep files focused; split unrelated responsibilities when a file becomes hard to follow.
- Trace the existing flow before choosing where to edit.
- Add tests for changed behaviour under tests/ using the project's existing framework.
- State assumptions. Ask when a missing decision materially changes scope.
- Follow existing patterns. Explain before adding a new dependency.
- Keep credentials and customer data out of code, docs, and examples.
- Work on a branch from the latest main. Land changes through a pull request.
- Never force-push or rewrite published history.

## Before handing over
- Run the relevant checks documented in README.md. Never claim an unrun check passed.
- If no automated checks exist, describe the manual verification and its limits.
- Keep useful reasons and verification results in commit messages and pull requests.
- Record open questions in the relevant PRD, issue, or pull request.
- Record a consequential decision in docs/decisions/ with its reason.
- Update a rule only when the working agreement actually changes.

These are instructions, not access controls. Configure repository protections,
permissions, and checks separately where enforcement matters.

You don’t need every file on day one. Keep the files you actually need. No one gets extra points for empty files. Every extra document needs someone to keep it current; an outdated plan can send the next person or agent in the wrong direction.

What each file is doing here

The .md ending means Markdown: plain text with simple formatting. A # makes a heading; a dash makes a list. You can write all of this in ordinary English. Here’s the question each file answers in this example.

README.mdWhat is this, and how do I run it?

The team’s starting point. I’ve kept it at the root, meaning the top level of the project folder, so it’s easy to find. It should explain the project, link to the docs, and give setup commands you’ve actually checked.

AGENTS.mdHow should an agent work here?

The working agreements an agent needs: which docs to read, how to check changes, and what to do before handing over. Codex uses this filename for project instructions.

CLAUDE.mdWhat should Claude Code read?

Claude Code’s instruction file. This starter uses @AGENTS.md to import the shared rules. Sometimes I just create a symlink instead, so CLAUDE.md points to AGENTS.md. Either way, I have one set of rules to keep up to date. How imports work.

docs/product.mdWho is this for, and what are we building?

This gives anyone opening the folder context about its job: what product or capability it powers and who it serves. I’ve put the current scope and what comes next here too, including what we’re leaving out. “Everything, eventually” is how a to-do app acquires a payroll department.

As the project grows

CONTRIBUTING.mdHow do I make a change?

The contributor’s guide explains how this team proposes, checks, and reviews changes. In this example, you work on a branch, a separate line of development, then open a pull request (PR) so the team can review the change before adding it to the shared version.

docs/architecture.mdHow do the pieces connect?

A map of how the product’s parts connect, such as the interface, server, and storage. A simple sketch may be enough. The useful distinction is what exists today and what is still a plan.

DESIGN.mdHow should this look and feel?

A place for visual choices and interaction patterns, including error states and accessibility. The example instructions point here before interface work, so each new session can build on the same design decisions.

docs/decisions/Why did we choose this?

Short records of choices whose reasons would be painful to rediscover. Alternatives and tradeoffs help the next teammate understand why the obvious option may have been ruled out.

docs/prds/What are we changing next, and why?

PRD means product requirements document: a plan for a feature or substantial change. These examples describe the problem, what to build, and how to tell whether it works. Their status makes it clear that the features are still proposals.

docs/evals.mdHow will we know it works?

A place to describe realistic scenarios, expected results, and what happened when you checked. AI features may also need output examples and a scoring rule. This records the evaluation plan and results; it does not run the checks itself.

tests/What can we check automatically?

Checks the computer can run have their own folder. They might check that a form rejects an invalid email address or records a signup only once. The starter has three tests marked TODO: placeholders that don’t check anything yet. Replace them with real tests; an empty check proves very little.

.gitlab-ci.ymlWho runs the checks when code changes?

CI means continuous integration. This file configures GitLab’s automated checks. GitHub Actions uses workflow files such as .github/workflows/ci.yml, with different syntax. The starter’s CI example is disabled until real tests exist. GitLab configuration · GitHub workflows.

docs/runbooks/How do we do this safely again?

Instructions for a procedure someone will need to repeat, such as releasing a new version. The example covers what to prepare, how to check the result, and what to do if something goes wrong. The commands need to be tested before anyone relies on them.

CHANGELOG.mdWhat changed for people using the product?

A release history for people using the product. It describes new capabilities and fixes; Git keeps the individual code changes.

For a starter this size, I’ve kept the document map in the root README.md. Links there are enough to find the docs and PRDs. The principle is to give people a clear way in and avoid maintaining several copies of the same information.

One product, more than one PRD

Say you’re building a waitlist feature for an upcoming course: a form where visitors leave their email address to register interest before booking opens. docs/product.md explains the overall product; docs/prds/001-waitlist.md plans this first feature, including what happens when someone submits the form.

Later, you want each visitor to receive an email confirming that their interest was recorded. That gets its own plan, docs/prds/002-email-confirmation.md, which links back to the first PRD. The product brief stays current, while each PRD records the thinking behind a particular change. You can open both examples in the explorer above.

Once a feature is available to users, update the product brief and mark its PRD “shipped.” Link the pull request back to the plan and record the checks in docs/evals.md, so someone can follow the work without asking for its whole history. If a new plan replaces an old one, mark the old one “superseded” and link to its replacement. A typo fix does not need its own PRD.

For those confirmation emails, the evaluation sample asks: does a signup trigger one message? Does retrying the same request send duplicates? What happens if the email service is down? It also checks that the message doesn’t promise a course date or seat that hasn’t been confirmed. These checks are all marked “not run” in the starter. If you automate them later, keep the checks and their sample inputs in a folder such as evals/ and link to them.

Agents recognise instruction files by name, so use the exact spelling AGENTS.md and CLAUDE.md. README.md is the usual starting point for people. Names such as DESIGN.md, product.md, and architecture.md are choices your team makes; link them from the instructions rather than assuming the agent loads them. You could keep design notes in DESIGN.md at the root or in docs/design.md. What matters is that your team knows where to find them.

Two useful neighbours: .env.example lists settings with empty or fake values, and .gitignore tells Git which local files to leave out. Keep real credentials out of the repo. Adding an ignore rule won’t remove a secret you already committed.

Should every project look like this?

The file list can change quite quickly from one project to the next. I have a folder where I work on marketing and branding. That work doesn’t need architecture.md, product.md, or .gitlab-ci.yml. It needs context about the brand and the people we’re trying to reach.

For a folder like that, useful choices might be:

brand-soul.mdWhat does this brand stand for?

What the brand believes, its personality, and the promises it can make. A reference for deciding whether an idea feels like us.

voice-and-tone.mdHow should we sound?

Writing examples, words we use, and phrases we avoid, so each new draft doesn’t sound like it came from a different company.

audience.mdWho are we talking to?

Who we want to reach, what matters to them, and questions they ask. Ground this in conversations or research so the agent has something better than guesses.

campaigns/What are we working on?

A folder for each campaign’s brief, drafts, and results. Keep the goal and chosen message beside the work they guide.

assets/Which visuals can we use?

Approved logos, images, and reusable templates, with notes on where to use them. Make the current versions easy to find; logo-final-final-v7 shouldn’t be a team mystery.

README.md can still show people where to start, and AGENTS.md can tell the agent to read the brand notes before drafting copy. The checks change too: a draft needs accurate claims and the right brand voice; a visual needs the approved logo.

Choose the files around what the next teammate needs to do the work well, and update them as decisions change. You’re giving your human and AI teammates enough context to work together, whether they’re building a feature or drafting a campaign.

One project, several levels of instructions

The starter shows how this can work: the root AGENTS.md sets agreements for the whole project, app/AGENTS.md adds interface checks, and app/billing/AGENTS.md adds checks for totals and repeated payment requests. These are example rules; the starter has no app code or billing integration. Keep each local instruction file about the work in that folder, so there’s less to maintain.

Codex: from the root to your working folder

Codex loads personal guidance, then instructions along the path from the repo root to the folder where you start the session, its working directory. Start in app/billing/ to load all three levels in this example. Instructions closer to that folder take priority if rules conflict. In our example, each level adds detail and stays consistent with the broader rules.

An AGENTS.override.md takes the place of AGENTS.md in the same directory. Starting at the root does not mean every nested file is loaded. For work below it, explicitly ask the agent to read the relevant files and confirm its instructions. Codex’s discovery rules.

Claude Code: the loading rules differ

Claude Code loads CLAUDE.md files from the folder where you start and the folders above it. It loads instructions in subfolders as it reads files there. Each level in our starter has a CLAUDE.md that imports its neighbouring AGENTS.md. Keep the rules consistent: conflicting instructions don’t give you a dependable “nearest file wins” result. Claude Code’s loading rules.

Some current Claude Code setups also read AGENTS.md directly; the version and settings matter. Check what your session loaded. Compatibility details.

You may also have personal instructions in ~/.codex/AGENTS.md or ~/.claude/CLAUDE.md. The ~/ means your home folder. Keep personal preferences there and shared project rules in the repo.

These files guide behaviour. Permissions, branch protections, and automated checks enforce boundaries. “Please don’t break production” still needs a deployment process behind it.

And what is that .agents/ folder?

The leading dot is a hidden-folder convention, so your file browser may hide .agents/. It is separate from AGENTS.md, the instruction file.

Codex uses .agents/skills/ for reusable workflows. SKILL.md holds the skill’s name, description, and instructions. The explorer includes .agents/skills/grill-me/SKILL.md to show where a skill goes. It is a labelled placeholder, not an installed copy of the skill. Codex skills.

Folder conventions depend on the tool. Claude Code documents .claude/skills/ for project skills. Importing AGENTS.md does not install a Codex skill into Claude Code. Claude Code skills. I’d add a skill when a useful procedure keeps coming up. There’s no need to design a whole library before you’ve started.

See it in action: a new thread, but a familiar project.

Back to our course waitlist: imagine the form now collects email addresses, and you’re ready to add the confirmation emails planned in PRD 002. You open a fresh thread, or conversation, in the same repo and point the agent to that plan. The project instructions help it find the rest of the context.

This is what I want the setup to do for the team: let us start with the next goal and find the context behind it. When the instructions already explain where tests belong and how changes get reviewed, there’s less to repeat. The conversation can focus on the feature and the decisions still to make.

Each Git commit is a saved checkpoint, so give it a message that explains what changed and why. Keep open questions with the feature plan or review discussion. If the next session starts from a new copy of the repo, it needs those commits; edits left only on your computer won’t come along. A decision left only in chat still needs to be recorded somewhere the next session can read.

Where does a setup like this come from?

Engineers have used Markdown files for READMEs, contribution guides, and design notes for years. Browse a well-known open-source project on GitHub and you’ll find its own version of this. VS Code’s README points to plans and guidance for contributors; React’s CONTRIBUTING.md sends newcomers to its contribution guide.

Underneath the filenames is good systems thinking: notice where work gets stuck or context goes missing, then make it easier for the next teammate to do the job.

My cue is repetition. If I keep explaining the same background, it probably belongs in a document. If we keep following the same sequence, maybe it should become a skill. If we keep missing the same check, a checklist or an automated test might help. Sometimes the note already exists and just needs a link where people will find it.

Start with the question: what would help me, my AI teammates, and the humans on the team stay aligned? Let the answer shape your setup. Borrow ideas from other projects, try them in your own, and pay attention to what you still find yourself repeating.

Start small. Make it yours.

I’ve put together a version of this that you’re welcome to download and use. I’d start small, though. Add documents as you build with agents and discover what your project needs.

The principle is to keep enough context in the folder that the next session can pick up the work. The files themselves will change with the project. Keep what helps, change what doesn’t, and make it your own.

And yes, this is a good place to put all those strong opinions about organising folders to the test. :)

Tool behaviour checked against official documentation on 22 September 2026. Follow the source links when your setup behaves differently.