APC: 하나의 컨텍스트, 하나의 이름

모든 AI 코딩 에이전트(AI coding agent)는 프로젝트 컨텍스트(project context)를 원합니다. Claude Code, Codex, Cursor, OpenCode, Windsurf 및 이와 유사한 에이전트 기반 개발 도구들은 모두 동일한 기본 정보들을 필요로 합니다: 저장소(repository)가 어떻게 구조화되어 있는지, 어떤 명령어가 중요한지, 어떤 규칙을 따라야 하는지, 어떤 에이전트가 존재하는지, 그리고 어떤 프로젝트 지식이 하나의 채팅을 넘어 유지되어야 하는지 등입니다.

문제는 도구들이 컨텍스트를 원하는 것이 아닙니다. 문제는 각 도구가 컨텍스트를 위한 자신들만의 브랜드화된 저장 공간을 만들려는 경향이 있다는 점입니다.

이 포스트의 배경이 되는 인포그래픽은 APC의 핵심 논지를 한 장의 그림으로 보여줍니다: 프로젝트의 의미는 .claude/, .cursor/, .codex/ 또는 기타 특정 벤더(vendor) 전용 폴더에 갇혀 있어서는 안 됩니다. 그것은 .apc/라는 하나의 중립적인 이름을 가져야 합니다.

구체적인 논지

APC는 또 다른 프롬프트 더미(prompt dump)가 아닙니다. APC는 내구성이 있고 프로젝트가 소유하는 에이전트 컨텍스트(agent context)를 위한 파일 시스템 규약(filesystem convention)입니다. APX는 런타임 상태(runtime state)를 저장소 외부에 유지하면서, 해당 컨텍스트를 일상 업무에서 유용하게 사용할 수 있도록 만드는 로컬 런타임/툴링(runtime/tooling) 레이어입니다.

이러한 분리는 중요합니다.

저장소는 다음과 같이 말할 수 있어야 합니다: "이것들은 이 프로젝트에 속하는 에이전트, 규칙, 기술, MCP 힌트, 그리고 큐레이션된 메모리들입니다." 호환 가능한 모든 에이전트 런타임은 팀에게 동일한 의미를 다섯 개의 서로 다른 폴더에 중복해서 작성하라고 요청하지 않고도 이를 읽을 수 있어야 합니다.

동시에, 저장소는 가공되지 않은 세션(raw sessions), 개인적인 트랜스크립트(private transcripts), 로컬 캐시(local caches) 또는 비밀 정보(secrets)를 포함해서는 안 됩니다. 그것들은 런타임에 속해야 합니다.

브랜드화된 사일로(silos)에서 공유 표준으로

공유된 규약이 없다면, 팀들은 결국 병렬적인 컨텍스트 트리(parallel context trees)를 갖게 됩니다:

.claude/
.cursor/
.codex/
...

각 폴더는 유용한 지침을 포함하고 있을 수 있습니다. 하지만 동일한 저장소 규칙이 여러 도구 전용 위치로 복사될 때, 진정한 단일 진실 공급원(source of truth)이 불분명해집니다.

팀이 Claude는 업데이트했지만 Cursor는 잊어버린 것일까요? Codex가 최신 규칙을 읽었을까요, 아니면 오래된 규칙을 읽었을까요? MCP 기대 사항이 한 번에 문서화되어 있나요, 아니면 로컬 설정 파일들에 흩어져 있나요?

APC는 이를 더 단순한 모델로 전환합니다:

AGENTS.md        # 루트 프로젝트 계약 (root project contract)
.apc/            # 구조화된 프로젝트 컨텍스트 (structured project context)

AGENTS.md는 호환 가능한 도구들에게 저장소 규칙 (repository rules), 스택 노트 (stack notes), 명령어 (commands), 그리고 가이드라인 (guidance)과 같은 광범위한 루트 계약 (root contract)을 제공합니다. .apc/는 프로젝트 메타데이터 (project metadata), 에이전트 정의 (agent definitions), 재사용 가능한 기술 (reusable skills), 규칙 (rules), 지속 가능한 계획 (durable plans), 그리고 공유해도 안전한 MCP 힌트 (MCP hints)와 같은 구조화된 프로젝트 컨텍스트 (structured project context)를 담고 있습니다.

프로젝트/런타임 경계 (The project/runtime boundary)

인포그래픽의 오른쪽은 가장 중요한 설계 제약 사항을 보여줍니다: APC는 지속 가능한 프로젝트의 의미 (durable project meaning)를 위한 것이지, 런타임 상태 (runtime state)를 위한 것이 아닙니다.

다음과 같은 종류의 정보는 커밋(commit)하세요:

.apc/project.json
.apc/agents/<slug>.md
.apc/skills/
...

다음은 APC 외부로 유지하세요:

가공되지 않은 세션 (raw sessions)
대화 기록 (conversation transcripts)
로컬 캐시 (local caches)
...

APX는 해당 경계를 따릅니다. 프로젝트는 AGENTS.md와 .apc/project.json에 의해 식별되는 반면, APX는 런타임 데이터 (runtime data)를 ~/.apx/projects/<id>/ 아래에 저장합니다. 이를 통해 프로젝트 정의는 저장소와 함께 이동할 수 있는 반면, 로컬 실행 이력 (local execution history)은 원래 속한 머신에 그대로 머물 수 있습니다.

중립적인 이름이 중요한 이유 (Why the neutral name matters)

이름은 동작을 결정합니다. 만약 프로젝트 컨텍스트가 .claude/ 아래에 있다면, 사람들은 이를 Claude 전용으로 취급할 것입니다. 만약 .cursor/ 아래에 있다면, 사람들은 이를 에디터 전용으로 취급할 것입니다. 만약 모든 런타임이 각자의 폴더를 소유한다면, 팀들은 동일한 프로젝트 계약 (project contract)을 여러 번 반복해서 유지 관리해야 합니다.

.apc/는 다른 것을 말합니다: 이 컨텍스트는 프로젝트에 속해 있다는 것입니다.

이는 미래에 호환 가능한 런타임이 APC를 직접 소비하여 자신의 내부 형식으로 투영하거나, 오늘 당장 APX를 참조 런타임 (reference runtime)으로 사용할 수 있음을 의미합니다. 목표는 모든 도구 폴더를 즉시 삭제하는 것이 아닙니다. 목표는 벤더 폴더 (vendor folders)가 공유된 프로젝트 의미의 유일한 진실의 원천 (source of truth)이 되는 것을 막는 것입니다.

실무 규칙 (Practical rule)

파일이 어디에 속해야 할지 결정할 때, 한 가지 질문을 던져보세요:

"만약 내가 한 AI 코딩 에이전트에서 다른 에이전트로 바꾼다 해도, 이것이 여전히 유용할까?"

만약 그렇다면, 그것은 아마도 AGENTS.md나 .apc/에 속해야 할 것입니다.

만약 아니라면, 그것은 아마도 ~/.apx/, ~/.codex/, .cursor 로컬 상태(local state), 또는 다른 도구가 소유한 위치와 같은 런타임 저장소(runtime storage)에 속할 것입니다.

APC는 프로젝트에 하나의 컨텍스트(context)와 하나의 이름을 부여합니다. APX는 일상적인 런타임(runtime) 작업을 로컬(local)에 유지하며, 비공개(private)로 관리하고, 운영(operational) 가능하게 유지합니다.