AGENTS.md and llms.txt: Making Your Next.js Project Legible to AI

Two different kinds of AI now read what you publish. AI coding agents read your codebase to help build and maintain it. AI answer-engines read your live site to decide what your business is and whether to recommend it. Both perform dramatically better when you leave them clear instructions, and Next.js has a specific, low-effort answer for the first that generalizes neatly to the second. This is about two small files — `AGENTS.md` for the agents in your repo, and `llms.txt` for the models reading your site — and what each is worth to a business of your size.

#The problem: AI’s training data is always a little stale

An AI coding agent knows an enormous amount about Next.js, but its knowledge is frozen at its training cutoff. Frameworks move fast; by the time you’re building, the agent may be confidently writing patterns that were deprecated two releases ago — putting config in the wrong place, using an API that changed, following a convention that’s now an anti-pattern. The result is code that looks plausible, passes a glance, and quietly does the wrong thing. Next.js’s fix is to ship the correct, version-matched documentation inside the package itself.

#AGENTS.md: point the agent at the real docs

When you install Next.js, its documentation is bundled at `node_modules/next/dist/docs/`, matching the exact version you’re running. An `AGENTS.md` file at your project root tells any AI agent to read those bundled docs before writing code, instead of trusting its training data. Most agents — Claude Code, Cursor, Copilot — read `AGENTS.md` automatically when they start. New projects created with `create-next-app` generate it for you.

<!-- AGENTS.md -->
<!-- BEGIN:nextjs-agent-rules -->

# Next.js: ALWAYS read docs before coding

Before any Next.js work, find and read the relevant doc in
`node_modules/next/dist/docs/`. Your training data is outdated —
the docs are the source of truth.

<!-- END:nextjs-agent-rules -->

The markers let you add your own project rules outside the managed block without them being overwritten on update. Claude Code users can add a one-line `CLAUDE.md` that imports it with `@AGENTS.md`, so both tools share one set of instructions. This is the whole setup: two files, and every AI touching your repo now works from accurate, version-matched Next.js docs instead of a hazy memory of an older release.

#llms.txt: the same idea, pointed at AI answer-engines

The mirror image of AGENTS.md faces outward. Just as you can hand coding agents a map of your docs, you can hand AI answer-engines a map of your site with an `llms.txt` file at your root — a plain-Markdown summary of what your business is and links to your most important pages, written for a model rather than a crawler. It’s an emerging convention (Next.js itself publishes one), and while no single file guarantees a citation, the direction is clear: as AI-driven answers take a growing share of discovery, the businesses that make themselves easy for models to summarize correctly will be the ones summarized correctly. It pairs with the structured data in our JSON-LD guide — schema tells machines what each page means; llms.txt tells them what the whole business is.

# llms.txt — a map of your site for AI

# Acme Co
> Local web design and SEO for home-service businesses in DFW.

## Core pages
- [Services](https://acme.co/services): what we do and what it costs
- [Results](https://acme.co/results): client outcomes with real numbers
- [Contact](https://acme.co/contact): book a free discovery

#What goes in your own section of AGENTS.md

The Next.js-managed block is deliberately minimal — read the bundled docs before coding — and that’s the point: it redirects agents from stale training data to accurate, version-matched documentation. But the markers exist so you can add your own rules outside them, and this is where a business gets real leverage. Put your project’s conventions there: how you structure routes, which UI library to use, your deploy target and its constraints, the patterns you consider settled and don’t want re-litigated. An agent that reads “this project deploys to a memory-constrained container, so keep the build lean” or “data access goes through lib/server, never directly from a component” makes fewer of exactly the mistakes that cost review time. It turns AGENTS.md from a framework pointer into a living style guide every AI (and every new human) reads first.

<!-- AGENTS.md -->
<!-- BEGIN:nextjs-agent-rules -->
# Next.js: read node_modules/next/dist/docs before coding.
<!-- END:nextjs-agent-rules -->

## Acme project rules
- Server Components by default; add "use client" only at interactive leaves.
- All data access lives in lib/server and is never imported by a client file.
- Images always go through next/image. No raw <img>.
- Deploy target is a 2GB container; keep the build and bundle lean.

#llms.txt in practice, and where it’s heading

The llms.txt proposal is young but the logic is sound and the adoption curve is steep: give language models a clean, curated entry point to your site instead of making them reverse-engineer it from your navigation and marketing copy. The file is plain Markdown — a short description of what you are, then links to your most important pages with a line on each. Think of it as the README for your business, written for a model. It doesn’t replace good structured data or a crawlable site; it complements them by stating the summary explicitly rather than hoping a model infers it. Nobody can promise a citation from any one file today, but the trajectory is unmistakable: as AI-mediated discovery grows, being easy for a model to summarize correctly stops being optional. The cost to add one is near zero, and the downside is nil, which is exactly the profile of a bet worth making early.

#Does it actually help? The honest answer

It’s fair to ask whether pointing agents at bundled docs measurably improves their output, and the Next.js team publishes benchmark results showing how bundled docs plus AGENTS.md change agent performance on real Next.js tasks. The mechanism is intuitive: an agent that looks up the current API instead of recalling a two-year-old one writes code that compiles and follows current conventions more often. You’ll feel it as fewer corrections on AI-assisted work — the agent stops confidently proposing the deprecated pattern. It’s not magic and it doesn’t make a weak agent strong, but it removes a whole category of avoidable, stale-knowledge errors, and that category is a real slice of the rework AI-assisted teams pay for today.

#One instruction set, every tool and every new hire

The quiet strength of AGENTS.md is that it’s tool-agnostic. Most modern AI coding assistants — Claude Code, Cursor, GitHub Copilot, and a growing list — read it automatically at the start of a session, so you write your project’s rules once and every agent, regardless of which developer prefers which tool, works from the same instructions. That portability matters more than it first appears: it means your conventions aren’t locked to one vendor’s config format, and switching or mixing tools doesn’t mean re-teaching each one your project. Claude Code users bridge it with a one-line `CLAUDE.md` containing `@AGENTS.md`, so Claude Code and the rest share a single source of truth instead of drifting copies.

And the audience isn’t only machines. A well-written AGENTS.md is the fastest onboarding doc a new human developer can read — it states the framework version, the conventions, the deploy constraints, and the patterns the team considers settled, all in one place at the root of the repo. We’ve watched a new contributor get productive faster from a good AGENTS.md than from a wiki nobody kept current, precisely because it lives next to the code and gets updated when the code does. So treat it as a living document with an owner: review it when your conventions change, version it in git like everything else, and keep the framework-managed block current by updating Next.js (which refreshes the bundled docs the block points at). One file, kept honest, pays back every time a new hand — human or AI — touches your project. It’s the cheapest leverage in this whole series, and almost nobody does it. The reason it’s neglected is that it feels like documentation, and documentation is the first thing teams skip — but this is documentation the machines actually read and act on every session, which is what makes it worth the ten minutes it takes to write.

#What this means for your business

Both files are near-free to add. The value scales with how much AI touches your code and how much of your discovery is moving to AI answers.

#For agencies

You are the heaviest user of AI coding agents, so AGENTS.md is direct margin. Standardize it across every client repo and your AI-assisted builds get measurably more accurate — fewer stale-pattern bugs, less senior time spent correcting confident-but-wrong agent output, faster delivery at the same quality. Put your own house rules (the client’s conventions, your deploy posture) in the un-managed section so agents follow the project, not just the framework. On the outward side, adding llms.txt to client sites is a cheap, forward-looking differentiator you can include in every build and point to when a client asks what you’re doing about AI. Two files, shipped once in your starter, applied to every engagement.

#For micro businesses (1–5 people)

If you or a freelancer use an AI tool to make changes to your Next.js site, AGENTS.md is the cheapest insurance you can buy against it introducing subtle breakage — one file, and the AI works from current docs. On the discovery side, an llms.txt is a genuinely smart low-effort move for a small local business: more and more customers ask an AI “who’s a good [your trade] near me,” and a clear summary of who you are and what you do makes you easier to surface correctly. Neither file needs ongoing maintenance. If setting them up isn’t your thing, it’s a ten-minute add-on we’ll handle.

#For small businesses (SMEs)

As you bring more AI into how your site gets maintained — whether an in-house dev with Copilot or a contractor with Claude Code — AGENTS.md keeps that work anchored to correct patterns and to your conventions, which matters more as more hands (human and AI) touch the code. Add llms.txt and keep it current with your key pages, because AI-driven discovery is a real and growing slice of how buyers find businesses your size. Treat both as part of your standard site setup, reviewed when you do a bigger content or platform update.

#For mid-size companies

AGENTS.md becomes a governance surface at your scale: it’s where you encode the standards you want every AI agent — across many repos and many developers — to follow, which is how you keep AI-assisted development consistent instead of a hundred developers each getting a hundred different confident-but-wrong suggestions. Version it, review it, and extend the un-managed section with your architectural rules. The llms.txt and the broader question of how AI systems model your brand deserve real ownership too — as answer-engines mediate more discovery, being summarized accurately is a brand-integrity issue, not a nice-to-have. Fold both into your existing docs and content governance.

#How we run this at Frontend Horizon

Every FH project ships with an AGENTS.md that points agents at the version-matched Next.js docs and carries our own build conventions, so AI-assisted work stays accurate — and we treat llms.txt as part of making a client site legible to the AI answer-engines that increasingly drive discovery. It’s the same principle in both directions: leave the machine a clear map and it works with you instead of guessing. If you want your codebase and your site set up to work well with AI, run a free discovery. Next in the series, the live version of this idea: letting an AI agent see your running app while it builds, with the Next.js MCP server.