APC proposes shared repository folders for durable AI coding agent context

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

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" } 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 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: Does every agent need this? Put it in AGENTS.md. Is this stable identity data? Put it in .apc/project.json. 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.

2 hours ago

APC: One Context, One Name

Every AI coding agent wants project context. Claude Code, Codex, Cursor, OpenCode, Windsurf, and similar agentic development tools all need the same basic facts: how the repository is structured, which commands matter, what rules should be followed, which agents exist, and which project knowledge should survive beyond one chat. The problem is not that tools want context. The problem is that each tool tends to invent its own branded home for it. The infographic behind this post shows the core APC thesis in one picture: project meaning should not be trapped in .claude/, .cursor/, .codex/, or any other vendor-specific folder. It should have one neutral name: .apc/. The concrete thesis APC is not another prompt dump. APC is a filesystem convention for durable, project-owned agent context. APX is the local runtime/tooling layer that makes that context useful in daily work while keeping runtime state outside the repository. That split matters. A repository should be able to say: "these are the agents, rules, skills, MCP hints, and curated memories that belong to this project." Any compatible agent runtime should be able to read that without asking the team to duplicate the same meaning into five different folders. At the same time, a repository should not contain raw sessions, private transcripts, local caches, or secrets. Those belong to the runtime. From branded silos to a shared standard Without a shared convention, teams end up with parallel context trees: .claude/ .cursor/ .codex/ .opencode/ .windsurf/ Each folder may contain useful instructions. But when the same repository rule is copied into multiple tool-specific locations, the real source of truth becomes unclear. Did the team update Claude but forget Cursor? Did Codex read the newer rule or the stale one? Are MCP expectations documented once, or scattered through local config files? APC turns that into a simpler model: AGENTS.md # root project contract .apc/ # structured project context AGENTS.md gives compatible tools a broad root contract: repository rules, stack notes, commands, and guidance. .apc/ carries structured project context: project metadata, agent definitions, reusable skills, rules, durable plans, and MCP hints that are safe to share. The project/runtime boundary The right side of the infographic shows the most important design constraint: APC is for durable project meaning, not runtime state. Commit this kind of information: .apc/project.json .apc/agents/<slug>.md .apc/skills/ .apc/rules/ .apc/plans/ .apc/mcps.json # no secrets Keep this outside APC: raw sessions conversation transcripts local caches private memory API keys and credentials APX follows that boundary. A project is identified by AGENTS.md plus .apc/project.json, while APX stores runtime data under ~/.apx/projects/<id>/. That lets the project definition travel with the repository, while local execution history stays on the machine where it belongs. Why the neutral name matters Names shape behavior. If project context lives under .claude/, people treat it as Claude-specific. If it lives under .cursor/, people treat it as editor-specific. If every runtime owns its own folder, teams keep maintaining the same project contract many times. .apc/ says something different: this context belongs to the project. That means a future-compatible runtime can consume APC directly, project it into its own internal format, or use APX as a reference runtime today. The goal is not to delete every tool folder immediately. The goal is to stop making vendor folders the only source of truth for shared project meaning. Practical rule When deciding where a file belongs, ask one question: Would this still be useful if I switched from one AI coding agent to another? If yes, it probably belongs in AGENTS.md or .apc/. If no, it probably belongs in runtime storage such as ~/.apx/, ~/.codex/, .cursor local state, or another tool-owned location. APC gives the project one context and one name. APX keeps the daily runtime work local, private, and operational.

2 hours ago