Write an AGENTS.md for a converted Framer site

An AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding tools how the project works: where things live, which commands to run and which rules to follow. For a Framer site converted to TypeScript, the useful version is short and specific: pages are in src/views, routes only carry metadata, colours are tokens in src/styles, CMS content is JSON in src/cms, and every change ends with a production build. This post gives a sample file grounded in the real project layout, then explains each rule so you can adapt it.

A converted project doesn't include an AGENTS.md; it's a file you add. Deframer is an independent tool and is not affiliated with, endorsed or sponsored by Framer, and it converts only sites you own or have permission to convert.

Why a converted Framer site needs one

AI tools read the code they're pointed at, and a converted project is readable, but it has a few conventions a tool can't guess from a single file:

• The page content is not in the route file. In Next.js, src/app/**/page.tsx imports a view from src/views, so a tool asked to "change the hero" may open the wrong file first.
• Colours and type are design tokens and text-style classes, named after the designer's styles. Hard-coded hex values work but drift from the design system.
• Breakpoints are separate layouts per variant (Desktop, Tablet, Phone), so an edit to one may need the same edit in the others.
• src/lib/deframer is the small kit that replaces Framer's runtime. It's yours to change, but most tasks shouldn't touch it.
• Code components in src/code came from Framer's editor, which never type-checked them.

Without these notes, tools waste turns exploring, or make plausible edits in the wrong place. With them, a request like "change the pricing headline" lands in the right view on the first try. The workflow around it is in editing a Framer site with Cursor or Claude Code; this post is about the file itself.

The sample AGENTS.md (Next.js)

Copy this to AGENTS.md at the project root and fill in the bracketed parts. It assumes the default Next.js target.

# AGENTS.md

This is a marketing site converted from a published Framer site to a
Next.js 16 App Router project (React 19, TypeScript). README.md maps
every URL to its route file and has a "Where to edit" table: read it first.

## Commands
- Install: `npm install` (Node.js 20.9 or later)
- Dev server: `npm run dev` (http://localhost:3000)
- Production build: `npm run build`, then `npm start`
- Type check: `npx tsc --noEmit`

## Where things live
- Routes: `src/app/**/page.tsx`. Route files hold metadata (title,
  description, Open Graph, canonical) and render a view. Keep them short.
- Page content and layout: `src/views/<page>.tsx` + `<page>.module.css`
- Navigation and footer: `src/layouts/`
- Shared components: `src/components/` (designer's folders), each with a
  CSS module
- Colours: `src/styles/tokens.ts` (CSS variables like `--token-...`)
- Text styles: `src/styles/text/` (one class per style, per-breakpoint sizes)
- Fonts: `src/styles/fonts/`
- CMS content: `src/cms/<collection>.json`; schema in `<collection>.ts`
- Forms: `src/site/forms.ts`, handlers in `src/app/api/forms/*/route.ts`,
  shared logic in `src/lib/forms.ts`
- URL forms and redirects: `src/proxy.ts`, `next.config.ts`
- The site's own code components and overrides: `src/code/`
- Marketplace components, as source: `src/vendor/`
- Runtime kit (replaces Framer's runtime): `src/lib/deframer`, imported
  as `@/deframer`

## Rules
- Edit views and components, not route files, unless the task is metadata.
- Use existing tokens and text-style classes. Do not hard-code colours or
  font sizes that already exist as a token or style.
- Pages have separate breakpoint layouts. When changing visible content,
  check Desktop, Tablet and Phone and apply the change to each.
- Do not edit `src/lib/deframer` or `src/vendor` unless the task says so.
- CMS edits go in the JSON records; keep field names as they are.
- Keep animations on `motion/react`. Keep spring values unless asked.
- Do not reformat or rename files you aren't changing.
- Do not add dependencies without saying why.
- [Our rule: e.g. all copy changes need a matching change in src/cms/...]

## Before you finish
1. `npm run build` passes.
2. `npx tsc --noEmit` has no new errors in files you touched.
3. Describe what changed and which URLs to check at 1440, 768 and 390 px.

What each section is for

Commands

Tools run commands to check themselves, so give them the exact ones. The project's package.json has dev, build and start in Next.js. There's no lint script in a fresh conversion; if you add ESLint, add its command here too. The Node.js line matters: Next.js 16 needs 20.9 or later, while the TanStack Start and Astro projects need 22.18 or later and React Router 22.22 or later.

Where things live

This section is the map. It mirrors the README's "Where to edit" table, which is generated for your site, so check yours and delete the lines your site doesn't use. Folders like src/cms, src/code and src/locales exist only when the site needs them.

The single most useful line is the one about routes and views. Most wrong edits in a converted project come from a tool changing a route file when the content is in the view.

Rules

Keep rules to the ones that prevent real mistakes. Each rule above exists because a tool, left alone, tends to do the opposite:

• Tokens over hex values: tools copy the colour they see in the CSS.
• Breakpoints: tools edit the first layout they find and stop.
• The kit and vendor folders: tools "fix" shared code to make one page work, and break three others.
• No reformatting: a formatter run across the project turns a two-line change into a thousand-line diff.

Before you finish

The checklist turns "done" into something a tool can verify. A build that passes and a list of URLs to look at is what you need to review the change yourself.

Adapting it to other frameworks

The pages, components, styles, CMS and forms are the same in all five frameworks. Change the commands and the routing lines:

For Vite, add a rule that there is no server: forms post to the service in VITE_FORM_ENDPOINT, and any feature that needs a server needs a separate service. The framework pages (Astro, TanStack Start, React Router, Vite) list each project's files.

AGENTS.md, CLAUDE.md or .cursor/rules?

Different tools look for different files. AGENTS.md is read by a growing number of tools, including OpenAI's Codex and Cursor. Claude Code reads CLAUDE.md, which can import another file with an @AGENTS.md line, so you keep one source of truth. Cursor also supports rule files in .cursor/rules. Check each tool's documentation for its current behaviour; the safe setup is one AGENTS.md with the content and thin pointer files for tools that need their own name.

One Next.js detail: recent Next.js 16 releases can add a managed block of their own to AGENTS.md or CLAUDE.md when next dev detects an AI coding agent, pointing tools at the Next.js documentation shipped in node_modules. Leave that block in place and keep your notes outside its markers.

Nested files for big projects

Most converted sites need one file. If a project grows, for example after adding a backend, tools that support nested files read the closest AGENTS.md to the file they edit. A short src/cms/AGENTS.md that says "records only; the schema is generated" keeps that rule next to the files it guards.

Keep it true

An AGENTS.md that describes a folder that no longer exists is worse than none. Update it in the same pull request as any structural change: a new folder, a headless CMS replacing the JSON, Tailwind added next to the CSS modules (see adding Tailwind to a converted Framer site). Treat it like the README: part of the code, reviewed like code.