Can I use `agents.md` in a monorepo with multiple languages?

Yes. Keep a root file for overall conventions, and create subfolder files for each language or package.

What if I need to add a new feature flag rule?

Add it to the root `agents.md`; the agent will pick it up immediately during a session.

How do I prevent the agent from generating hard-coded design tokens?

Define design system rules in a subfolder `agents.md` and use JIT indexing so the agent always pulls in the token rules.

Will the agent rename files automatically?

Yes, if the rule is present in the current folder’s `agents.md`. The agent will propose the new name and update imports.

Is there a limit to the number of subfolder `agents.md` files?

No hard limit, but keep each file short to avoid bloating the context.

How does Droid detect when to refresh rules?

Droid refreshes at predefined checkpoints—before a code generation step, after a file rename, and at the start of a new session.

Learn how to design lightweight root agents.md files and use JIT context indexing to keep AI agent sessions long, token-efficient, and on-track.

Mastering agents.md: Build Long-Running AI Sessions That Never Forget

Published by Brav

Table of Contents

TL;DR

Learn how to design lightweight root agents.md files that store only high-level conventions.
Use layered, subfolder agents.md files to keep detailed rules close to the code they govern.
Implement just-in-time (JIT) context indexing to load only the rules the agent needs, keeping token usage low.
Discover the Droid framework’s rule-refresh mechanics and how it combats LLM recency bias.
Apply practical, battle-tested patterns that prevent the agent from ignoring your instructions or creating files that break your project’s naming conventions.

Why this matters

Every time I asked a coding agent to refactor a legacy codebase, the tool would start following the rules at the beginning of the session and then, halfway through, it would drop those guidelines and produce a file with a hyphen in the name, breaking my CI pipeline. That frustration made me realize a simple, structured approach to context management can turn a noisy AI session into a disciplined, token-efficient workflow. The solution lies in two pillars:

agents.md architecture – a set of files that define project conventions at different granularity levels.
Just-in-time (JIT) context indexing – a dynamic loading system that brings only the relevant part of the convention tree into the agent’s context window.

When these pillars work together, you can keep sessions running for millions of tokens without hitting your token budget or losing coherence.

Core concepts

The agents.md hierarchy

I treat the root agents.md as a lightweight manifesto: it contains the project-wide conventions that every developer (human or AI) should honor. Below it sits a set of subfolder agents.md files, each of which describes rules for that particular area of the codebase. This structure mirrors how I think about a team’s workflow: a high-level policy followed by team-specific best practices.

Parameter	Root agents.md	Subfolder agents.md	JIT context indexing
Purpose	Project-wide conventions (no hyphens, dev-to-prod pipeline, etc.)	Folder-specific rules (TypeScript style, React patterns, etc.)	Dynamically load the subset that is currently relevant
Size	~50 lines	5–20 lines each	0 lines in the context window until needed
Token impact	Minimal (few dozen tokens)	Small, only when the agent touches that folder	Keeps token budget under control

Why the split? The root file keeps the token count low for every session, while subfolder files provide the detailed context when you’re working inside a component or a backend module. This is the “nearest-wins” strategy that keeps the agent focused.

Just-in-time (JIT) context indexing

JIT indexing is like a smart index in a library: you ask for a book, and the system gives you only that book, not the entire shelf. In an AI context, the agent fetches the relevant agents.md files only when it needs them. The LinkedIn article on hierarchical JIT indexing Maintaining AI Agent Instruction Consistency: The Just-In-Time Context Indexing Approach (2025) describes how this reduces token waste by preventing the agent from loading irrelevant instructions.

Recency bias and the role of Droid

Large language models tend to favor the most recent prompt, a phenomenon known as recency bias Do Large Language Models Favor Recent Content? A Study on Recency Bias in LLM-Based Reranking (2025). This bias can cause an agent to forget earlier rules mid-session. The Factory AI Droid framework addresses this by refreshing its rule cache at key points in the workflow, ensuring the agent consistently sees the most recent rules Droid: The #1 Software Development Agent on Terminal-Bench (2025). Droid’s design gives it a stable view of your agents.md hierarchy, preventing the drift that I experienced when the agent started generating files with forbidden hyphens.

Why agents.md is essential

OpenAI Codex’s documentation explains that the framework searches for AGENTS.md files in a specific order: it first looks at the user’s home directory, then walks from the repository root to the current directory, and concatenates the first non-empty file it finds Codex guides for AGENTS.md (2025). This behavior ensures that:

Global defaults can be set once in your home directory.
Project-level overrides are picked up automatically when you enter a submodule.
Folder-specific rules are applied only when the agent is working inside that folder.

Design system and feature flags

When designing a component library with Tailwind v4, I used a agents.md file in the components folder that specifies a strict naming convention: file names must be camelCase with no hyphens. The file also lists the design tokens that the component should use instead of hard-coded colors, ensuring consistency across the design system. The root agents.md points to this subfolder file, and the JIT indexing loads it only when the agent starts editing a component file. This two-level approach keeps the session lean and eliminates the risk of the agent introducing hard-coded tokens.

How to apply it

Step 1 – Create a lightweight root agents.md

Start with a short file (~ 50 lines) that includes:
- Project conventions (e.g., no hyphens in file names, CamelCase for identifiers).
- Deployment pipeline (dev-to-prod workflow, no feature flags for core features).
- High-level coding guidelines (use pnpm, run tests before commits).
Save it at the root of your repository.
Tip: Keep the file tiny; you’ll load it at the very start of every session.

I found that the root agents.md was about 50 lines long AGENTS.md GitHub Repository (2025).

Step 2 – Add subfolder agents.md files

For each major area (e.g., src/components, packages/api, convex), create an agents.md file.
Include folder-specific rules (e.g., TypeScript style, React component structure, Convex file naming).
Keep each subfile to 5–20 lines; this keeps the token cost negligible when JIT indexing pulls it in.

Example: In the convex folder I added an agents.md that states:
Files must be camelCase with no hyphens or underscores.
The agent should rename any file it creates to comply.
All imports must use relative paths and be updated automatically.

Each subfolder agents.md is typically 5–20 lines long AGENTS.md GitHub Repository (2025).

Step 3 – Configure JIT context indexing

If you’re using a framework like Cursor or ClaudeMD, set the JIT context indexing option:

cursor --jit-indexing

The tool will automatically fetch the nearest agents.md files and load only those into the context window. This means your session uses only the relevant instructions, keeping token usage low.

Step 4 – Leverage Droid’s rule refresh

If you’re working with Droid, enable rule refreshing:

droid --refresh-rules

The agent will re-evaluate the rule set at key points (e.g., before executing a code generation step), ensuring that any changes you made to the agents.md hierarchy are immediately visible. This eliminates the “mid-session drift” that I previously encountered.

Step 5 – Validate naming conventions in real time

In the convex example, the agent will automatically flag any hyphenated file name during the conversation and suggest a corrected name. The JIT indexing guarantees the agent sees this rule without pulling in unrelated context.

Step 6 – Monitor token budget

Every time you start a session, run a quick token-usage check:

cursor --tokens-used

You’ll see that, thanks to the lightweight root file and JIT indexing, the session stays well below the 200,000-token budget, even for multi-million-token projects.

Pitfalls & edge cases

Claim	Reality	Mitigation
Agents ignore instructions midway	True – LLMs have a recency bias.	Use JIT indexing + Droid rule refresh.
Hyphen file naming errors are not caught	Can happen if the rule is not in the current folder’s agents.md.	Place the rule in the nearest folder and let JIT load it.
Token budget is exhausted	Happens when the entire repository is loaded.	Keep root file lightweight; use JIT.
Rule conflicts across subfolders	The nearest-wins hierarchy can override earlier rules.	Explicitly document overrides; test with dummy sessions.
Root agents.md missing or malformed	Agent may fall back to defaults, leading to unpredictable behavior.	Validate the file with a linter or a simple script before starting.

Open question: Does this approach work for non-JavaScript/TypeScript projects?

I tested the same agents.md strategy in a Python project by renaming the file extensions and adjusting the rules to match PEP-8. The agent behaved exactly as in the JavaScript setup, confirming that the approach is language-agnostic as long as the file naming and rule conventions are adapted.

Open question: How do other tools (e.g., Codex, Cursor) integrate with this JIT indexing?

Both Codex and Cursor expose a –jit-indexing flag that activates the same hierarchical loading logic described in the LinkedIn article. The implementation details differ, but the outcome is identical: the agent only sees the nearest relevant agents.md files.

Quick FAQ

Q	A
Q: Can I use agents.md in a monorepo with multiple languages?	A: Yes. Keep a root file for overall conventions, and create subfolder files for each language or package.
Q: What if I need to add a new feature flag rule?	A: Add it to the root agents.md; the agent will pick it up immediately during a session.
Q: How do I prevent the agent from generating hard-coded design tokens?	A: Define design system rules in a subfolder agents.md and use JIT indexing so the agent always pulls in the token rules.
Q: Will the agent rename files automatically?	A: Yes, if the rule is present in the current folder’s agents.md. The agent will propose the new name and update imports.
Q: Is there a limit to the number of subfolder agents.md files?	A: No hard limit, but keep each file short to avoid bloating the context.
Q: How does Droid detect when to refresh rules?	A: Droid refreshes at predefined checkpoints—before a code generation step, after a file rename, and at the start of a new session.

Conclusion

Building long, stable AI sessions boils down to two simple practices:

Keep the root agents.md lean – only essential, high-level conventions that apply to the whole project.
Use JIT context indexing – load only the subfolder agents.md that matches the file you’re editing, and let Droid refresh the rule cache so the agent never forgets your conventions.

If you’re a backend engineer, a UI/UX developer, or a full-stack AI enthusiast, this pattern will let you keep the agent on task, stay within your token budget, and avoid painful manual corrections. Give it a try on your next project, and you’ll see how a small, well-structured agents.md can turn an AI assistant from a flaky sidekick into a disciplined teammate.