Files

Ge Song 4fa6e18940 docs(bluecraft-agentic-docs): document explicit linking patterns and update skill rules

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.

2026-04-20 12:54:30 +08:00

1.9 KiB

Raw Blame History

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.

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

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.

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.

1.9 KiB Raw Blame History