# Linking Patterns

## 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 only when the intermediate layer reduces ambiguity or repeated cross-reference text.

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

### 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.

## Conflict Resolution Rule

- More specific scope beats broader scope.
- A child doc with explicit task scope beats a generic note in the root file.
- A rule doc's behavior rule beats an inventory entry's shorthand wording.
- If two active docs both read like authoritative owners for the same rule, do not improvise a priority. Treat it as duplicate authority and refactor the tree.
- If two sibling docs are equally specific and both explicitly apply, do not break the tie by tone or wording. Report the ambiguity and refactor the tree.