Writing an AGENTS.md for Agility Projects

An AI coding tool starts every session knowing nothing about your project except what it can read. AGENTS.md is where you put the things it can't read from the code: your conventions, your instance's facts, and the mistakes you don't want repeated.

This article covers the conventions that made the biggest difference across our proof-of-concept builds (see Vibe Coding with Agility). For a complete, ready-to-extend file for the Agility Next.js Starter, including MCP rules, list limits, reference-name case and the cache-tag contract, use the template in Building an Agility Site with AI Coding Tools. This article doesn't repeat it.

Keep one canonical file

Make AGENTS.md the single source of truth, and make every tool-specific file a short pointer to it:

• CLAUDE.md for Claude Code
• .cursor/rules or .cursorrules for Cursor
• .github/copilot-instructions.md for GitHub Copilot
• the Windsurf rules file

Each pointer can be a single line: "Read AGENTS.md first. It is the source of truth for this project." When conventions live in five files they drift apart, and the AI tool follows whichever one it happened to read.

Open with a short list of non-negotiables

Put five to eight rules at the top, before anything else. These are the rules that, if broken, cause bugs the AI tool can't see in development. Typical ones for an Agility project:

• Every CMS read goes through the project's data layer, which sets cache tags. No direct SDK calls from components.
• Every component is registered in the component registry, or it renders as "not found".
• Environment variables are read only through one typed module.
• Brand colors come only from CSS custom properties.
• Keep it small. Name the demo moment or core feature so the AI tool protects it instead of adding features around it.

Write project constraints as rules too. If a customer's security review rules out AI features in the shipped site, say "No AI features, MCP endpoints or analytics in this repo" in the non-negotiables, not in a paragraph on page three.

Describe one component pattern

Give the AI tool one way to build a component, and an example to copy. For the Agility Next.js Starter that pattern is:

• An async server component receives its content ID, then fetches its own fields through the data layer.
• Linked lists are fetched separately, by reference name, with an explicit take.
• Images use the SDK's picture component (AgilityPic), and rich text uses the SDK's HTML rendering.
• The component is added to the registry under the component model's reference name.

When there's exactly one pattern, the AI tool's output is consistent and every component can be reviewed the same way.

Write out the Web Studio attribute rules

Web Studio in-context editing depends on data-agility-* attributes in the rendered HTML. AI tools get these subtly wrong, so spell the rules out:

• data-agility-component goes only on a component's root element.
• Every rendered field gets data-agility-field with the field name, and the element should contain only that field's value. If an element mixes a field with other text, an edit can overwrite the extra text.
• Items rendered from a linked list get data-agility-nested-listitem, not data-agility-component.
• Rich text fields also get data-agility-html.

Two more rules we have seen matter in practice: if your image component doesn't pass the field attribute through to the rendered element, wrap the image in an element that carries it; and some link-field layouts edit better without a field attribute than with one. Check each in Web Studio rather than assuming.

Agility Decorate can add these attributes for you and check them in CI.

Keep an instance ledger

Record the facts about your Agility instance in AGENTS.md, and update them the moment anything is created. Later sessions then start from facts, not from guesses or another round of lookups:

• Instance GUID, locales and sitemap names
• Page models and their zone names
• Every content model, container, component model and seed content item, with its ID and exact reference name

Ask the AI tool to add each entry as it creates the thing, in the same step. Recording IDs at the end of a session is how they get lost.

Carry an "MCP gotchas" list forward

Every time you lose time to surprising behavior from the MCP server, the APIs or the framework, add one line to an "MCP gotchas" list in AGENTS.md: the symptom and what to do instead. Copy the list into each new project. It's the part of the file that compounds most.

Start with the ones in MCP and Agility Gotchas to Know Before You Build.

Other conventions worth adding

• Framework version warnings. If you're on a framework version newer than the AI model's training data, say so, and point the AI tool at the framework's own docs. Next.js 16 changed enough (the proxy file, Cache Components) that an AI tool working from older habits will write outdated code.
• Wording for customer-facing copy. For example, say "components", not "modules".
• Keep docs in sync. A code change that affects a convention, a ledger entry or a doc must update it in the same change.
• Skills next to AGENTS.md. Repeatable tasks such as "create a news article through the MCP server" or "review a pull request" work well as skills that AGENTS.md links to.

A skeleton to start from

Here's a generic skeleton with the sections above. Fill in the brackets, delete what doesn't apply, and add the starter-specific sections from Building an Agility Site with AI Coding Tools.

# AGENTS.md

Source of truth for AI coding tools in this repo. CLAUDE.md, Cursor rules
and Copilot instructions point here. Keep this file current: any change
to a convention, model or ID updates this file in the same change.

## Project
[One paragraph: who the site is for, the use case, the demo moment or
core feature to protect.]

## Non-negotiables
1. Every CMS read goes through lib/cms/ (it sets cache tags).
2. Every component is registered in components/agility-components/index.ts.
3. Env vars are read only through lib/env.ts.
4. Colors come only from CSS custom properties in the global stylesheet.
5. Saves go to Staging. Publishing level: [manual | via approval | autonomous].
6. Keep it small. Don't add features that aren't in docs/plan.md.
7. [Project constraint, e.g. "Use real public content; anything we wrote
   is listed in docs/content-provenance.md".]

## Stack
Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS 4, Node 24 LTS.
Next.js 16 may differ from your training data. Check the Next.js docs
before using caching, routing or proxy APIs.

## Component pattern
- Async server component. Receives its content ID, fetches its own
  fields with getContentItem from lib/cms/.
- Linked lists: getContentList by reference name, with an explicit take.
- Images: AgilityPic. Rich text: render the HTML field, never raw strings.
- Register under the component model's reference name.

## Web Studio attributes
- data-agility-component on the component root only.
- data-agility-field="<fieldName>" on every rendered field; the element
  contains only that field's value.
- data-agility-nested-listitem on each item rendered from a linked list.
- data-agility-html on rich text fields.

## Instance ledger
- Instance GUID: [guid]   Locales: [en-us]   Sitemap: [website]
- Page models: [Main] (zones: [MainContentZone])

| Kind | Reference name | ID | Notes |
| --- | --- | --- | --- |
| Content model | [Event] | [id] | |
| Container | [Events] | [id] | |
| Component model | [EventList] | [id] | |
| Seed content | [Event: Spring Open House] | [id] | from [source], [date] |

## MCP gotchas
- [Symptom] -> [what to do instead]

## Commands
npm run dev | npm run build | [test command]

Related

• From Brief to Working Site: The Vibe Coding Workflow
• Vibe Coding Playbooks by Use Case
• AGENTS.md specification