How to Write AGENTS.md for Website Development

An effective AGENTS.md tells a coding agent how this website is supposed to work, where the authoritative decisions live, which commands prove a change, and which actions require approval. It should be short enough to scan and specific enough to prevent the most expensive forms of improvisation.

The file is context, not enforcement. A sentence that says “keep pages accessible” is useful direction. A semantic HTML validator, keyboard review, and contrast check are evidence. Website teams need both.

What AGENTS.md does

AGENTS.md is an open Markdown convention for project instructions. The format does not require a schema or fixed headings. That flexibility is useful, but it shifts responsibility to the repository owner: vague prose remains vague no matter how recognizable the filename becomes.

Codex documents a concrete resolution model. It reads instruction files from the project root toward the working directory, with nearer files appearing later and taking precedence. The default combined project-documentation limit is finite, so dumping every convention into the root file can crowd out the instructions relevant to the current task.

Other agents differ. OpenCode and Cursor support AGENTS.md. Claude Code uses CLAUDE.md; Anthropic documents imports, so a thin CLAUDE.md can reference a shared AGENTS.md. Compatibility does not mean identical precedence or identical security behavior. Check the agent field guides before assuming one setup works the same everywhere.

Begin with the decisions that must survive the chat

A website session has temporary context. The repository is durable. Put decisions in the latter when a future agent must preserve them:

• rendering mode and framework conventions;
• route and content ownership;
• design tokens and reusable components;
• page-language and editorial rules;
• accessibility baseline;
• technical SEO requirements;
• test and build commands;
• deployment path and approval boundaries.

Do not use the instruction file as a second README. The README helps a person understand and run the project. AGENTS.md routes an agent through the work: inspect these files first, reuse these primitives, run these checks, do not take these external actions without authority.

A compact root file

The following pattern is intentionally plain. Adapt the paths and commands to the repository rather than copying them unchanged.

# Website operating rules

## Before editing
- Read `src/content.config.ts`, the relevant layout, and existing components.
- Reuse tokens from `src/styles/global.css`; do not create a parallel design system.
- Confirm that a new route has distinct intent before adding it.

## Architecture
- Keep Astro output static unless a documented requirement needs request-time rendering.
- Prefer build-time content and native browser behavior.
- Add dependencies only when the platform cannot solve the requirement clearly.

## Content and SEO
- Write in American English.
- Every indexable page needs a unique title, description, canonical, H1, useful internal links, and truthful structured data.
- Cite primary sources for technical claims. Never invent benchmarks, authors, reviews, or search volume.

## Verification
- Run `npm run content:check` for content changes.
- Run `npm run quality` before release.
- Treat a successful build as necessary, not sufficient.

## External actions
- Never deploy, push a protected branch, alter DNS, or change credentials without explicit authority.

The best lines tell the agent what to inspect or execute. “Follow best practices” does neither.

Separate rules from references

The root file should route, not contain the full operating manual. Long procedures belong in focused documents or reusable skills. For example:

AGENTS.md                         universal workflow and safety
docs/design-system.md            tokens, components, responsive rules
docs/content-system.md           schema, voices, evidence, quality gate
.agents/skills/create-seo-content/SKILL.md
                                  repeatable publishing procedure
src/content/editorial/AGENTS.md   optional collection-specific constraints

This shape reduces noise. An agent working on a header needs design and accessibility guidance. It does not need the complete research protocol for a future benchmark. An agent drafting a comparison needs the content system and source policy. It does not need a tutorial for generating image assets.

Use nested instruction files when a subtree has genuinely different rules. Do not add them merely to demonstrate hierarchy. Conflicting files make precedence harder to reason about and review.

Encode design constraints as paths and components

“Match the brand” asks the agent to infer the brand again. A better instruction identifies the source of truth:

• tokens live in one stylesheet;
• article width uses the existing reading measure;
• buttons reuse the shared class or component;
• new editorial cards extend the existing border and radius treatment;
• mobile behavior must preserve navigation and table semantics;
• motion must respect reduced-motion preferences.

The instruction should also say what not to introduce: a second color scale, an unrelated font, random shadows, or a client framework for a static disclosure. Those exclusions narrow the solution space without dictating every CSS declaration.

The Brief & Ship marketing-site example shows this approach in a real internal repository. The editorial layer uses the same Open Runde typeface, Carbon/Linen palette, pills, hairline borders, and reading measure as the sales page.

Make content rules operational

Editorial instructions fail when they consist entirely of adjectives. “Authoritative, human, useful” sounds correct but cannot settle a difficult publishing decision.

Add gates that can:

1. identify the primary query and user problem;
2. check whether an existing page already owns that intent;
3. require sources for technical statements;
4. distinguish qualitative judgment from measured results;
5. validate titles, descriptions, routes, dates, and links;
6. hold weak pages at draft or noindex;
7. review American English and remove repeated machine-like phrasing.

A numerical quality score can support review, but it should not become theater. The scorer must show its components, and the evidence score must reflect available artifacts. Word count is a warning, not a substitute for unique information.

Treat permissions as a separate layer

Instructions are not a security boundary. An agent can misunderstand a sentence, and different environments apply permissions differently. Use the agent’s sandbox, approval policy, command allowlist, CI permissions, protected branches, and secret scoping to limit consequences.

The file should still name actions that need explicit authority. That helps the agent pause before deployment, billing, credentials, destructive Git operations, or DNS changes. It also makes the intended workflow visible to reviewers.

For Codex, see the Codex website-development guide and Codex with Astro. For Claude Code, connect the same project rules through a thin adapter rather than maintaining two divergent manuals.

Pair every important instruction with a check

Some rules remain human judgments. Art direction, factual nuance, and whether two search intents should merge need review. Other requirements can become deterministic:

• the content schema rejects missing fields;
• a link checker rejects unresolved internal routes;
• the build rejects malformed collection entries;
• HTML validation catches structural errors;
• an audit checks canonicals, robots directives, JSON-LD, assets, and budgets;
• CI runs the same commands on every proposed change.

This pairing changes the role of AGENTS.md. It stops being a wish list and becomes the map to an executable production system.

Route specialized work without bloating the root

Website repositories contain several disciplines that share a release but need different working context. A root file should identify the source of truth for each one. It should not compress every discipline into a list of slogans.

For an editorial task, route the agent to the content schema, query inventory, voice guide, source policy, and validation command. For component work, route it to tokens, existing primitives, breakpoints, and accessibility conventions. For deployment, route it to the current provider configuration and a release checklist that names the production host.

A small routing table is often enough:

The table tells an agent where the work begins and what a completion claim must contain. Detailed procedures can live in the linked documents or skills.

Avoid instruction patterns that fail in practice

Several common patterns make a repository look agent-ready while adding little control.

The universal best-practices paragraph. It asks for clean code, good SEO, accessibility, and performance without naming a project decision or validation command. Replace it with paths and observable acceptance criteria.

The giant context dump. It copies architecture notes, product positioning, style references, and deployment instructions into one file. Important constraints become difficult to find and may exceed an agent’s project-document budget. Keep the root concise and route deeper.

Duplicated adapters. Teams copy the full manual into AGENTS.md, CLAUDE.md, Cursor rules, and another tool’s context file. Those copies diverge. Prefer a shared source with thin adapters where the tool supports imports or references.

Prompt-only security. A warning says not to deploy or expose secrets, while the environment provides unrestricted credentials and no approval boundary. Pair the warning with sandbox, branch protection, scoped tokens, and CI permissions.

Completion by assertion. The agent says the page is responsive or optimized without showing a build, output inspection, or test. Require command results and name the checks that remain manual.

Design for non-developer review

A founder or marketer does not need to evaluate every Astro primitive. They do need a completion report that exposes decisions and risk.

Ask the agent to summarize:

• what changed in user-visible terms;
• which routes and files were affected;
• what it deliberately did not change;
• commands that passed and checks that were not available;
• new dependencies, tokens, content claims, or external services;
• any action still requiring approval.

That report is not a substitute for the diff. It is an index into the diff. A reviewer can start with the consequential choices instead of reading generated CSS in file order.

For content, require a short claim ledger: technical facts added, their sources, qualitative judgments, and statements intentionally excluded for lack of evidence. This is especially useful for fast-changing agent products where a confident but stale sentence can survive long after the session that wrote it.

Keep adapters truthful to each tool

Shared project rules should remain shared, but the adapter has to match the agent’s documented behavior. Codex can consume AGENTS.md directly. Claude Code consumes CLAUDE.md; importing the shared file keeps one maintained source while respecting the tool’s real interface. Cursor rules can scope instructions to file patterns. Other agents may use their own global and project context hierarchy.

Do not claim universal compatibility from the presence of one Markdown file. Test how each supported tool discovers the instructions, how nested scope works, and whether local overrides can accidentally enter version control. Record the verified behavior and date it when the product changes quickly.

The same care applies to commands. An interactive agent may request approval before a test or deployment. A headless runner needs explicit flags, credentials, exit-code handling, and a stopping condition. Keep those execution details out of a generic adapter unless that environment genuinely uses them.

Use a completion contract

The last section of the root file can define what “done” means without prescribing how every task must be solved:

Before reporting completion:
1. Run the checks relevant to the changed files.
2. Run the full quality command for a release candidate.
3. Inspect generated routes, metadata, links, and assets when output changed.
4. Report failures, unavailable checks, and unverified external state.
5. Do not commit, push, deploy, or change credentials unless the request authorizes it.

This creates a shared finish line for Claude Code, Codex, and other repository agents without pretending their interfaces are identical.

Review the file like product code

Update instructions when the repository changes, not on an arbitrary “fresh today” schedule. Remove commands that no longer exist. Mark superseded documents. Test imports used by agent-specific adapters. Check that nested rules still apply at the intended path.

Most important, read the file from the perspective of a new session. Can the agent locate the source of truth? Can it distinguish advice from a hard constraint? Does it know how to prove completion? If not, the file is longer than it is useful.