AI Coding Tip 014 - Use Nested AGENTS.md Files

Question

Context is precious. Don't waste it.

TL;DR: Split your AGENTS.md into layered files so your AI loads only the rules that matter for the code you touch.

Common Mistake ❌

You put a single massive AGENTS.md , CLAUDE.md , GEMINI.md at your project root and cram everything into it.

Framework rules, database patterns, front-end conventions, and continuous integration configuration—all loaded at once.

Your AI reads rules that have nothing to do with what you're actually working on.

This wastes context and weakens the guidance that matters.

Problems Addressed

• Your AI follows rules meant for other parts of the codebase
• Irrelevant context crowds out the rules you actually need
• Updating one big file can break guidance for unrelated areas
• Teammates get confused by your personal preferences

How to Do It ️

1. Create a root AGENTS.md with global rules: coding standards, commit format, architecture overview, and general gotchas
2. Add subdirectory AGENTS.md files in each major area (model/, tests/, api/) with area-specific rules
3. Create AGENTS.local.md for personal preferences and add it to .gitignore
4. Keep files short, opinionated, and actionable—three bullets over three paragraphs
5. Trust the loading system: most tools load root files at startup and subdirectory files only when you touch files there

   FermiCalculator/
   ├── AGENTS.md       ← loaded at startup (always) with general
   │                   rules
   ├── model/
   │   └── AGENTS.md   ← loaded when you make changes to your
   │                   model/, model conventions
   ├── tests/
   │   └── AGENTS.md   ← loaded when you change your tests/,
   │                   mocking rules
   ├── ui/
   │   └── AGENTS.md   ← loaded when you make changes to ui/,
   │                   UI code standards
   └── api/
   │   └── AGENTS.md   ← loaded when you make changes to api/,
   │                   OpenApi formatting
   └── database/
   │   └── AGENTS.md   ← loaded when you make changes to the
   │                   persistence/ DDL Rules
   

Benefits

• The AI reads only rules relevant to what you're working on
• You reduce context waste in every session
• Each team area owns its own guidance independently
• Personal preferences stay personal — they don't pollute shared files
• Smaller files are easier to review and maintain

Context

AI coding assistants load context files to understand your project.

Tools like Claude Code, Cursor, and Copilot support instruction files (AGENTS.md, CLAUDE.md, .cursorrules).

When you put everything in one file, your assistant can't filter what's relevant.

The layered approach works like good software: separation of concerns.

The root file sets foundations.

Subdirectory files add specifics.

Local files hold personal quirks.

This helps any project with multiple distinct areas—monorepos benefit most.

Remember, you always need to manage your context wisely.

Prompt Reference

Bad Prompt:

Here are all the conventions for my project:

[pastes 200 lines of mixed rules for backend, frontend, 
mobile, and CI]

Now help me fix this React component.

Good Prompt:

I'm working in UI/. My AGENTS.md for this area says: 

use functional components, no class components,

Tailwind only for styling, 

test with React Testing Library.

Help me fix this component.

Considerations ⚠️

• Not all tools support lazy loading of subdirectory files—check your tool first
• A short bad AGENTS.md hurts less than a long one. Vague rules get ignored or misapplied
• Consider adding AGENTS.md when you create new subdirectories
• Review your root file regularly. Outdated rules mislead more than good guidance. See Outdated Documentation
• Avoid AI external comments

Type

[X] Semi-Automatic

Limitations ⚠️

• Works best with tools that support hierarchical context loading (Claude Code, Cursor, some Copilot)
• Single-file projects don't need this structure
• You still need good rules—the hierarchy only helps if the content is solid
• AGENTS.local.md support varies by tool; check your documentation

Tags ️

• Standards

Level

[X] Intermediate

Related Tips

https://coderlegion.com/11001/ai-coding-tip-005-keep-context-fresh

• Use examples in your AGENTS.md, not just descriptions
• Version-control your AGENTS.md alongside your code

Conclusion

You don't need one perfect AGENTS.md.

You need the right rules in the right place.

Split context by area, keep files tight, and let tools load only what's relevant.

Your AI works better with less noise.

More Information ℹ️

https://craftbettersoftware.com/p/stop-using-claude-code-like-a-chatbot

https://docs.anthropic.com/en/docs/claude-code/memory

https://docs.cursor.com/context/rules-for-ai

https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot

https://openai.com/blog/custom-instructions-for-chatgpt

https://aider.chat/docs/usage/conventions.html

https://sourcegraph.com/docs/cody

https://nx.dev/concepts/mental-model

https://www.anthropic.com/research/claude-character

https://www.promptingguide.ai/

Also Known As

• Hierarchical context files
• Layered instructions
• Nested AI rules
• Scoped assistant configuration

Tools

• Claude Code (CLAUDE.md)
• Cursor (.cursorrules / .cursor/rules)
• GitHub Copilot (.github/copilot-instructions.md)
• Aider (CONVENTIONS.md)
• Continue.dev (.continuerc.json)

Disclaimer

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

---

This article is part of the AI Coding Tip series.

https://coderlegion.com/12469/ai-coding-tips