An AGENTS.md that keeps a Codex-built site shippable

Short answer: put a short AGENTS.md at the root of your repository with four sections: how to run and test the app, rules that must never break (no secrets in client code, every route checks the user owns the data), rules for every new public page (title, meta description, server-rendered text, labels on form fields), and what done means (tests pass, a screenshot on a phone viewport, no new console errors). OpenAI's docs say Codex reads AGENTS.md from the project root down to the folder it works in before each task, so these rules apply every time.

How Codex reads AGENTS.md

Per OpenAI's docs:

• Codex reads one global file from your Codex home, ~/.codex by default.
• It then walks from the project root, usually the git root, down to the current folder, and includes at most one file per folder: AGENTS.override.md if present, else AGENTS.md.
• Files are joined from the root down, so files closer to your folder override earlier guidance.
• The combined size limit is 32 KiB by default.

A template you can copy

# AGENTS.md

## Run and test
- Install: npm ci
- Dev server: npm run dev (http://localhost:3000)
- Before saying a task is done: npm run lint && npm test && npm run build
- End to end: npx playwright test (phone viewport 390x844 and desktop)

## Never break these
- No API keys, tokens or service role keys in client code, logs or git.
- Every API route checks that the signed-in user may read or change the data.
- Never send real emails or payments in tests; use test accounts.

## Every public page
- A unique title (under 60 characters) and meta description.
- Main text rendered in the HTML, not only in the browser.
- One h1. Headings in order. Alt text on images.
- Forms: a visible label on every field, errors that say what to fix.
- New pages are added to sitemap.xml.

## Done means
- Tests and build pass.
- A screenshot of the changed page on a phone viewport.
- No new errors in the browser console.

Keep it short and specific

Rules like "write clean code" do nothing. Rules like "every API route checks ownership" can be checked in a review. Long files hit the size limit and get ignored in part. If one folder needs its own rules, such as payments, add an AGENTS.md there; OpenAI's docs give that example with a payments-specific test command.

Pair it with a pre-launch pass

AGENTS.md keeps new changes in line. It does not check what is already live. Before launch, run the Codex pre-launch checklist, and give Codex one finding per task, as in turning bug reports into fix prompts.

Where Persqo helps

Persqo tests the live site and hands Codex findings it can act on:

• Paste the Persqo prompt into Codex and your app gets a Persqo admin page at /admin/persqo.
• An AI visitor tests the live app on desktop and mobile, with screenshots and a replay. Each finding comes with a fix prompt written for a coding agent.
• One click: on a Next.js or Vite app, the Persqo fix runtime the prompt adds applies the home page title and description, business and FAQ schema and llms.txt, each with Undo. Next.js shows them within a minute, Vite at your next build.
• Connect your repository and Persqo opens a pull request for file fixes such as llms.txt and robots.txt. You merge it; Persqo never merges.

More on Persqo for Codex.

Sources

• Custom instructions with AGENTS.md, OpenAI Codex docs, checked November 6, 2026
• Project rules, Cursor docs, checked November 6, 2026
• How Claude remembers your project, Claude Code docs, checked November 6, 2026

Last updated: November 6, 2026.

Questions people ask