What Does NOT Belong in AGENTS.md
A common mistake with AGENTS.md is thinking:
"If more context helps the agent, let's give it everything."
That can quickly turn a useful instruction file into a large knowledge dump.
The goal isn't to provide maximum context.
The goal is to provide relevant instructions.
Let's look at what should usually stay out.
1. Secrets and Credentials
Never put secrets inside AGENTS.md.
❌ Never do this
# Database
DATABASE_URL=postgresql://admin:password123@production-db.example.com
STRIPE_SECRET_KEY=sk_live_xxxxx
AGENTS.md normally lives inside your repository.
Secrets committed there could become visible to:
- Other developers.
- Repository collaborators.
- CI/CD systems.
- Logs.
- Public repositories.
Instead, tell the agent how secrets should be handled.
✅ Better
## Environment
- Read database credentials from `DATABASE_URL`.
- Store local secrets in `.env.local`.
- Never commit `.env` files.
- Never hardcode credentials in source code.
The rule belongs in AGENTS.md.
The secret does not.
2. Generic Programming Knowledge
You usually don't need to teach the coding agent basic programming concepts.
❌ Unnecessary
JavaScript supports asynchronous programming.
React applications are built using components.
TypeScript adds static typing to JavaScript.
REST APIs commonly use HTTP methods such as GET and POST.
These instructions consume space without telling the agent anything specific about your repository.
Instead, describe your implementation choices.
✅ Better
- Use TypeScript for all new source files.
- Use Server Components by default.
- Use Route Handlers for HTTP APIs.
The difference is important:
General knowledge
❌
Project-specific guidance
✅
3. Your Entire README
Some overlap between README.md and AGENTS.md is perfectly reasonable.
But don't blindly copy the README.
❌ Avoid
# About Our Company
...
# Product Features
...
# Installation
...
# Screenshots
...
# Contributors
...
# License
...
Most of this may be useful to humans without changing how an agent should implement code.
Instead, extract the relevant working instructions.
README
Run the application locally using:
pnpm install
pnpm dev
AGENTS.md
## Development
- Use `pnpm` for dependency management.
- Start local development with `pnpm dev`.
Don't duplicate documentation without a reason.
4. Temporary Task Instructions
Suppose today you're asking the agent:
Fix the login button on mobile.
Don't add this to your permanent AGENTS.md:
## Current Task
Fix the login button on mobile.
Make the button 100% width.
Then check the signup page.
That's a task prompt, not a repository instruction.
Tomorrow the task will be irrelevant.
Keep persistent instructions in AGENTS.md.
Give temporary instructions through the current task or prompt.
Think:
Persistent repository rule
↓
AGENTS.md
Current task
↓
Prompt / task description
5. Personal Preferences That Don't Matter
Be careful about adding preferences simply because you like them.
❌ Questionable
- Prefer functions shorter than 20 lines.
- Never use ternary operators.
- Always alphabetize object properties.
- Use exactly one blank line between logical sections.
Some teams genuinely enforce rules like these.
If your project does, they may belong.
But don't fill AGENTS.md with arbitrary preferences that don't improve correctness or maintainability.
Better yet, when a rule can be automatically enforced, use tooling.
For example:
Formatting
→ Prettier
Lint rules
→ ESLint
Type correctness
→ TypeScript
Repository-specific working instructions
→ AGENTS.md
Don't make AGENTS.md manually enforce everything your tools already enforce reliably.
6. Huge Architecture Documentation
Architecture context can be extremely useful.
But AGENTS.md shouldn't necessarily become your complete architecture document.
❌ Too Much
# Architecture
Our platform contains 17 services...
Service A communicates with Service B...
[300 lines later]
The complete database schema is...
If your architecture is complex, maintain dedicated documentation.
For example:
docs/
├── architecture.md
├── database.md
└── api-design.md
Then AGENTS.md can contain the instructions that directly affect implementation:
## Architecture
- Keep business logic inside services.
- Access the database through repositories.
- See `docs/architecture.md` when changing service boundaries.
This keeps the instruction file focused while still pointing the agent toward deeper documentation.
7. Large API Documentation
Similarly, don't paste your entire API specification into AGENTS.md.
❌ Avoid
GET /users
GET /users/:id
POST /users
PUT /users/:id
DELETE /users/:id
Request schema...
Response schema...
If your project already has:
openapi.yaml
use it.
Your AGENTS.md might simply say:
## API
- Follow `openapi.yaml` when modifying public API behavior.
- Update the OpenAPI specification when changing an endpoint contract.
This keeps one source of truth.
8. Information the Repository Already Expresses Clearly
Avoid unnecessarily repeating information that's already obvious and reliably enforced.
For example, if package.json clearly establishes:
{
"packageManager": "pnpm@10.0.0"
}
you don't necessarily need several paragraphs explaining why the project uses pnpm.
A short instruction may still be useful:
- Use `pnpm` for package management.
But avoid excessive repetition.
9. Duplicated Instructions
Consider:
## Development
- Run tests before finishing.
## Testing
- Always run tests.
## Workflow
- Make sure tests run before completing work.
## Quality
- Don't forget to run tests.
These are essentially the same instruction four times.
Duplication creates noise and makes maintenance harder.
✅ Better
## Validation
Before completing application changes:
- Run `pnpm test`.
One clear instruction is usually better than several variations.
10. Contradictory Instructions
This is worse than duplication.
Earlier
- Use npm for dependency management.
Later
- Always use pnpm.
Now the agent has conflicting guidance.
Another example:
- Always add tests for bug fixes.
followed by:
- Don't modify tests unless explicitly requested.
Sometimes conflicts arise because instructions were added at different times.
Regularly review your AGENTS.md for:
Duplicates
Contradictions
Outdated rules
Unnecessary instructions
11. Outdated Instructions
Stale instructions can be worse than missing instructions.
Imagine your project migrated:
Jest
↓
Vitest
but AGENTS.md still says:
- Run tests using `npm run jest`.
The agent may faithfully follow an instruction that's no longer correct.
When your development workflow changes, update the corresponding agent instructions.
Treat AGENTS.md as code-adjacent documentation that needs maintenance.
12. Instructions for Every Possible Situation
Avoid trying to predict every possible task.
❌ Over-engineered
If modifying a button...
If modifying a modal...
If adding a tooltip...
If adding a database column...
If changing a date field...
If changing a checkbox...
This can grow indefinitely.
Prefer principles and project-specific boundaries that cover many situations.
For example:
## UI
- Reuse components from `src/components/ui` before creating new ones.
- Follow existing component patterns.
- Ensure interactive controls remain keyboard accessible.
A few useful rules can guide many tasks.
13. Things Better Enforced by Tools
Suppose your project requires:
2-space indentation
single quotes
trailing commas
You could write:
- Use 2 spaces.
- Use single quotes.
- Always include trailing commas.
But if Prettier already enforces these rules, that's usually the stronger source of truth.
Your AGENTS.md can simply say:
- Run `pnpm format` when formatting changes are required.
Use the right mechanism for the job.
Formatting → Formatter
Static rules → Linter
Types → Type checker
Tests → Test runner
Agent working guidance → AGENTS.md
Before and After
Imagine this AGENTS.md:
❌ Before
# Project
React is a library for building user interfaces.
TypeScript adds static typing to JavaScript.
Our company was founded in 2022.
Always write clean code.
Always use meaningful names.
Use pnpm.
Run tests before finishing.
Never commit secrets.
Current task: Fix the dashboard navigation.
Run tests before finishing.
Our complete API documentation:
[200 lines of API documentation...]
There's useful information here, but it's buried in noise.
✅ After
# Project Guidelines
## Development
- Use `pnpm` for dependency management.
## Validation
Before completing application changes:
- Run `pnpm lint`.
- Run `pnpm test`.
## Security
- Never commit secrets or `.env` files.
## API
- Follow `openapi.yaml` for public API contracts.
- Update the specification when changing API behavior.
Much shorter.
Much clearer.
Much easier to maintain.
The Removal Test
When reviewing an instruction, ask:
What would happen if I removed this?
If the answer is:
"Probably nothing—the agent already knows this."
consider removing it.
If the answer is:
"The agent might violate an important project convention."
keep it.
For example:
React components can receive props.
Remove it.
But:
Never manually modify files inside `src/generated`.
Keep it.
Another Useful Test
Ask where the information naturally belongs.
Repository working rule?
→ AGENTS.md
Human onboarding documentation?
→ README / docs
Temporary task?
→ Prompt
Formatting rule?
→ Formatter
Static code rule?
→ Linter
API contract?
→ OpenAPI
Secret?
→ Secret manager / environment
Reusable specialized workflow?
→ Potentially a Skill
AGENTS.md is one part of your development environment—not the place where everything has to live.
Keep It Focused
A useful principle is:
Include enough instruction to guide the agent, but not enough noise to distract it.
Don't optimize for:
"How much information can we give the agent?"
Optimize for:
"What information changes how the agent should work?"
Key Takeaway
Avoid filling AGENTS.md with:
- Secrets.
- Generic programming tutorials.
- Entire README files.
- Temporary tasks.
- Arbitrary personal preferences.
- Huge architecture documents.
- Complete API specifications.
- Duplicate instructions.
- Contradictory instructions.
- Outdated rules.
- Instructions better enforced by tooling.
A good AGENTS.md isn't necessarily a large one.
It's a focused one.
Up Next
Writing Effective Instructions
Now that we know what belongs—and what doesn't—we'll focus on the actual wording.
We'll turn instructions like:
"Write good tests."
into instructions an agent can actually act on and verify.