Codex AGENTS.md Starter

What this is

Codex works better when the repo has a short operating manual. AGENTS.md is that manual: a file at the project root that tells the agent what the project is, where design-system rules live, which commands are safe, and how to report changes.

Use this template before asking Codex to edit a real project.

Starter file

Create a file called AGENTS.md at the project root and paste this:

# AGENTS.md

## Project

Name: [project name]
Type: [Astro site, Next.js app, Storybook docs, design-system package, etc.]
Primary audience: [designers, engineers, customers, internal team]

## Goal

Help with small, reviewable design-system and UI tasks:
- inspect files
- explain structure
- audit components, tokens, and docs
- make scoped edits
- run safe verification commands
- report diffs clearly

## Design-system rules

Read these before judging UI or changing components:
- [path to token docs]
- [path to component docs]
- [path to brand or style rules]
- [path to examples]

If a rule is not documented, label it as a recommendation, not a violation.

## Safe commands

Prefer these commands when verifying work:
- install: [npm install / pnpm install / yarn]
- dev: [npm run dev]
- build: [npm run build]
- test: [npm test]
- lint: [npm run lint]

Ask before:
- installing new packages
- deleting files
- changing environment variables
- running migrations
- touching production config

## Editing rules

- Keep changes narrowly scoped to the requested task.
- Do not refactor unrelated files.
- Do not rename public APIs unless asked.
- Preserve existing design patterns unless the task is to improve them.
- Prefer existing components, tokens, helpers, and styles.
- If a file is already modified, explain how your change interacts with it.

## Design review format

When reviewing UI, lead with findings:

1. Severity: Blocking, High, Medium, Low
2. Evidence: file, selector, screenshot area, or visible behavior
3. Fix: one concrete change
4. Confidence: High, Medium, Low

Avoid generic advice. Name the exact element, label, spacing, token, or state.

## Done means

Before saying the task is done, report:
- files changed
- commands run
- verification result
- remaining risk or follow-up

First prompt to run

After adding the file, ask Codex:

Read AGENTS.md and orient yourself in this project.

Do not edit files.

Tell me:
1. What kind of project this is
2. Where the design-system rules seem to live
3. Which commands look safe to run
4. One missing instruction that would help you work more safely

Customize before edits

Do not leave the placeholders in place. At minimum, fill in:

• project type
• token and component docs
• safe build command
• safe test or lint command
• the work Codex should not do without asking