Precedence for Nested AGENTS.md: A Merge Design for Many Projects in One Workspace

Decide the merge in code, not prose

Once the principle is set, lower it into the process that actually binds the files. Collect AGENTS.md from the edit target toward the root, and stack them weakest first.

from pathlib import Path
 
def collect_agents_files(target: Path, root: Path) -> list[Path]:
    """Collect AGENTS.md from target toward root, return weakest first (root first)"""
    files = []
    cur = target if target.is_dir() else target.parent
    while True:
        candidate = cur / "AGENTS.md"
        if candidate.exists():
            files.append(candidate)
        if cur == root:
            break
        cur = cur.parent
    return list(reversed(files))   # root -> near = weak -> strong
 

The reversed line is the point. You collect in the "near -> root" direction, but stack in "root -> near." Lay the weak as the foundation and pile the strong on top afterward, so the closer instruction wins last.

Distinguish overriding from appending

Stacking alone is not enough, because instructions come in two kinds. Ones that should settle to a single value ("commit in English" — override) and ones that should add up ("a forbidden-word list" — append). Read AGENTS.md section by section and merge each kind differently.

import re
 
# Separate sections to append (merge) from sections to override (replace)
APPEND_SECTIONS = {"Forbidden words", "Prohibitions", "Glossary", "Caveats"}
 
def parse_sections(text: str) -> dict[str, str]:
    sections, cur, buf = {}, None, []
    for line in text.splitlines():
        m = re.match(r"^#{1,3}\s+(.*)", line)
        if m:
            if cur is not None:
                sections[cur] = "\n".join(buf).strip()
            cur, buf = m.group(1).strip(), []
        else:
            buf.append(line)
    if cur is not None:
        sections[cur] = "\n".join(buf).strip()
    return sections
 
def merge(files: list[Path]) -> dict[str, str]:
    merged: dict[str, str] = {}
    for f in files:                       # process weakest first
        for name, body in parse_sections(f.read_text(encoding="utf-8")).items():
            if name in APPEND_SECTIONS and name in merged:
                merged[name] += "\n" + body   # add up
            else:
                merged[name] = body           # closer overrides
    return merged

Mistake override for append and you stumble in a quiet way. Treat a forbidden-word list as override and, meaning to add a project-specific word, you wipe the shared list whole. Treat the commit language as append and both English and Japanese survive as instructions, leaving the agent to waver. Sorting by the nature of the section is the design that holds up in production.

Shared rules at the root, specific rules per project

With the merge mechanism settled, the judgment of "what goes where" arrives next. What I recommend, when unsure, is keeping the shared side thin and the specific side thick.

1. Put at the root only what every project should keep identically.
2. Push any rule with even one exception down from the root into each project.
3. Don't park "probably shared" in the shared file; promote it only once a second project genuinely needs the same instruction.

There's a reason for this lean. A root rule reaches every project, so a mistake there has wide blast radius. Write an App Store asset-naming convention at the root as "probably shared" and an unrelated constraint rains down even on a project that only handles AdMob reports. Promoting to shared can wait until the second need is confirmed.

Field notes: keep AGENTS.md thin

One last impression reached by running this. AGENTS.md grows fat if left alone.

Each time something goes wrong you want to add a line, and before long every file is enormous. Long instruction files raise the number of collisions when merged and make precedence hard to trace. I make a point of regularly rereading each AGENTS.md and trimming on "is this truly needed" and "does it duplicate the level above."

Closer is stronger, separate override from append, keep the shared side thin — hold just these three and the agent's behavior stays readable even with many projects bound into one workspace. Readable behavior is, when running unattended, the reassurance I value most.