Root instructions should describe shared invariants; package instructions should describe local reality.
The decision behind the technique
A monorepo-wide instruction file becomes noisy when every framework and service has different commands. Layering keeps each task’s automatic context relevant.
Root instructions should describe shared invariants; package instructions should describe local reality.
A practical step-by-step workflow
Use this sequence as a default, then tighten or expand it only when the evidence changes.
- Define repository-wide safety and integration rules at the root
- Add package-level build and test commands near each package
- Document which rules override or extend the root
- Run a task in two different packages to detect leakage
Failure boundary and finish line
Do not duplicate the same command in several layers unless ownership and update rules are explicit.
Finish when the configuration is smaller, reproducible and still preserves every required safety boundary.
Frequently asked questions
What should I do first?+
Define repository-wide safety and integration rules at the root
What is the main failure mode?+
Do not duplicate the same command in several layers unless ownership and update rules are explicit.
OFFICIAL SOURCES
Verify against the source
OpenAI AGENTS.md guidanceThis guide provides general information, not an OpenAI allowance promise or support decision. Your account and official pages govern actual usage, benefits and recovery times.