Real-World AGENTS.md Patterns
We've covered the principles.
Now let's see what useful AGENTS.md files actually look like.
There is no universal template that every project should copy.
A good AGENTS.md reflects:
- The project's stack.
- Its architecture.
- Its workflows.
- Its validation requirements.
- Its important boundaries.
The examples below are patterns, not mandatory templates.
Use what fits your repository.
Pattern 1 — Small Next.js Application
Consider:
my-app/
├── AGENTS.md
├── package.json
├── src/
│ ├── app/
│ ├── components/
│ └── lib/
└── tests/
A useful AGENTS.md might be:
# Project Guidelines
## Stack
- Next.js App Router
- TypeScript
- Tailwind CSS
## Development
- Use `pnpm` for dependency management.
- Start development with `pnpm dev`.
## React
- Prefer Server Components.
- Add `"use client"` only when client-side interactivity is required.
- Reuse components from `src/components` before creating new shared components.
## Code Organization
- Keep reusable non-UI logic inside `src/lib`.
- Keep route-specific components close to their routes.
## Testing
- Add tests for new business logic.
- Add regression tests for bug fixes.
## Validation
Before completing application changes:
- Run `pnpm lint`.
- Run `pnpm typecheck`.
- Run relevant tests.
## Security
- Never commit secrets or `.env` files.
Notice that this file doesn't explain how Next.js works.
It describes how this project uses Next.js.
Pattern 2 — Node.js API
Now consider:
api/
├── AGENTS.md
├── src/
│ ├── controllers/
│ ├── services/
│ ├── repositories/
│ └── schemas/
└── tests/
The architecture matters more here.
# API Guidelines
## Stack
- Node.js
- TypeScript
- Express
- PostgreSQL
- Zod
- Vitest
## Architecture
Follow this dependency direction:
Controller
→ Service
→ Repository
→ Database
- Controllers handle HTTP concerns.
- Services contain business logic.
- Repositories contain database access.
- Do not access the database directly from controllers.
## Validation
- Validate incoming request payloads using Zod.
- Keep reusable schemas inside `src/schemas`.
## Testing
- Add unit tests for new service-layer logic.
- Add regression tests for bug fixes.
- Add integration tests for new API endpoints.
## Database
- Create migrations for schema changes.
- Do not modify previously applied migrations.
## Validation Commands
Before completing backend changes:
- Run `pnpm lint`.
- Run `pnpm typecheck`.
- Run `pnpm test`.
Here the most valuable instructions are architectural.
Pattern 3 — Full-Stack Monorepo
Consider:
platform/
├── AGENTS.md
├── apps/
│ ├── web/
│ │ └── AGENTS.md
│ └── api/
│ └── AGENTS.md
└── packages/
└── ui/
The root should contain shared rules.
Root AGENTS.md
# Repository Guidelines
## Development
- Use `pnpm`.
- Use TypeScript for new source files.
- Use workspace dependencies for internal packages.
## Repository
- Do not manually modify generated files.
- Do not commit secrets or `.env` files.
## Validation
Before completing changes:
- Run linting for affected packages.
- Run type checking for affected packages.
- Run relevant tests.
Then each application adds only what is specific to it.
apps/web/AGENTS.md
# Web Application
- Use Next.js App Router.
- Prefer Server Components.
- Use Tailwind CSS.
- Reuse shared components from `packages/ui`.
- Use Playwright for end-to-end browser tests.
apps/api/AGENTS.md
# API Application
- Validate incoming request payloads using Zod.
- Keep business logic inside services.
- Keep database access inside repositories.
- Use Vitest for service-layer unit tests.
Notice that neither nested file repeats:
- Use pnpm.
- Never commit secrets.
Those rules already live at the repository level.
Pattern 4 — Shared UI Library
Shared packages often need different boundaries from applications.
Consider:
packages/ui/
├── AGENTS.md
├── src/
└── stories/
A useful file might be:
# UI Package Guidelines
## Components
- Keep components independent from application-specific business logic.
- Prefer composition over adding many configuration props.
- Export public components through the package entry point.
## Styling
- Use existing design tokens.
- Do not hardcode application-specific colors.
- Support both light and dark themes.
## Accessibility
- Interactive elements must remain keyboard accessible.
- Preserve appropriate ARIA attributes when modifying accessible components.
## Storybook
- Add or update stories when introducing reusable UI states.
## Testing
- Add tests for reusable component behavior.
The key instruction is the boundary:
Shared UI should not depend on application-specific business logic.
That is something an agent needs to know about this package.
Pattern 5 — Database-Heavy Project
Some repositories need stronger database instructions.
# Database Guidelines
## Schema Changes
- Create a migration for every schema change.
- Never edit a migration that has already been applied to a shared environment.
- Keep migrations backward-compatible when practical.
## Queries
- Use parameterized queries.
- Avoid unbounded queries on large tables.
- Reuse existing database helpers before introducing new query abstractions.
## Transactions
- Use transactions when multiple writes must succeed or fail together.
## Testing
- Add integration tests for repository methods containing non-trivial queries.
## Validation
After modifying database code:
- Run database integration tests.
- Run `pnpm typecheck`.
These instructions focus on the risks unique to database work.
Pattern 6 — Generated Code
Repositories using generated code need clear boundaries.
Imagine:
src/
├── generated/
└── schema/
A useful section might be:
## Generated Code
- Do not manually edit files inside `src/generated`.
- Modify the source schema inside `src/schema`.
- Run `pnpm generate` to regenerate output.
- Commit regenerated files when the source schema changes.
Notice the pattern:
Don't modify X
+
Modify Y instead
+
Run Z
This is much more useful than simply saying:
Don't touch generated files.
Pattern 7 — Testing-Heavy Project
Some projects place unusually strong emphasis on testing.
# Testing Guidelines
## Unit Tests
- Use Vitest for unit tests.
- Keep unit tests deterministic.
- Mock external network calls.
## Bug Fixes
- Add a regression test that fails before the fix and passes afterward.
## Integration Tests
- Use integration tests for database and API boundary behavior.
## End-to-End Tests
- Use Playwright for critical user flows.
- Prefer user-visible selectors over implementation-specific selectors.
## Validation
Before completing application changes:
- Run relevant unit tests.
- Run affected integration tests.
- Run `pnpm typecheck`.
Notice that the instructions define which test type belongs where.
That's much more useful than:
Write lots of tests.
Pattern 8 — Security-Sensitive Area
Suppose the repository contains:
src/
└── auth/
└── AGENTS.md
Authentication code may justify more specific guidance.
# Authentication Guidelines
## Credentials
- Never log passwords, access tokens, refresh tokens, or session secrets.
- Read secrets from environment variables.
## Authorization
- Perform authorization checks on the server.
- Do not rely on client-side UI checks for access control.
## Errors
- Do not expose internal authentication errors or stack traces to clients.
## Testing
When changing authentication or authorization behavior:
- Add tests for allowed access.
- Add tests for denied access.
This is a good example of when a nested file may be justified.
The area has meaningful additional requirements.
Pattern 9 — Documentation Project
AGENTS.md isn't only useful for application code.
Suppose you're maintaining developer documentation.
# Documentation Guidelines
## Writing
- Write for developers familiar with basic web development.
- Prefer short examples over long theoretical explanations.
- Define project-specific terminology on first use.
## Code Examples
- Use TypeScript for JavaScript examples.
- Keep examples runnable where practical.
- Do not include real credentials or secrets.
## Links
- Prefer relative links for documentation inside this repository.
- Check modified internal links before completing changes.
## Structure
- Follow the existing heading hierarchy.
- Keep one primary topic per page.
These instructions tell the agent how this documentation project expects content to be written.
Pattern 10 — Legacy Codebase
Legacy projects require a different approach.
The goal may be to avoid unnecessary modernization.
# Legacy Application Guidelines
## Changes
- Prefer focused changes over broad refactoring.
- Follow existing patterns unless the task explicitly includes modernization.
- Do not migrate libraries or frameworks as part of unrelated work.
## Dependencies
- Do not upgrade dependencies unless required by the task.
- Verify compatibility before introducing new dependencies.
## Testing
- Add regression tests when fixing bugs where the existing test infrastructure supports them.
## Scope
- Avoid modifying unrelated files.
This communicates an important project constraint:
Don't turn every task into a modernization project.
Pattern 11 — React Native / Expo Application
Consider:
mobile/
├── AGENTS.md
├── app/
├── components/
└── services/
A useful file might contain:
# Mobile Application Guidelines
## Stack
- React Native
- Expo
- TypeScript
## Components
- Use React Native primitives instead of web DOM elements.
- Reuse shared components before creating new ones.
- Keep platform-specific implementations isolated when required.
## Expo
- Prefer Expo-compatible libraries.
- Do not introduce native dependencies requiring prebuild unless necessary.
## Performance
- Avoid unnecessary re-renders in large lists.
- Use appropriate list components for large datasets.
## Testing
- Add tests for new business logic.
- Test platform-specific behavior when changing native integrations.
Again, the file focuses on project decisions, not teaching React Native.
Pattern 12 — Infrastructure
Infrastructure code has very different risks from frontend code.
# Infrastructure Guidelines
## Terraform
- Run `terraform fmt` after modifying Terraform files.
- Run `terraform validate` before completing infrastructure changes.
- Review the generated plan before applying changes.
## Safety
- Do not apply infrastructure changes automatically.
- Do not destroy resources unless explicitly required.
- Never hardcode credentials.
## Organization
- Reuse existing modules before creating new infrastructure abstractions.
This demonstrates why scoped instructions can matter.
The same rules would make little sense inside a React component directory.
What These Patterns Have in Common
Although the examples are different, notice the repeated structure.
Useful AGENTS.md files usually answer some combination of:
What stack are we using?
How is the code organized?
Where should new code go?
What project conventions matter?
What should not be modified?
How should changes be tested?
How should changes be validated?
The exact answers vary by project.
Don't Copy Every Section
You may notice sections such as:
Stack
Development
Architecture
Testing
Validation
Security
Documentation
Dependencies
That doesn't mean every AGENTS.md needs all of them.
For example, this may be perfectly useful:
# Project Guidelines
- Use `pnpm`.
- Keep business logic inside `src/services`.
- Do not manually edit files inside `src/generated`.
- Run `pnpm test` before completing application changes.
If that's all the project needs, stop there.
Build From Repository Reality
Don't start by asking:
What should an AGENTS.md contain?
Start by asking:
What does an agent need to know to work correctly in this repository?
Inspect:
package.json
Directory structure
Existing code
Tests
CI configuration
README
Architecture docs
Lint configuration
Build scripts
Then identify the instructions that aren't obvious or that are especially important.
A Practical Starting Template
If you need a starting point, use something small:
# Project Guidelines
## Development
- Use `<package-manager>`.
- Start development with `<command>`.
## Architecture
- `<important project boundary>`
- `<important code organization rule>`
## Testing
- `<when tests are required>`
- Run `<test-command>` when appropriate.
## Validation
Before completing changes:
- Run `<lint-command>`.
- Run `<typecheck-command>`.
- Run relevant tests.
## Boundaries
- `<important thing the agent must not modify>`
Then delete any section that doesn't provide value.
A template should help you start.
It shouldn't dictate your final file.
From Pattern to Sample
This lesson showed broad patterns.
The Samples section of this course will go further.
Instead of simply showing:
"Here's a Next.js AGENTS.md."
we'll explore specific scenarios such as:
Next.js + Supabase
Next.js + Prisma
Express API
NestJS API
React Native + Expo
Turborepo
Monorepo with shared packages
Legacy React app
OpenAPI-driven backend
Database migrations
Generated GraphQL clients
Authentication module
CI/CD repository
Terraform infrastructure
Testing-heavy application
Each sample will explain:
Scenario
↓
AGENTS.md
↓
What it does
↓
What it intentionally doesn't do
↓
Why the instructions are written that way
The goal isn't to build a collection of files to blindly copy.
The goal is to learn how to design the right instructions for different repositories.
Mini Exercise
Suppose you're building:
Next.js
TypeScript
Supabase
Tailwind CSS
Vitest
Which instruction is more useful?
Option A
- Use Next.js best practices.
- Write good TypeScript.
- Make sure the database is secure.
Option B
- Prefer Server Components unless client-side interactivity is required.
- Keep Supabase server-side data access inside `src/lib/supabase/server`.
- Never expose service-role credentials to browser code.
- Add Vitest tests for new business logic.
Option B.
It captures decisions specific to how the project is built.
Pattern Design Checklist
When creating an AGENTS.md, ask:
- What instructions apply across the entire repository?
- What architecture boundaries matter?
- Which commands should the agent run?
- What should never be modified directly?
- Which existing tools are the source of truth?
- What testing behavior is expected?
- Does any area need different scoped instructions?
- Am I documenting project decisions rather than generic programming knowledge?
- Can any instruction be removed without losing useful guidance?
Key Takeaway
There is no perfect universal AGENTS.md.
A good one is shaped by the repository.
A small Next.js application may need one short file.
A monorepo may need scoped instructions.
An authentication module may need additional security guidance.
A legacy application may need instructions preventing unnecessary modernization.
The pattern is always the same:
Understand the repository first. Then write the smallest set of instructions that helps the coding agent work correctly inside it.
Don't copy patterns blindly.
Understand why the pattern exists.
Then adapt it.
Up Next
AGENTS.md vs Skills vs Hooks vs Prompts
We've learned how to write and structure AGENTS.md.
But not every instruction belongs there.
In the final lesson we'll answer one of the most important questions:
Should this be in AGENTS.md, a Skill, a Hook, or the task Prompt?
Understanding that distinction will help you build a much cleaner coding-agent setup.