Load Nested AGENTS.md Rules at the Folder Boundary

A project needs shared instructions, but it does not need every instruction in every turn. The useful rule is: put folder-specific guidance in that folder's AGENTS.md, then load it when work reaches that folder.

That sounds like a small organization detail. It is actually a context-quality boundary. If a repository-wide agent prompt carries every rule for the mobile app, deployment scripts, data migration, and marketing site, most of those rules are irrelevant most of the time. The important instruction becomes harder to notice precisely when it matters.

Keep root guidance truly shared

An APC project keeps portable context in the repository. Root AGENTS.md is the place for rules that apply across the project: conventions, commands, safety constraints, and an index of the project-level agent setup. It should answer questions that matter no matter which directory a task touches.

For example, a root file might say:

Run the repository test suite before changing shared packages.
Do not commit credentials or generated runtime state.
Use the documented release workflow.

Those are project facts. They are useful to a compatible tool from a fresh checkout, and they stay useful whether the next edit is in api/, web/, or infra/.

Put local rules next to local work

Now consider a migration directory that needs a special ordering rule, or a service folder that has a separate test command and an external API contract. Those instructions should not become permanent background for an unrelated documentation edit. Give the directory its own AGENTS.md instead:

repo/
├── AGENTS.md
├── api/
│   ├── AGENTS.md
│   └── migrations/
└── web/
    └── AGENTS.md

The api/AGENTS.md can explain migration safety and API checks. The web/AGENTS.md can describe component conventions and browser tests. Each file has a narrow owner: the folder beneath it.

This is not an excuse to hide global policy in a deep directory. A rule belongs there only when its scope really starts there. A ban on secrets belongs at the root; a warning about a destructive database fixture can belong with the fixture. Scope should follow the work boundary, not the writer's desire to keep a file short.

Attach instructions when the tool crosses the boundary

APX makes this structure operational. For a project turn, it supplies the project AGENTS.md and identifies subfolders with their own instruction files. When a tool first touches one of those folders in that turn, APX attaches the folder's rules to the tool result. The agent receives the local rule at the moment it has evidence that the task reached that part of the tree.

That timing matters. Imagine a request to update a landing-page headline. The agent should not begin with database migration instructions. If the same task later changes an API schema, the API guidance appears when the work enters api/. The context grows with the actual path of work instead of arriving as an unfiltered manual.

Portable contract, local execution

APC provides the portable contract: committed AGENTS.md files travel with the repository and can be reviewed like other project decisions. APX is the daily-use runtime: it selects relevant project context during a turn while keeping conversations, tool history, and private runtime state local.

Together, they support a simple habit: write root rules for the whole project, write nested rules for real local boundaries, and let the runtime reveal local guidance when the task crosses that boundary. Less prompt noise is not merely tidier. It gives the right instruction a better chance to govern the right action.