DEV Community

Cover image for AGENTS.md, project.json, and rules: the smallest APC boundary that works
Agent Project Context profile image Manuel Bruña
Manuel Bruña for Agent Project Context

Posted on

AGENTS.md, project.json, and rules: the smallest APC boundary that works

#ai #opensource #devtools #tutorial

AGENTS.md, project.json, and rules: the smallest APC boundary that works

APC stays useful only if its layers stay small and distinct. The mistake is to turn one file into a catch-all for every kind of project knowledge. That feels simpler on day one, then turns into drift, duplication, and tool-specific clutter.

The better split is narrow:

  • AGENTS.md for the repo-wide contract
  • .apc/project.json for stable project metadata
  • .apc/rules/ for path-scoped or task-scoped rules
  • .apc/agents/ and .apc/skills/ for reusable structured instructions

That is not just tidiness. It is what keeps APC portable across tools and repeatable across machines.

AGENTS.md is the broad contract

APC uses AGENTS.md as the root project surface. The docs describe it as the broad repository contract: the place for rules that every compatible agent should see when it enters the repo.

That means things like:

  • build or test expectations
  • security boundaries
  • repo-wide conventions
  • major workflow notes

If the rule should apply everywhere, AGENTS.md is the right home.

The important part is scope. AGENTS.md should not become a transcript dump or a place to stash every tiny exception. It is the top-level signal: what this repository is, how it behaves, and what an agent must respect before touching anything.

.apc/project.json is the stable identity

The workspace metadata file gives the project a consistent identity. In the current draft and reference implementation, that file is .apc/project.json.

The docs show a minimal shape like this:

{
  "name": "My Project",
  "version": "0.1.0",
  "apc": "0.1.0",
  "created": "2026-05-08T00:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

That file should answer a small set of questions:

  • what this project is called
  • which project version it is on
  • which APC target version it expects
  • when the APC metadata set was created

That is enough. It should stay boring.

Why keep it small? Because metadata is supposed to be stable. If project identity starts absorbing instructions, runtime state, or workflow noise, then the file stops being identity and starts being a junk drawer.

.apc/rules/ is where precision belongs

Some guidance is not repo-wide. Some guidance only matters for one path, one subsystem, or one kind of task. That is what .apc/rules/ is for.

The docs recommend path-scoped rule files such as:

.apc/rules/backend.mdc
.apc/rules/frontend.mdc
.apc/rules/security-review.md
Enter fullscreen mode Exit fullscreen mode

Use this layer when the rule is narrower than the whole repository:

  • backend request validation
  • frontend style constraints
  • security review notes
  • migration-specific reminders

That split matters because it keeps the root contract short. A frontend rule does not need to clutter the repo-wide instructions, and a backend rule should not be forced into a generic project overview.

Why this matters for APX too

APX is the runtime/tooling layer that consumes APC. Its README says the filesystem is the source of truth: project definitions and curated memory stay in the repo, while runtime state lives in ~/.apx/.

That works only if APC itself stays clean.

If you blur the surfaces, APX has to guess. If you keep them separate, APX can do the simpler thing:

  • read the root contract from AGENTS.md
  • read project identity from .apc/project.json
  • load path-scoped guidance from .apc/rules/
  • keep sessions, logs, and other runtime state out of the repo

The result is less drift. New tools can read the same project contract. Old tools do not need special cases. The repo stays portable.

A practical test

Before you add a file or move a rule, ask three questions:

  1. Does every agent need this? Put it in AGENTS.md.
  2. Is this stable identity data? Put it in .apc/project.json.
  3. Does this only matter for one path or task? Put it in .apc/rules/.

If none of those fit, it probably belongs in APX runtime state or in a normal project doc, not in APC.

That check is simple, but it prevents most of the confusion.

Bottom line

APC is not one big config blob. It is a small contract with clear layers.

AGENTS.md says how the repo should be treated. .apc/project.json says what the project is. .apc/rules/ says where exceptions live.

Keep those boundaries sharp, and APC stays portable instead of turning into another tool-specific folder.

Top comments (0)