A directory tree in documentation is easy to mistake for a setup checklist. You see agents, skills, rules, memory, and tool configuration, then create a placeholder for everything before an agent has done any useful work.
My recommendation for APC adoption is narrower: add a context file when you can explain which recurring decision it improves. A full-looking tree is not evidence of useful context.
Separate the contract from the example
Agent Project Context (APC) is the portable context layer: repository-owned instructions and definitions that compatible tools can share. APX is the daily-use runtime and tooling layer, providing local execution through its CLI, daemon, and other surfaces.
That distinction matters during onboarding. Designing project context and configuring an execution environment are separate jobs. Installing more runtime features does not make a vague project instruction more precise.
The APC draft identifies .apc/project.json as its metadata file. Its fields describe the project name, project version, APC target version, and creation time. That metadata has a specific purpose; it is not a place to collect every setting a developer might eventually need. See the workspace metadata specification.
Likewise, the folder structure specification explicitly describes path-scoped rules as optional. A canonical location tells you where content belongs when you need it. It does not make an empty file useful.
Start with an actual mistake
Consider a hypothetical API repository where agents repeatedly edit generated client files. Before designing several specialist roles, put the relevant instruction in the root contract:
# Project Context
- Generated clients live in `src/generated/`; change the schema instead.
- Regenerate clients after schema changes.
- Run the repository's documented API compatibility checks before merge.
These instructions identify a boundary, an alternative action, and a verification requirement. They are useful even before the team has a sophisticated agent setup. In a real repository, replace the generic check reference with the command your project actually documents.
Now suppose the same schema update requires a repeatable sequence: edit the schema, regenerate clients, inspect compatibility, and update examples. That is a reason to write a reusable project skill. Its value comes from preserving the sequence that people otherwise forget.
Later, if backend-only constraints start overwhelming the root contract, a path-scoped rule has a concrete job. You are moving an existing instruction to a more precise loading boundary, with the consuming tool's support checked explicitly.
This is a proposed adoption workflow, not a claim that every tool implements every APC directory or that this article defines a formal minimum layout.
Avoid speculative context
A placeholder such as “follow best practices” gives a reviewer almost nothing to verify. A fictional release process can be worse: an agent may follow it because the repository presents it as authoritative.
For each proposed file, ask:
- Which repeated question does this answer?
- Who can verify that the answer is current?
- What future change should trigger an update?
If those answers are missing, investigate the workflow before writing instructions for it. Empty structure can wait; incorrect guidance creates work immediately.
APX remains useful on the execution side as the project grows. Its local sessions and message history should stay in runtime-owned storage, rather than becoming filler for .apc/. The APX repository documents that storage boundary and its CLI workflow.
The practical measure is whether the next contributor or compatible agent makes fewer avoidable mistakes. Grow the context around observed needs, and review each new instruction as carefully as the code it will influence.
Project: Agent Project Context on GitHub.
Top comments (0)