63 lines
2.3 KiB
Markdown
63 lines
2.3 KiB
Markdown
# 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.
|