DEV Community

Agent Project Context profile image Manuel Bruña
Manuel Bruña for Agent Project Context

Posted on

Migrating to APC: One Unified Context for Your AI Agents

#ai #opensource #devtools #tutorial

Migrating to APC: One Unified Context for Your AI Agents

Every AI coding tool wants project context. Claude Code has its files. Cursor has rules. Codex reads AGENTS.md. Windsurf and OpenCode have their own conventions too.

Each tool solves the same problem in its own folder: give the agent knowledge about this repository. The result is not a set of unique features. It is the same context — roles, rules, memory — copied and slowly desynchronized under different brand names.

This article is about fixing that with APC (Agent Project Context): one portable, tool-agnostic context layer that lives in your repo.

The real cost of multiple contexts

Fragmented context is not just untidy. It actively costs you:

  • Desynchronization. You update the rules in Claude, but forget Cursor. Instructions diverge fast, and agents start from different truths.
  • Onboarding friction. What an agent knows about the project depends on which editor the developer happens to use.
  • Noise in reviews. Pull requests fill with dirty diffs: duplicated configs and prompts tweaked to fit each IDE.
  • Privacy leaks. High risk of committing chat histories and tokens trapped inside tool-specific folders.

The solution: one context, one name

APC is not "another prompts folder." It is a neutral standard that consolidates the information that always belonged to the project, pulling it out of proprietary folders and into the repository boundary.

APC defines what an agent needs to know when it enters this project — regardless of whether it is executed by Claude Code, Cursor, or an automation in CI/CD.

That single move changes the model:

Legacy (multiple folders) With APC
Update "Did we update Claude and Cursor?" "Did we update .apc/?"
Portability Context follows the last tool used Context follows the repository
Onboarding Depends on the user's editor Starts consistently in AGENTS.md + .apc/
Code contract Noisy, duplicated diffs One clear, auditable project contract

The critical boundary: project vs. runtime

The most important idea in APC is a clean split between what belongs to the project and what belongs to the local machine.

Project (inside APC), travels with the repo:

  • agent roles (agents/)
  • reusable skills (skills/)
  • curated memory and rules

Local machine (outside APC), stays on your computer:

  • raw chat sessions
  • API tokens and IDE preferences
  • private memory dumps

APC is not a session store. Raw history stays in the IDE.

APC's canonical structure 

AGENTS.md          # root compatibility contract + global rules
.apc/
  project.json     # stable environment metadata
  agents/          # structured role definitions (e.g. architect.md)
  skills/          # reusable instructions and workflows
  rules/           # path-scoped rules (e.g. backend.mdc)
Enter fullscreen mode Exit fullscreen mode

AGENTS.md is the broad compatibility surface that almost every tool already reads. Inside .apc/, agent definitions carry portable metadata:

---
name: architect
model: inherit
skills: [system_design, review]
---

You are the software architect.
Enter fullscreen mode Exit fullscreen mode

The detail that matters: model: inherit. By not hard-coding a vendor model in the frontmatter, you let the runtime decide which LLM to use — which eliminates vendor lock-in at the project level.

Migration, phase 1: audit

You migrate through a funnel, not a rewrite.

  1. Inventory. Separate meaning from local state.
  2. Consolidate rules into AGENTS.md.
  3. Extract skills into .apc/skills/.
  4. Filter secrets. Keep APIs and raw sessions in your local folders (e.g. ~/.apx/).

Migration, phase 2: source vs. projection

You do not have to delete .claude/ or .cursor/ on day one. APC becomes the main source of truth. If an environment still needs tool-specific files, those should act as read-only projections of APC.

Golden rule: if two folders disagree, APC wins. Project context is edited in APC.

The privacy filter

Raw sessions and chat logs pass through a privacy filter that produces a curated summary, which feeds two safe outputs:

  • Durable plans (.apc/plans/): store migration or architecture plans only when they are safe to share.
  • Agent memory (memory.md): exclusively safe project facts. Never include raw agent dumps.

APC vs. MCP: complementary, not competing

These are two different layers:

  • External layer (MCP): What external capabilities can this AI call? — servers, databases, APIs.
  • Internal layer (APC): What should an agent know about this project? — folders, contracts, rules.

.apc/mcps.json is just a file of hints about which MCP servers the project needs. It is not an MCP server itself, and not a secrets store.

The bridge today: APX

While industry tools adopt .apc/ natively, APX is the reference runtime that works as a bridge today. Cursor, Claude Code, and Codex all run through APX, which reads .apc/ and keeps local state and raw sessions safe, outside the repository, in ~/.apx/.

Synthesis: the modern AI project architecture

Each layer in its right place:

  • Local machine (runtime): ~/.apx/, .cursor/ — session history and secrets belong to the runtime.
  • Repository (project): .apc/ — the project contract, rules, and roles belong to the repo.
  • External services (MCP): MCP servers and databases — connectivity to external tools belongs to MCP.

Unify your project context

A clean starting checklist:

  1. Create your AGENTS.md at the root.
  2. Initialize your .apc/ directory.
  3. Move your roles and rules, and stop duplicating effort.

Knowledge belongs to the project, not the tool.

Top comments (0)