An AGENTS.md example for a frontend website repository
Give a frontend agent the real page, stylesheet and design-note paths, then ask it to preserve the shared controls. This complete example uses a small static website.
6 min read
In this note
Make the instructions specific to the repository
A frontend AGENTS.md should tell the agent where the page and shared styles live, which existing controls to reuse, and what to check after a UI edit. In the example below, those paths are index.html, styles.css and DESIGN.md. Replace them with files that exist in your repository.
OpenAI’s official guide says Codex reads AGENTS.md before working and builds a chain of instructions down to the current directory. The example is written for Codex. Other tools may support the filename, but their loading behaviour needs its own documentation and test.
Copy a complete frontend AGENTS.md
This file is small because the fixture is small. It has no package manager, build process or backend. Its verification section says that explicitly instead of listing commands that would fail in the supplied directory. In a framework repository, replace that last line with the commands from your package scripts.
The design rules name a reusable control and the CSS file that owns its values. The review rule also asks for the actual link destination, because a correctly styled button can still take the visitor to the wrong place.
# Frontend work in this repository
## Map
index.html is the public page.
styles.css owns the tokens and .button-primary.
DESIGN.md records the page's reader and approved text.
## Before an edit
Read DESIGN.md and styles.css.
Preserve existing page content unless the request changes it.
## Design and UI rules
Reuse .button-primary for the main action.
Use CSS variables from styles.css; do not repeat colour literals in HTML.
Keep one h1 and preserve visible keyboard focus.
For a review, start the reply with: Frontend check:
Report the main action's actual label and destination.
## Verification
After changing index.html, open it at 390x844 and 1440x900.
Follow the main action with the keyboard.
Report the widths actually checked and any remaining failures.
This static fixture has no build command or form backend.
Keep the page’s purpose and approved wording nearby
DESIGN.md holds the product and page decisions. AGENTS.md tells the agent to read it. The split lets you change the fictional beta copy without searching through the repository’s tool instructions for another copy of it.
For a real project, add the agreed source for product claims and the location of approved media. If a request changes a published price or customer promise, have the product owner settle that change. A generic instruction file cannot establish facts the business has not supplied.
# Wrenboard page
The page is for product managers considering a private beta.
The main action says Request access and links to #access.
The access section must exist. No signup service is connected.
Use the existing single-column layout and shared button class.
Test instruction loading without putting the answer in the prompt
Put AGENTS.md at the root of a disposable repository. Add the matching page, stylesheet and design note, then start Codex in that directory. Ask the review question below. The expected reply begins Frontend check: and names Request access with destination #access. Those details come from the project, not the test prompt.
Inspect what the agent read and compare its answer with the files. If the phrase appears but the link information is wrong, the output rule was followed while the review failed. If it names the correct link but has not opened a browser, keep the phone and keyboard checks marked unverified.
Review index.html against the project instructions in this folder. Read files only; do not edit. List each concrete mismatch between the page and the instructions, quoting the instruction you rely on.Check scope when you move the file
A root instruction applies broadly in a small website repository. A monorepo may need more specific frontend instructions near the website. Codex’s documented lookup follows the path to the current working directory, with nearer project guidance appearing later. Check the directory where you launch the session when testing a nested file.
Keep the test local and specific. Adding more instructions will not repair a session started in the wrong project. The official guide also documents override files; inspect those if the loaded guidance differs from the file you intended to test.
What Codex reported in the fixture review
On 3 November 2026, Codex CLI 0.162.1 ran codex exec -s read-only with the exact prompt above. The transcript shows it reading AGENTS.md, DESIGN.md, styles.css and index.html. Its reply began: “Frontend check: No concrete mismatches found in the files.” It quoted the project rules, identified Request access and #access, and confirmed the target section existed. The command exited 0 without editing files.
The run also loaded the user’s global configuration. It demonstrates that this session read and applied the fixture’s rules; it does not isolate the effect of AGENTS.md or measure reliability across sessions. Codex explicitly left viewport and keyboard behaviour untested. Run those checks on the page after an edit. For a procedure that reviews many pages, keep repository rules short and put the procedure in a separate skill.
Put the brief into practice
A launch page should make the buyer, promise, proof, and next action obvious. iter0 uses this same standard when it turns a brief or reference site into a builder-ready page.
Start your launch build