Context is precious. Don't waste it. 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. 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. AGENTS.md CLAUDE.md GEMINI.md 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 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 🛠️ Create a root AGENTS.md with global rules: coding standards, commit format, architecture overview, and general gotchas


Add subdirectory AGENTS.md files in each major area (model/, tests/, api/) with area-specific rules


Create AGENTS.local.md for personal preferences and add it to .gitignore


Keep files short, opinionated, and actionable—three bullets over three paragraphs


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 Create a root AGENTS.md with global rules: coding standards, commit format, architecture overview, and general gotchas Create a root AGENTS.md with global rules: coding standards, commit format, architecture overview, and general gotchas AGENTS.md Add subdirectory AGENTS.md files in each major area (model/, tests/, api/) with area-specific rules Add subdirectory AGENTS.md files in each major area (model/, tests/, api/) with area-specific rules AGENTS.md model/ tests/ api/ Create AGENTS.local.md for personal preferences and add it to .gitignore Create AGENTS.local.md for personal preferences and add it to .gitignore AGENTS.local.md .gitignore Keep files short, opinionated, and actionable—three bullets over three paragraphs Keep files short, opinionated, and actionable—three bullets over three paragraphs 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 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 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 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). 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. manage your context 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. 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. 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 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 AGENTS.md Consider adding AGENTS.md when you create new subdirectories AGENTS.md Review your root file regularly. Outdated rules mislead more than good guidance. See Outdated Documentation Outdated Documentation Avoid AI external comments 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 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 AGENTS.local.md Tags 🏷️ Standards Standards Level 🔋 [X] Intermediate Related Tips 🔗 https://hackernoon.com/ai-coding-tip-005-how-to-keep-context-fresh?embedable=true https://hackernoon.com/ai-coding-tip-005-how-to-keep-context-fresh?embedable=true https://hackernoon.com/ai-coding-tip-005-how-to-keep-context-fresh https://hackernoon.com/ai-coding-tip-005-how-to-keep-context-fresh Use examples in your AGENTS.md, not just descriptions Version-control your AGENTS.md alongside your code Version-control your AGENTS.md alongside your code Conclusion 🏁 You don't need one perfect AGENTS.md. 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?embedable=true https://craftbettersoftware.com/p/stop-using-claude-code-like-a-chatbot?embedable=true https://docs.anthropic.com/en/docs/claude-code/memory?embedable=true https://docs.anthropic.com/en/docs/claude-code/memory?embedable=true https://docs.cursor.com/context/rules-for-ai?embedable=true https://docs.cursor.com/context/rules-for-ai?embedable=true https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot?embedable=true https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot?embedable=true https://openai.com/blog/custom-instructions-for-chatgpt?embedable=true https://openai.com/blog/custom-instructions-for-chatgpt?embedable=true https://aider.chat/docs/usage/conventions.html?embedable=true https://aider.chat/docs/usage/conventions.html?embedable=true https://sourcegraph.com/docs/cody?embedable=true https://sourcegraph.com/docs/cody?embedable=true https://nx.dev/concepts/mental-model?embedable=true https://nx.dev/concepts/mental-model?embedable=true https://www.anthropic.com/research/claude-character?embedable=true https://www.anthropic.com/research/claude-character?embedable=true https://www.promptingguide.ai/?embedable=true https://www.promptingguide.ai/?embedable=true Also Known As 🎭 Hierarchical context files
Layered instructions
Nested AI rules
Scoped assistant configuration 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) Claude Code (CLAUDE.md) CLAUDE.md Cursor (.cursorrules / .cursor/rules) .cursorrules .cursor/rules GitHub Copilot (.github/copilot-instructions.md) .github/copilot-instructions.md Aider (CONVENTIONS.md) CONVENTIONS.md Continue.dev (.continuerc.json) .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. AI Coding Tip https://maximilianocontieri.com/ai-coding-tips https://maximilianocontieri.com/ai-coding-tips

GitHub

Keep

AI Coding Tip 013 - Stop Wasting Tokens With Progressive Disclosure

Buy My Book

AI Coding Tip 014 - One AGENTS.md Is Hurting Your AI Coding Assistant

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

10 Predictions About the Future of Finance

How My Development Team Utilized GitHub Copilot & AI Tools to Boost Productivity by Vimaldeep Singh

Developer Productivity with GitHub Copilot & AI Tools by Aditya Mishra

Zero Trust, Zero Bugs? The AI Blueprint for Building Unbreakable Software Systems

Exploring AWS Q Developer: The AI-Powered Coding Companion for Modern Developers

Meet the Dev Tool That Kills Stack Overflow Tabs for Good

10 Predictions About the Future of Finance

How My Development Team Utilized GitHub Copilot & AI Tools to Boost Productivity by Vimaldeep Singh

Developer Productivity with GitHub Copilot & AI Tools by Aditya Mishra

Zero Trust, Zero Bugs? The AI Blueprint for Building Unbreakable Software Systems

Exploring AWS Q Developer: The AI-Powered Coding Companion for Modern Developers

Meet the Dev Tool That Kills Stack Overflow Tabs for Good

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps