APC로의 전환: AI 에이전트를 위한 하나의 통합된 컨텍스트

모든 AI 코딩 도구는 프로젝트 컨텍스트 (Project Context)를 원합니다. Claude Code는 자체 파일이 있고, Cursor는 규칙 (Rules)이 있습니다. Codex는 AGENTS.md를 읽습니다. Windsurf와 OpenCode 또한 그들만의 컨벤션 (Conventions)을 가지고 있습니다.

각 도구는 동일한 문제, 즉 에이전트에게 이 저장소 (Repository)에 대한 지식을 제공하는 문제를 각자의 폴더에서 해결합니다. 그 결과는 고유한 기능들의 집합이 아닙니다. 그것은 역할 (Roles), 규칙 (Rules), 메모리 (Memory)와 같은 동일한 컨텍스트가 서로 다른 브랜드 이름 아래 복제되어 서서히 동기화가 어긋나는 현상일 뿐입니다.

이 글은 **APC (Agent Project Context)**를 통해 이 문제를 해결하는 방법에 관한 것입니다. APC는 여러분의 저장소에 상주하는, 휴대 가능하고 도구에 구애받지 않는 (Tool-agnostic) 하나의 통합된 컨텍스트 레이어 (Context Layer)입니다.

다중 컨텍스트의 실제 비용

파편화된 컨텍스트는 단순히 지저분한 것에 그치지 않습니다. 이는 실제로 다음과 같은 비용을 발생시킵니다:

• 동기화 오류 (Desynchronization). Claude의 규칙을 업데이트했지만 Cursor는 잊어버릴 수 있습니다. 지침 (Instructions)은 빠르게 갈라지며, 에이전트들은 서로 다른 진실을 바탕으로 시작하게 됩니다.
• 온보딩 마찰 (Onboarding friction). 에이전트가 프로젝트에 대해 알고 있는 내용은 개발자가 우연히 어떤 에디터를 사용하는지에 따라 달라집니다.
• 리뷰 시 노이즈 (Noise in reviews). 풀 리퀘스트 (Pull Requests)가 지저분한 디프 (Diffs)로 가득 찹니다. 즉, 각 IDE에 맞게 조정된 중복된 설정 (Configs)과 프롬프트 (Prompts)들이 나타납니다.
• 개인정보 유출 (Privacy leaks). 도구별 특정 폴더 안에 갇힌 채팅 기록과 토큰 (Tokens)이 커밋될 위험이 높습니다.

해결책: 하나의 컨텍스트, 하나의 이름

APC는

프로젝트 (APC 내부), 리포지토리(repo)와 함께 이동:

• 에이전트 역할 (agents/)
• 재사용 가능한 기술 (skills/)
• 큐레이션된 메모리 및 규칙

로컬 머신 (APC 외부), 사용자의 컴퓨터에 유지:

• 가공되지 않은 채팅 세션 (raw chat sessions)
• API 토큰 및 IDE 설정 (IDE preferences)
• 개인 메모리 덤프 (private memory dumps)

APC는 세션 저장소 (session store)가 아닙니다. 가공되지 않은 기록은 IDE에 남습니다.

APC의 표준 구조 (canonical structure)

AGENTS.md          # 루트 호환성 계약 (root compatibility contract) + 글로벌 규칙
.apc/
  project.json     # 안정적인 환경 메타데이터 (stable environment metadata)
...

AGENTS.md는 거의 모든 도구가 이미 읽고 있는 광범위한 호환성 접점 (compatibility surface)입니다. .apc/ 내부에서 에이전트 정의는 이식 가능한 메타데이터 (portable metadata)를 포함합니다:

---
name: architect
model: inherit
...

중요한 세부 사항은 바로 model: inherit입니다. 프론트매터 (frontmatter)에 특정 벤더의 모델을 하드코딩하지 않음으로써, 런타임 (runtime)이 어떤 LLM을 사용할지 결정하도록 합니다. 이는 프로젝트 수준에서 벤더 종속성 (vendor lock-in)을 제거합니다.

마이그레이션, 1단계: 감사 (audit)

마이그레이션은 재작성 (rewrite)이 아니라 깔때기 (funnel)를 통과하는 과정입니다.

1. 인벤토리 (Inventory). _의미 (meaning)_와 _로컬 상태 (local state)_를 분리합니다.
2. 규칙 통합 (Consolidate rules). AGENTES.md로 규칙을 통합합니다.
3. 기술 추출 (Extract skills). .apc/skills/로 기술을 추출합니다.
4. 비밀 정보 필터링 (Filter secrets). API와 가공되지 않은 세션은 로컬 폴더 (예: ~/.apx/)에 유지합니다.

마이그레이션, 2단계: 소스 vs 투영 (source vs. projection)

첫날부터 .claude/나 .cursor/를 삭제할 필요는 없습니다. APC가 **단일 진실 공급원 (main source of truth)**이 됩니다. 만약 특정 환경이 여전히 도구별 파일이 필요하다면, 해당 파일들은 APC의 읽기 전용 투영 (read-only projections) 역할을 해야 합니다.

황금률: 만약 두 폴더의 내용이 일치하지 않는다면, APC가 우선합니다. 프로젝트 컨텍스트는 APC에서 편집됩니다.

개인정보 보호 필터 (The privacy filter)

가공되지 않은 세션과 채팅 로그는 **개인정보 보호 필터 (privacy filter)**를 거쳐 _큐레이션된 요약 (curated summary)_을 생성하며, 이는 두 가지 안전한 출력물로 전달됩니다:

• 지속 가능한 계획 (Durable plans) (.apc/plans/): 공유해도 안전한 경우에만 마이그레이션 또는 아키텍처 계획을 저장합니다.
• 에이전트 메모리 (Agent memory) (memory.md): 오직 안전한 프로젝트 사실만을 포함합니다. 절대로 가공되지 않은 에이전트 덤프를 포함해서는 안 됩니다.

APC vs MCP: 경쟁 관계가 아닌 상호 보완 관계

이것들은 서로 다른 두 개의 계층입니다:

• 외부 계층 (MCP): 이 AI가 호출할 수 있는 외부 기능은 무엇인가? — 서버, 데이터베이스, API.
• 내부 계층 (APC): 에이전트가 이 프로젝트에 대해 무엇을 알아야 하는가? — 폴더, 계약 (contracts), 규칙.

.apc/mcps.json은 프로젝트에 어떤 MCP 서버가 필요한지에 대한 힌트 (hints) 파일일 뿐입니다. 이것은 MCP 서버 자체가 아니며, 비밀 정보 저장소 (secrets store)도 아닙니다.

현재의 가교: APX

업계 도구들이 .apc/를 네이티브로 채택하고 있는 가운데, APX는 현재 가교 역할을 하는 참조 런타임 (reference runtime)입니다. Cursor, Claude Code, Codex는 모두 APX를 통해 실행되며, APX는 .apc/를 읽고 로컬 상태 (local state)와 가공되지 않은 세션 (raw sessions)을 저장소 외부인 ~/.apx/에 안전하게 보관합니다.

종합: 현대적인 AI 프로젝트 아키텍처 (architecture)

각 계층이 제 위치에 있습니다:

• 로컬 머신 (런타임): ~/.apx/, .cursor/ — 세션 기록 (session history)과 비밀 정보 (secrets)는 런타임에 속합니다.
• 저장소 (프로젝트): .apc/ — 프로젝트 계약 (project contract), 규칙, 그리고 역할 (roles)은 저장소 (repo)에 속합니다.
• 외부 서비스 (MCP): MCP 서버 및 데이터베이스 — 외부 도구와의 연결성은 MCP에 속합니다.

프로젝트 컨텍스트를 통합하세요

깔끔한 시작을 위한 체크리스트:

1. 루트 디렉토리에 AGENTS.md를 생성합니다.
2. .apc/ 디렉토리를 초기화합니다.
3. 역할과 규칙을 이동시키고, 중복된 노력을 멈추세요.

지식은 도구가 아니라 프로젝트에 속합니다.

• Web: https://agentprojectcontext.com/
• Repo: https://github.com/agentprojectcontext/agentprojectcontext