APC Should Stay Clone-Safe, APX Should Stay Machine-Local

Decide where data belongs by asking one question.

Would this data survive a fresh clone on another machine?

If yes, put it in APC. If no, put it in APX.

This rule keeps your stack honest. APC stays portable. APX stays useful on the machine running the work. When these layers blur, projects become hard to share and hard to audit.

APC is the project contract. APX is the runtime.

APC data is clone-safe. Another developer or machine should read it immediately after a git checkout. It must be reviewable in git.

Good APC examples: • AGENTS.md for repo contracts • .apc/project.json for project identity • .apc/agents/ for agent roles • .apc/skills/ for reusable skills • .apc/mcps.json for shared hints

APX data is machine-local. This data stays on the machine or gets rebuilt there. It is execution state, not portable context.

Good APX examples: • Runtime config in ~/.apx/config.json • Local permission modes • Sessions and message logs • Local caches • Per-machine secrets

A repository should not force one person's local setup on everyone else.

When APC stays clone-safe, you can review the project shape without hidden files. You can diff instructions instead of chasing side effects.

When APX stays machine-local, the runtime adapts without changing the project. One machine uses a different permission mode, while another keeps a longer history. The project contract remains the same.

Before you add a new file, ask these three questions:

  1. Does every compatible tool need to read this? Put it in APC.
  2. Does it describe the project instead of the machine? Put it in APC.
  3. Does it depend on local credentials or recent execution? Put it in APX.

Examples: • A new agent role? APC. • A Telegram bot token? APX. • A note about project review rules? APC. • A log of the last conversation? APX.

APC carries what survives a clone. APX carries what matters only on the current machine. This simple rule keeps the system sane.

Source: https://dev.to/agentprojectcontext/apc-should-stay-clone-safe-apx-should-stay-machine-local-59n9

Optional learning community: https://t.me/GyaanSetuAi