A Path-Scoped Rule Is a Matching Contract, Not Just a Note

A rule that applies everywhere is easy to write and expensive to live with.

Projects accumulate instructions: validate API input, preserve migration compatibility, write release notes, keep documentation examples current. Those instructions are all useful. They are not all relevant while an agent is editing the same file.

APC gives this distinction a portable shape. Repository-wide expectations belong in AGENTS.md. A rule that only matters for a slice of the tree belongs in .apc/rules/ with frontmatter that says where it applies. The thesis is simple: a path-scoped rule is a matching contract. Its glob is part of its meaning.

The small rule

Imagine a repository with an API and a documentation site. The API needs request-boundary validation and careful compatibility handling. Documentation pages need accurate examples, but do not need a warning about route validation on every edit.

Put the API-specific instruction in a rule file such as .apc/rules/backend.mdc:

---
description: "Backend API rules"
globs:
  - "src/api/**/*.ts"
alwaysApply: false
---

- Validate request input at the route boundary.
- Keep public API compatibility during migrations.

The file holds two different facts. The Markdown body explains what to do. The frontmatter explains when the instruction matters. Removing either half changes the contract.

Why alwaysApply: false matters

alwaysApply: false expresses a useful restraint: do not make this a project-wide command. A task that changes src/api/orders.ts should receive backend rules. A task that updates docs/getting-started.mdx should not have to treat those rules as the primary context.

This is not an attempt to hide important constraints. It is how you make constraints easier to follow. A relevant, narrow rule is more likely to be noticed and less likely to be diluted among unrelated instructions.

The alternative is one enormous root file. That starts well: every rule is visible in one place. Later, a docs change arrives with database migration advice, UI conventions, deployment commands, and incident procedures attached. The agent must guess which parts matter. Humans do the same thing during review.

The matching surface is part of maintenance

A glob can become wrong without the rule text becoming wrong. Suppose an API moves from src/api/ to services/http/. The validation rule may still describe the right practice, but src/api/**/*.ts no longer names the files that need it. The rule has silently lost its reach.

Treat that rename as a contract change:

---
description: HTTP service rules
globs:
  - "services/http/**/*.ts"
alwaysApply: false
---

- Validate request input at the route boundary.
- Keep public API compatibility during migrations.

This gives code review a concrete question: did the matching surface move with the code?

Where APC and APX meet

APC is the portable context layer. It keeps the root contract, reusable skills, agent definitions, and scoped rules in the project rather than a tool-branded folder. The .mdc rule can travel with a checkout because its target is described relative to that project.

APX is the daily-use runtime and tooling layer. It can consume that project context while its sessions, messages, routines, and private runtime state remain local. The boundary matters here: a scoped rule is durable shared project knowledge; a runtime conversation about one particular edit is not.

A practical check before merging

When you add or edit a scoped APC rule, ask three questions:

1. Does the body state one behavior that is genuinely local to these files?
2. Does globs match every file that needs the behavior, without catching unrelated work?
3. Would a folder rename require updating this file?

If the answer to the last question is yes, the rule is doing useful work. Keep its matching surface visible in the review. Portable context stays trustworthy when its instructions have a clear home and a clear boundary.