# How To Link Root AGENTS.md And agent-docs

## Preferred Patterns

### Root -> Topic Docs

Use when the repository has a small set of clearly separate instruction topics.

```md
# Required `agent-docs` Before Editing

- Read and follow `agent-docs/topic-a.md` when ...
- Read and follow `agent-docs/topic-b.md` when ...
```

### Root -> Project Doc -> Leaf Docs

Use when one project-specific document should explicitly reference several closely related leaf docs.

```md
AGENTS.md
  -> agent-docs/project-guidelines.md
      -> agent-docs/topic-a.md
      -> agent-docs/topic-b.md
```

Use this only when the intermediate layer reduces ambiguity or repeated cross-reference text.

### Root -> Subproject `agent-docs/`

Use in monorepos when a subproject has its own scoped instruction set.

```md
AGENTS.md
  -> apps/docs/agent-docs/project-guidelines.md
  -> services/api/agent-docs/backend-guidelines.md
```

Common rules stay in the root `AGENTS.md`. Subproject-specific rules stay near the subproject they govern.

## Anti-Patterns

- Root file linking to every leaf doc in a large tree without grouping
- Child docs that are never reachable from the root
- Topic-specific rules stored in the root file without a reference reason
- Extra index files that only restate links without adding scope or decision logic
- Moving rules out of the root file without leaving an explicit reference to the new child file
- Keeping monorepo-wide and subproject-specific constraints mixed together in the same root section when they can be separated cleanly

## Explicit Reference Rule

Parent documents should point to the child documents that refine them.

If a child document exists and is active, there must be an explicit reference path from the root `AGENTS.md` to that document.

The root `AGENTS.md` should list only the next `agent-docs` documents that are actually needed. Do not add unnecessary next-step links just for completeness.