APC는 프로젝트 계약을 정의합니다. MCP는 도구 프로토콜을 정의합니다.

에이전트 도구(agent tooling)를 둘러싼 많은 혼란은 서로 다른 두 계층을 혼동하는 데서 발생합니다.

APC는 프로젝트에 관한 것이고, MCP는 외부 도구에 관한 것입니다. APX는 그 중간에 위치하여 두 가지 모두를 일상적인 머신에서 유용하게 만듭니다.

이러한 분리는 작업이 시작될 때 런타임(runtime)이 실제 도구에 도달할 수 있도록 허용하면서도, 저장소(repository)를 작고, 검토 가능하며, 이식 가능하게 유지하기 때문에 중요합니다.

요약 버전

APC를 이식 가능한 컨텍스트 계층(context layer)이라고 생각하세요.

APC는 호환 가능한 도구들에게 저장소가 무엇을 의미하는지 알려줍니다:

• 어떤 에이전트(agents)가 존재하는지
• 어떤 규칙(rules)이 중요한지
• 어떤 기술(skills)이 프로젝트에 속하는지
• 프로젝트가 어떤 MCP 서버를 기대하는지
• 어떤 큐레이션된 사실(curated facts)이 단일 세션을 넘어 유지되어야 하는지

MCP를 도구 프로토콜(tool protocol)이라고 생각하세요.

MCP는 AI 앱이 외부 기능과 통신하는 방법을 알려줍니다:

• 도구(tools)
• 리소스(resources)
• 프롬프트(prompts)
• 전송(transports)
• 스키마(schemas)
• 요청 및 응답 흐름(request and response flow)

APC는 MCP를 대체하지 않습니다. MCP는 APC를 대체하지 않습니다. 이들은 서로 다른 문제를 해결합니다.

이러한 구분이 중요한 이유

모든 것을 하나의 바구니에 담으면, 그 바구니는 금방 더러워집니다.

저장소는 다음과 같은 것들을 저장해서는 안 됩니다:

• API 키(API keys)
• 베어러 토큰(bearer tokens)
• 세션 로그(session logs)
• 일시적인 런타임 상태(transient runtime state)
• 머신 특정 절대 경로(machine-specific absolute paths)

이러한 것들은 공유된 프로젝트 계약이 아니라, 런타임이나 사용자 머신에 속해야 합니다.

이것이 .apc/mcps.json이 비밀 저장소(secret store)도 아니고 그 자체로 서버도 아닌, 힌트 파일(hint file)인 이유입니다. 이 파일은 여기서 파일 시스템 MCP가 중요하다는 것을 말할 수 있습니다. 하지만 파일 시스템 MCP 자체가 되려고 해서는 안 됩니다.

예시:

project-root/
└── .apc/
    └── mcps.json

해당 파일은 기대 사항을 선언할 수 있습니다. 호환 가능한 런타임은 여전히 실제 MCP 서버를 해결(resolve), 시작, 그리고 연결해야 합니다.

APC에 포함되어야 할 내용

APC는 좁고 안정적인 상태를 유지할 때 가장 잘 작동합니다.

좋은 APC 콘텐츠:

• AGENTS.md 내의 루트 프로젝트 계약 (root project contract)
• .apc/agents/<slug>.md 내의 구조화된 에이전트 (structured agents)
• .apc/skills/ 내의 재사용 가능한 기술 (reusable skills)
• .apc/project.json 내의 프로젝트 메타데이터 (project metadata)
• 공유가 안전할 때의 큐레이션된 메모리 (curated memory)
• .apc/mcps.json 내의 MCP 기대 사항 (MCP expectations)

좋은 APC 콘텐츠란 새로 클론(fresh clone)을 받았을 때, 노트북을 교체했을 때, 또는 런타임(runtime)을 전환했을 때 바로 사용하고 싶은 종류의 것입니다.

APX가 해야 할 일

APX는 로컬 런타임 (local runtime) 및 툴링 레이어 (tooling layer)입니다.

APX는 APC를 읽은 다음, APC가 의도적으로 소유하지 않는 머신 로컬 작업 (machine-local work)을 수행합니다:

• 데몬 (daemon) 시작
• 에이전트 (agents) 실행
• 세션 (sessions) 및 메시지 (messages) 관리
• 런타임 상태 (runtime state)를 ~/.apx/ 아래에 로컬로 유지
• MCP 소스 해결 및 병합 (resolve and merge)
• 런타임 및 엔진 (engines) 간의 디스패치 (dispatch)

다시 말해, APC는 프로젝트가 무엇을 기대하는지 말합니다. APX는 이 머신이 그것을 어떻게 충족할지 결정합니다.

이러한 분리는 흔한 실패 모드(failure mode), 즉 프로젝트 파일이 캐시(cache), 트랜스크립트 덤프(transcript dump), 그리고 로컬 설정 데이터베이스(local settings database)로 한꺼번에 서서히 변질되는 현상을 방지합니다.

구체적인 워크플로우 (workflow)

파일 시스템 MCP와 리뷰어 에이전트 (reviewer agent)가 필요한 저장소(repo)를 상상해 보세요.

APC는 프로젝트의 형태를 기술할 수 있습니다:

{
  "mcpServers": {
    "filesystem": {
...

또한 .apc/agents/reviewer.md에 에이전트 계약 (agent contract)을 정의할 수 있습니다.

그 다음 APX가 런타임 작업 (runtime job)을 수행합니다:

apx init
apx agent list
apx mcp check
...

저장소는 계약을 유지하고, 데몬은 실행을 유지합니다.

더 깊은 이유

이러한 분리는 단순히 깔끔한 아키텍처 (architecture) 때문만이 아닙니다.

이는 드리프트 (drift, 괴리)를 낮춥니다.

프로젝트의 의미가 APC에 존재할 때, 서로 다른 도구들이 동일한 신뢰할 수 있는 단일 원천 (source of truth)을 읽을 수 있습니다. 런타임 메커니즘이 APX에 존재할 때, 저장소를 다시 작성하지 않고도 머신을 변경할 수 있습니다. MCP가 MCP로 유지될 때, 외부 도구 통합은 프로젝트 형식의 문제가 아닌 프로토콜 (protocol)의 문제로 남습니다.

이를 통해 세 가지 명확한 소유권 라인 (ownership lines)을 가질 수 있습니다:

• APC: 프로젝트 의미 (project meaning)
• MCP: 외부 기능 프로토콜 (external capability protocol)
• APX: 로컬 실행 레이어 (local execution layer)

그러한 경계가 명확해지면, 많은 도구(tooling) 결정이 더 쉬워집니다. "이 무작위 상태(random state)를 어디에 두어야 할까?"라고 묻는 대신, 더 나은 질문을 던지기 시작하게 됩니다: "이것은 프로젝트 의미(project meaning)인가, 외부 기능(external capability)인가, 아니면 로컬 실행(local execution)인가?"

그 질문이 보통 올바른 답을 제공합니다.