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

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 🛠️

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

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