How Factory Droid CLI Discovers AGENTS.md (2026)

Factory’s Droid CLI supports AGENTS.md — that part is easy to find in their marketing. What’s harder to find is the actual discovery mechanism: which folders it checks, what order it applies them in, and what happens when a nested directory has its own file. We went through Factory’s documentation line by line to answer that.

AGENTS.md is a Markdown file that AI coding agents read for project-specific instructions — build commands, code conventions, and validation steps that don’t belong in a human-facing README. Factory’s Droid CLI is one of a growing list of tools that read it, alongside Claude Code, Codex, Cursor, and Gemini CLI.

Where Droid Actually Looks

Droid doesn’t just check the repository root. It searches hierarchically from your current working directory up to the git root, checking three project-level folder names at each level:

• .factory/ — Factory-specific instructions
• .agents/ — shared agent folder, for compatibility with other tools that use the plural form
• .agent/ — singular variant, same purpose

It repeats the same check at the personal level, in your home directory:

• ~/.factory/
• ~/.agents/
• ~/.agent/

That’s six possible locations before you even get to which filename Droid accepts inside them. If you’ve been dropping a single AGENTS.md at your repo root and assuming that’s the whole story, you’re only using one of the paths Droid checks.

The Precedence Order

When multiple candidate files exist, Droid applies them in this order, highest priority first:

1. The current user request (explicit instructions always win)
2. Nested project files — files deeper in the directory tree, scoped to that subtree
3. Root project files — the top-level file at the git root
4. Personal default files — your home-directory fallback

This is a strict override chain, not a merge. A nested file doesn’t add to the root file’s instructions; it replaces them for anything in its subtree.

Nested Files Override, They Don’t Merge

Factory’s own example illustrates the pattern: when Droid later reads files under apps/web/, it discovers apps/web/AGENTS.md and applies it in place of the root-level file for anything scoped to that directory.

my-project/
├── AGENTS.md                 # applies everywhere by default
├── apps/
│   └── web/
│       └── AGENTS.md          # overrides the root file for this subtree
└── apps/
    └── api/                    # no local AGENTS.md — falls back to root

Work inside apps/web/ and only apps/web/AGENTS.md is in effect — the root instructions for that subtree are replaced, not appended to. Work inside apps/api/ and the root file still applies, since there’s no local override. If you’re used to Claude Code’s nested CLAUDE.md behavior, this will feel familiar: it’s the same override-not-merge model, not an accumulation of every file along the path.

Yes, It Reads CLAUDE.md Too

This is the part most coverage skips. Droid’s compatible filenames aren’t limited to AGENTS.md:

If you already have a CLAUDE.md maintained for Claude Code, Droid reads it directly — no migration, no symlink, no duplicate file. That’s a meaningfully different stance from tools like Cursor, which reads AGENTS.md as an alternative to its own .cursor/rules format but doesn’t recognize CLAUDE.md by name. For a team running both Claude Code and Droid against the same repo, this means one file can serve both, provided the content itself doesn’t lean on Claude-Code-specific syntax like @import references.

Context Budget: 80,000 vs 40,000 Characters

Droid enforces two separate character limits, and the distinction matters for how you structure a large project’s instructions:

• Initial load: 80,000 characters maximum — this is the budget for what gets pulled in when a session starts.
• Dynamic discovery: 40,000 characters maximum — a smaller budget applies to files discovered later, as Droid reads into new subdirectories mid-session.

Factory’s own guidance is blunt about the implication: smaller files are usually better. An AGENTS.md that’s bumping against either ceiling is a file that’s trying to do too much — split project-wide conventions from directory-specific detail and let the nested-file mechanism do the work instead of one enormous root file.

settings.json vs AGENTS.md: The Same Split as Claude Code

If you already run Claude Code, this division will look familiar. Droid keeps behavioral/workflow configuration separate from project instructions:

Factory’s documentation explicitly tells you to use AGENTS.md for “repository instructions, conventions, and validation commands” rather than their older .droid.yaml format — the same permissions-vs-instructions split Claude Code draws between settings.json and CLAUDE.md.

A Structure That Fits Droid’s Discovery Model

Given the nested-override behavior, a root AGENTS.md should hold what’s true everywhere, and subtree files should hold only what changes locally:

# AGENTS.md

## Project Overview
[1-2 sentences: what this is, primary stack]

## Commands
Install: `npm install`
Build: `npm run build`
Test: `npm test`
Type check: `npx tsc --noEmit`
Lint: `npm run lint`

## Project Layout
[Directory-by-directory summary]

## Conventions
[Coding patterns, dependency philosophy]

## Verification
[Checklist to run before considering a task complete]

## Safety Rules
[Secrets handling, destructive-command restrictions, generated-file boundaries]

Keep this at the root. Only add an apps/web/AGENTS.md if that subtree genuinely needs different commands or conventions — otherwise you’re fragmenting instructions Droid will apply inconsistently depending on which file it last read.

What Not to Put in AGENTS.md

Factory’s guidance calls out several categories to keep out, and they overlap with mistakes we’ve seen across every tool that reads this format:

• Secrets or credentials of any kind
• Inventories that go stale quickly (dependency version lists, file counts)
• Personal preferences that conflict with project-wide rules
• Temporary task notes that belong in a PR description instead
• Instructions to skip validation steps

FAQ

Q1. Does Factory’s Droid CLI read AGENTS.md automatically, or do I need to enable something? Automatically. Droid searches .factory/, .agents/, and .agent/ folders from your working directory up to the git root, plus the equivalent folders in your home directory, with no configuration required.

Q2. Will Droid use my existing CLAUDE.md if I don’t have an AGENTS.md? Yes. CLAUDE.md and Claude.md are both on Droid’s list of compatible filenames, alongside AGENTS.md, agents.md, and Agents.md. Factory recommends AGENTS.md for new projects, but existing Claude Code repos don’t need a duplicate file.

Q3. If I have both a root AGENTS.md and a nested one in a subdirectory, do they combine? No. Nested files override the root file for their subtree; they don’t merge with it. Anything you want applied everywhere needs to live in the root file, since a subtree’s local file replaces it rather than extending it.

Q4. What happens if my AGENTS.md is longer than 80,000 characters? It exceeds Droid’s initial-load budget. Factory’s guidance is to keep files smaller and split project-wide rules from directory-specific detail using nested files, rather than relying on one large root file.

Q5. Does Droid’s settings.json replace AGENTS.md? No — they cover different things. settings.json (personal or project-level, under .factory/) controls model defaults, permissions, and hook/MCP behavior. AGENTS.md covers project instructions, commands, and conventions. Factory explicitly recommends AGENTS.md over the older .droid.yaml for the latter.

Q6. Can I use the same AGENTS.md for both Claude Code and Droid CLI? Usually yes, since both read the same filename and a similar hierarchical model. Avoid Claude-Code-specific syntax like @file import references if you want the file to behave identically in both tools — Droid’s documentation doesn’t confirm it resolves those the same way.

Related Reading on The Prompt Shelf

• AGENTS.md for OpenAI Codex: Complete Setup and Configuration Guide (2026)
• AGENTS.md for Gemini CLI: How Google’s Agent Reads Your Instructions
• AGENTS.md vs CLAUDE.md: Tool Support Compared (2026)
• Does Claude Code Support AGENTS.md? The Complete 2026 Reference
• AGENTS.md Not Loading? How to Debug It in 2026

Keep Secrets Out of AGENTS.md Entirely

Factory’s own guidance says not to put credentials in AGENTS.md — but that only solves half the problem if they’re still sitting in a .env file an agent can read alongside it. 1Password CLI’s op run injects secrets at runtime instead, so there’s nothing in the repo for an AGENTS.md-reading agent — or a teammate browsing the same folders — to stumble into.