# Your repo is your AI’s memory. Give it a decent one. Author: Rajat Published: 2026-09-22 Canonical URL: https://www.thebuildercourse.com/blog/repo-readiness Publisher: The Builder Course One way to give your human and AI teammates the context they need. Explore the folder, understand the choices, and make your own version. Think of AI coding agents like Claude Code and Codex as teammates joining your project. You’d show a new colleague what you’re building and who it’s for. You’d explain the decisions already made, especially the ones they might otherwise helpfully undo. Start a fresh chat without that context and you’re back to the introductions: “We’re building an app for… The users are… Please don’t change the…” By the fourth time, you’ve given the same teammate quite a lot of onboarding. It should at least know where the coffee is. The project folder gives that team a shared workplace. The code lives there, along with a few notes and working manuals your teammates can refer to themselves. Keeping those documents current saves you from explaining the same things every time someone joins the work. Track the project with Git and you have a repository, or repo, with a history of changes too. In this post, I’ll walk through one version of that workspace and the thinking behind its files and subfolders. I wouldn’t expect this exact setup to fit every project. Your team and the way you work will shape your own. My aim is to share the principles that help the whole team stay on the same page, including our agent teammates, Claude and Codex. Be curious about why each document is there, and change the arrangement to suit your project. ## 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/`. The interactive explorer on the website shows these files from the starter. Optional examples can be removed. - [`README.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/README.md): What the project does, how to run it, and where to look next. - [`AGENTS.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/AGENTS.md): Shared working agreements. The nested files add instructions for their own folders. - [`CLAUDE.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/CLAUDE.md): Imports the neighbouring AGENTS.md so you maintain one set of shared rules. - [`CONTRIBUTING.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/CONTRIBUTING.md): How to propose a change, check it, and give a reviewer enough context. - [`DESIGN.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/DESIGN.md): Visual choices, interaction patterns, and accessibility expectations. Link it from the agent instructions for interface work. - [`CHANGELOG.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/CHANGELOG.md): A release history people can read without deciphering your Git commits. - [`.gitlab-ci.yml`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/.gitlab-ci.yml): Tells GitLab which checks to run automatically when code changes. This is called continuous integration, or CI. GitHub Actions uses files such as .github/workflows/ci.yml with different syntax. This example stays disabled until you add real tests. - [`app/AGENTS.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/app/AGENTS.md): Inside app/, reuse the design patterns and check loading, empty, error, and success states. The root agreements still apply. This starter has example instructions, not application code. - [`app/CLAUDE.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/app/CLAUDE.md): This entire file is @AGENTS.md. It imports app/AGENTS.md, relative to this folder. - [`app/billing/AGENTS.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/app/billing/AGENTS.md): A third level: check totals, rounding, and what happens if the same payment request arrives twice. Use test data. These illustrate local rules; the starter has no billing integration. - [`app/billing/CLAUDE.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/app/billing/CLAUDE.md): Imports the neighbouring app/billing/AGENTS.md. Keep those rules consistent with the root and app/ instructions. - [`docs/product.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/docs/product.md): The living overview: who the product serves, what it does today, and what comes next. Update this as features become available; give substantial changes their own product requirements documents, or PRDs. - [`docs/architecture.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/docs/architecture.md): A map of the product’s parts, how information moves between them, and which outside services they use. The starter marks these as prompts for planning your own setup. - [`docs/evals.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/docs/evals.md): Concrete scenarios, expected results, and evidence from checks. Useful for product behaviour and AI output. The sample honestly marks its checks as not run. - [`docs/decisions/001-shared-agent-rules.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/docs/decisions/001-shared-agent-rules.md): An example decision record: why the project shares its agent rules, the tradeoff, and when to reconsider. - [`docs/prds/001-waitlist.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/docs/prds/001-waitlist.md): A product requirements document (PRD) for a waitlist feature: visitors leave an email address to register interest in a future course. It explains what to build and how to check it. This feature is still a proposal. - [`docs/prds/002-email-confirmation.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/docs/prds/002-email-confirmation.md): A second product requirements document (PRD) plans an email confirming that a visitor’s course interest was recorded. It links to the form’s earlier plan. Update product.md when this feature becomes available. - [`docs/runbooks/release.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/docs/runbooks/release.md): A template for releasing a new version: what to prepare, what to do, how to check it worked, and how to return to the previous version if needed. Fill it in and rehearse before using it. - [`tests/waitlist.test.mjs`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/tests/waitlist.test.mjs): Automated tests belong here. This JavaScript example has three tests marked TODO. They don’t check anything yet; replace them with tests of your application. - [`.agents/skills/grill-me/SKILL.md`](https://github.com/thebuilderscollective/repo-ready-starter/blob/main/.agents/skills/grill-me/SKILL.md): A labelled grill-me placeholder showing the folder and file format. It is not an installed upstream skill; replace it with the version you choose to use. 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.md` What 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.md` How 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.md` What 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](https://code.claude.com/docs/en/memory#import-additional-files). ### `docs/product.md` Who 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.md` How 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.md` How 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.md` How 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.md` How 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.yml` Who 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](https://docs.gitlab.com/ci/yaml/) · [GitHub workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax). ### `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.md` What 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.md` What 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.md` How 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.md` Who 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. Example: working in `app/billing/`. 1. `AGENTS.md`: Make a focused change; report checks honestly. 2. `app/AGENTS.md`: Also reuse design patterns and check interface states. 3. `app/billing/AGENTS.md`: Also check totals, rounding, and repeated payment requests. All three add useful context. Keep local instructions short and specific. ### 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](https://learn.chatgpt.com/docs/agent-configuration/agents-md). ### 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](https://code.claude.com/docs/en/memory#how-claudemd-files-load). Some current Claude Code setups also read `AGENTS.md` directly; the version and settings matter. Check what your session loaded. [Compatibility details](https://code.claude.com/docs/en/memory#agentsmd). 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](https://learn.chatgpt.com/docs/build-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](https://code.claude.com/docs/en/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. ### One request. Follow the connections. Open Codex in `app/` and ask: > Work on docs/prds/002-email-confirmation.md. Follow the project instructions and show me your plan before editing. ```text Your request (starting in app/) | repo/AGENTS.md → repo/app/AGENTS.md | +-- Git history + current changes +-- Named PRD + product brief | +-- Code: app/AGENTS.md, architecture, design +-- Checks: tests/, README.md, evals +-- Review: CONTRIBUTING.md | Propose a plan; resolve open questions before editing ``` Illustrative walkthrough. This example starts Codex in app/. Loading rules vary by tool; the article’s hierarchy section explains the differences. ### Step 1: First, Codex finds the instructions. We open Codex in app/. It checks for project instructions from the repo root down to this folder. Here, it reads AGENTS.md in the parent folder, then app/AGENTS.md for the local rules. Personal guidance may apply too. Instruction path: > repo/AGENTS.md → repo/app/AGENTS.md Where it looks: `AGENTS.md` · `app/AGENTS.md` Those files contain directions to the rest of the project. Follow the branches to see where they lead. What the agent might say: > I’ve found the shared rules and the extra instructions for app/. I’ll follow their links to the context this task needs. This example starts in app/, so both levels are on Codex’s instruction path. Starting at the repo root would not automatically load every instruction file below it. The diagram shows a guided example, not a live agent run. The downloadable starter has these documents but no working app. ### Step 2: There, it finds a pointer to the history. That instruction sends Codex to the recent changes. Imagine we built the course-interest form in the last session. It reads the relevant commits and checks the current code, including unfinished edits, to see what is already there. AGENTS.md: > Inspect recent Git commits, git status, and the staged and unstaged diffs for context. Where it looks: `AGENTS.md` · `Git commits` · `Current code and local changes` Now it knows to build on the form that saves email addresses. You don’t have to retell yesterday’s work. What the agent might say: > The form already saves the signup. I’ll build on that flow and check any unfinished edits before changing it. Git commits are saved checkpoints. git log lists them; a diff shows the exact edits between versions. The agent should read the relevant code, not rely on commit messages alone. git status also helps find new files that Git isn’t tracking yet. Those can contain unfinished work too. ### Step 3: Another direction leads to the PRD. Your prompt names PRD 002, so Codex opens it and the linked product notes. The plan asks for an email confirming that someone’s course interest was recorded. It rules out marketing campaigns and promises of a booked seat. AGENTS.md: > Read the PRD named in the request and any linked issue or pull request. Where it looks: `docs/prds/002-email-confirmation.md` · `docs/product.md` Now it knows the scope. It can also spot a real open question: which email service should we use? What the agent might say: > The next feature is a confirmation email. The provider is still undecided; I’ll ask about that before implementing the integration. The product brief explains the wider context. The earlier waitlist PRD explains the form this feature builds on. A missing decision stays visible in the plan. The agent can ask about that gap instead of asking you to explain the entire product. ### Step 4: The local rules explain how to work. Codex already read app/AGENTS.md at the start. Now it applies those rules to this feature. The same file sends it to architecture.md to understand where the email code fits, and DESIGN.md if the interface needs to change. app/AGENTS.md: > Keep modules focused on one responsibility; reuse existing boundaries. Where it looks: `app/AGENTS.md` · `docs/architecture.md` · `DESIGN.md` Now it knows to keep files focused, reuse the existing structure, and follow the team’s design choices. What the agent might say: > I’ll keep the email work in a focused file, trigger it after the signup is saved, and reuse the existing interface patterns. Follow the current signup flow before choosing where to edit. A module is simply a piece of code with a defined job. Read deeper folder instructions when the task reaches those folders. The billing rules aren’t relevant to this change unless it touches app/billing/. ### Step 5: It also finds the test instructions. This tells Codex where tests belong and how to run them. The feature plan and evals.md describe what to check: one confirmation per signup, no duplicates after a retry, and a way to handle delivery failures. app/AGENTS.md: > Add or update behaviour tests under tests/ and use README.md for verified check commands. Where it looks: `tests/` · `README.md` · `docs/evals.md` Now it knows what evidence to bring back. Writing the code won’t be enough to call the feature done. What the agent might say: > I’ll add those tests, run the documented checks, and report what passed, failed, or couldn’t be run. The starter’s tests are placeholders and its CI is disabled. They need real checks of the application before any result can be claimed. evals.md records the scenarios and results. It doesn’t run the checks itself. ### Step 6: The contribution guide sets the review process. That link takes Codex to the team’s contribution guide. It explains how to prepare a reviewable change, report verification, and update affected docs. The shared rules also say to work on a branch and use meaningful Git commits. AGENTS.md: > For contributions, read CONTRIBUTING.md. Where it looks: `CONTRIBUTING.md` · `AGENTS.md` Now it knows how to leave a useful record for you and whoever picks up the next task. What the agent might say: > I’ll prepare the change on a branch, explain the checks in the pull request, and keep open questions with the feature plan. A pull request lets the team review a proposed change before it joins the shared version. The repo’s working rules don’t replace your approval. The agent still needs to follow your request about when to edit, merge, or publish. ### Step 7: Now it can propose a useful plan. The branches come back together. Codex knows what exists, what this feature should do, where changes belong, and how the team checks and reviews work. It can respond to your actual request without a fresh round of onboarding. Your request: > Show me your plan before editing. Where it looks: `The context gathered above` You discuss the remaining decision, then agree the work. The folder has supplied the background and working instructions. What the agent might say: > I’ll build on the saved-signup flow, add one confirmation email in a focused file, test retries and delivery failures, and prepare the change for review. Before I edit: which email service should we use? This is a proposed plan, not a claim that the feature is built or its tests pass. Once you agree the plan and resolve the missing choice, the agent can do the work within the permissions you gave it. The files give your next conversation a route to the context, working rules, and checks it needs. 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. > Work on docs/prds/002-email-confirmation.md. Follow the project instructions and show me your plan before editing. 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](https://github.com/microsoft/vscode/blob/main/README.md) points to plans and guidance for contributors; [React’s CONTRIBUTING.md](https://github.com/react/react/blob/main/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. :) [Use the GitHub template](https://github.com/thebuilderscollective/repo-ready-starter) · [Download ZIP](https://www.thebuildercourse.com/downloads/repo-ready-starter.zip) Tool behaviour checked against official documentation on 22 September 2026. Follow the source links when your setup behaves differently.