An AGENTS.md file should be a short operating contract for your coding agent: where code belongs, what not to touch casually, how to validate a change, and which existing patterns to copy. It is not a giant prompt, a substitute for review, or a guarantee that an agent will make correct changes.
For a solo developer building a Next.js SaaS with an agent, the useful goal is simpler: make the safe, repeatable path obvious before the agent starts exploring. That reduces the odds of a small feature spreading business logic into pages, pulling provider SDKs into components, or skipping the checks that would expose a regression.
This guide gives you a practical starting template, explains the sections that do real work, and shows how to keep the file honest as your application changes.
What an AGENTS.md file should do
Repository instructions are persistent project context. GitHub documents repository-wide and path-specific custom instructions, including AGENTS.md files for agent guidance; the closest file can take precedence when multiple instruction files exist. That makes placement and scope part of the design, not just a naming choice.
For a Next.js SaaS, a good root file answers four questions before an agent edits anything:
- What is this project? Identify the framework, major boundaries, and the kind of product it is.
- Where does a change belong? Describe feature modules, shared code, routing, and infrastructure seams.
- What must remain protected? Name areas that need deliberate review, such as auth, payments, configuration, migrations, and provider adapters.
- How is a change proven? Give the commands and targeted checks that are appropriate for the repository.
The file should reduce discovery cost. It should not claim that a test suite is comprehensive if it is not, promise production safety, or instruct an agent to bypass review for sensitive changes.
The practical AGENTS.md template
Start with this template, then replace every bracketed item with facts verified in your repository. Delete any rule you cannot maintain. The point is a usable contract, not a long document.
# Project Agent Contract
## Project context
[Product name] is a [framework and architecture] application for [user/job].
Read the target module and nearby implementations before changing code.
Prefer existing patterns over a new abstraction.
## Architecture
- Put product behavior in `src/features/<feature>/`.
- Keep `app/` limited to routing, layouts, route handlers, and composition.
- Do not import one feature directly from another feature.
- Move code to `src/shared/` only when it is genuinely reused.
- Access databases, payments, and AI providers through their existing adapters.
## Change boundaries
Treat these areas as protected infrastructure; change them only when the task requires it:
- `src/lib/`
- `src/config/`
- `src/services/`
- authentication, billing, webhook, and deployment configuration
Do not expose secrets to client code. Keep provider SDKs out of UI components.
## Implementation rules
- Default to Server Components; add `"use client"` only for browser APIs or interactivity.
- Preserve strict TypeScript; do not add `any` to escape a type error.
- Validate inputs at server boundaries.
- Return the project’s established result shape for expected action failures.
- Reuse the repository’s UI primitives and accessibility conventions.
## Verification
Run the checks relevant to the change:
```bash
npm run lint
npm test -- --runInBand
npm run build
```
Before finishing, review the diff, preserve unrelated local changes, and state
which checks ran and which did not.
The commands above are deliberately examples. If your project uses Playwright, a package workspace command, a database emulator, or a different test runner, record the exact command that contributors can actually run. A validation section that always fails will quickly be ignored.
Why the architecture section matters most
Coding agents can generate a route, form, or component quickly. The more expensive failure is a feature that looks correct in isolation but bypasses the application’s boundaries. For example, a client component that reaches directly into a database SDK creates a different security, caching, and testing path from the rest of the product.
Use the architecture section to state relationships, not slogans. “Keep business logic in feature modules” is useful when paired with “keep app/ focused on routing and composition.” “Use adapters” becomes actionable when it names the boundary: features call the project’s database or payment abstraction rather than importing a vendor SDK.
Frontend Accelerator’s current agent contract follows this pattern: it identifies feature-first modules, keeps routing and composition in app/, and keeps provider-specific implementation behind adapters. That is a concrete example of instructions describing a codebase’s real seams rather than asking an agent to be generally careful.
Annotate the template before you adopt it
Use this review checklist to turn the template into repository-specific guidance.
- Map one recent feature. Trace a small change from route to feature logic, data access, and test. Write only the boundaries that actually exist.
- Name protected infrastructure. Include the paths and domains where a casual edit can change security, billing, configuration, or deployment behavior. Do not mark half the repository as protected.
- Check the agent’s working directory. If you use nested
AGENTS.mdfiles, define which root rules still apply and what the local file adds. Avoid contradictory instructions. - Use real commands. Run every listed lint, test, type-check, and build command from a clean enough local environment. Record prerequisites such as an emulator or required environment variables without putting secrets in the file.
- Test with a small task. Ask an agent to add a contained feature or fix a clear bug. Review whether it chose the intended directory, obeyed the boundary, and ran the stated verification.
This is a maintenance loop. When you move a feature boundary, change a test command, or replace a provider integration, update the instruction that would otherwise mislead the next agent.
Common failure modes
A file that describes an idealized repository
“All actions return ActionResult” is harmful if half of the existing actions throw exceptions. Either migrate the pattern deliberately or state the local convention precisely. Agents need a reliable default, not aspirational policy.
A wall of rules with no priority
Long instruction files make it difficult to notice the rules that matter. Put the architecture, protected areas, and verification commands near the top. Link to longer design documents instead of duplicating every implementation detail.
Commands that are too broad for every change
A full production build may be necessary before a release but disproportionate for a copy change. Describe a baseline for all changes and add targeted checks by area. An agent should still report skipped checks rather than implying they ran.
Using instructions as a security boundary
An AGENTS.md file can tell an agent to validate authorization and keep secrets server-side. It cannot enforce those rules at runtime. Keep real controls in code, CI, access policies, review, and tests.
A lightweight operating model for solo builders
Use one canonical root AGENTS.md for rules that apply to the whole app. Keep tool-specific files small and point them back to that contract. Add a nested instruction file only when a directory has genuinely different constraints, such as a payment integration, generated client, or mobile app.
Then make the agent’s handoff inspectable. A good task result says what changed, which architectural boundary it used, what it did not change, and which verification ran. That is more useful than a confident claim that the change is “done.”
If you want a structured starting point, review Frontend Accelerator’s architecture and AI conventions. It is designed as a Next.js SaaS foundation with a canonical agent contract, tool-specific instruction entrypoints, and repository-level Skills; you still need to adapt any template to your own product decisions and review the generated changes.
