Ge Song
4fa6e18940
Add dedicated reference for root AGENTS.md to agent-docs linking patterns with anti-patterns and explicit reference requirements. Update SKILL.md core rules to emphasize directional, explicit references and minimal reference depth. Refine template structures in inventory-doc-template.md and root-agents-template.md to enforce clearer scope sections and required reading lists. Update agent interface metadata to reflect focused maintenance scope.
57 lines
1.9 KiB
Markdown
57 lines
1.9 KiB
Markdown
# 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.
|