이식 가능한 컨텍스트가 이식 가능한 런타임을 의미하지는 않는다

이식 가능한 에이전트 프로젝트(portable agent project)라고 해서 모든 머신이 동일한 AI CLI를 실행할 수 있는 것처럼 가장해서는 안 됩니다.

그것이 바로 APC와 APX를 함께 사용할 때 얻을 수 있는 정확한 구분점입니다.

APC는 이식 가능한 컨텍스트 계층(portable context layer)입니다. 이는 AGENTS.md, .apc/agents, .apc/project.json, 스킬(skills), 명령(commands), 그리고 MCP 힌트(hints)와 같은 프로젝트 계약(project contract)을 저장소(repository)에 유지합니다. 저장소를 다른 곳으로 클론(Clone)하면 그 의미 또한 함께 이동할 수 있습니다.

APX는 일상적으로 사용하는 런타임 및 툴링 계층(runtime and tooling layer)입니다. 이는 로컬 데몬(local daemon), CLI, 웹 관리자(web admin)를 통해 해당 컨텍스트를 실행 가능하게 만들며, Claude Code, Codex, OpenCode, Aider, Cursor Agent, Gemini CLI, Qwen Code와 같은 외부 코딩 CLI로 연결하는 브릿지 역할을 합니다.

하지만 이러한 런타임들은 APC의 일부가 아닙니다.

이 점이 중요한 이유는 머신은 이식 불가능하더라도 저장소는 이식 가능할 수 있기 때문입니다.

어떤 노트북에는 codex와 claude가 설치되어 있을 수 있습니다. 다른 노트북에는 gemini와 ollama만 있을 수도 있습니다. CI 러너(CI runner)에는 이 중 아무것도 없을 수도 있습니다. 만약 시스템이 런타임 가용성(runtime availability)을 영구적인 프로젝트 컨텍스트(durable project context)인 것처럼 취급한다면, 거짓말을 하기 시작하는 것입니다. 저장소는 한 가지를 말하고 호스트는 다른 것을 할 수 있게 되면, 이제 모든 핸드오프(handoff)는 취약해집니다.

APX는 런타임 탐지(runtime detection)를 로컬 작업으로 만듦으로써 이를 방지합니다.

APX 런타임 문서는 명확하게 명시하고 있습니다: 런타임을 선택하기 전에 다음을 실행하십시오:

apx env detect

이 명령은 현재 머신에서 실제로 사용 가능한 런타임 CLI, 엔진 및 도구들을 보고합니다. 즉, APC는 프로젝트를 정의하지만, APX는 실행 전에 실제 상황(ground truth)을 확인합니다.

이는 런타임 가정을 저장소에 저장하는 것보다 더 나은 경계 설정입니다.

실제적인 흐름은 다음과 같습니다:

apx env detect
apx run reviewer --runtime codex "Review the diff in src/ for regressions"

codex가 설치되어 있다면 APX는 이를 실행할 수 있습니다. 만약 설치되어 있지 않다면, APC 파일들이 아무리 깔끔하게 이동했더라도 해당 호스트에는 런타임이 없는 것입니다.

이것이 바로 APX가 apx run과 apx exec를 분리하는 이유이기도 합니다.

apx run은 외부 런타임 (runtime) 바이너리에 위임합니다. APX는 시스템 프롬프트 (system prompt)를 구축하고, CLI를 생성하며, 출력을 캡처하고, 세션 레코드 (session record)를 저장합니다. 실제 모델 상호작용 (model interaction)과 셸 작업 (shell work)은 외부 도구가 수행합니다.

반면, apx exec는 APX 내부에 머물며 구성된 엔진 (engine)을 직접 호출합니다. 경로는 다르지만, 의존성 표면 (dependency surface)도 다르며, 동일한 APC 프로젝트 컨텍스트 (project context)를 공유합니다.

이러한 분리는 이식성 (portability)을 정직하게 유지해주기 때문에 유용합니다.

저장소를 수정하지 않고도 동일한 APC 프로젝트를 기기 간에 이동할 수 있습니다. 그러면 APX는 다음과 같은 로컬 질문에 답할 수 있습니다:

• 이곳에는 어떤 런타임 (runtimes)이 설치되어 있는가?
• 이곳에는 어떤 엔진 (engines)이 구성되어 있는가?
• 지금 이곳에서 사용 가능한 툴체인 (toolchain)은 무엇인가?

이것들은 런타임에 관한 질문이지, 프로젝트 계약 (project-contract)에 관한 질문이 아닙니다.

APX 소개 문서(introduction docs)는 더 넓은 설계를 더욱 명확하게 설명합니다. 파일 시스템 (filesystem)은 지속 가능한 프로젝트 의미의 진실의 원천 (source of truth)인 반면, 세션 (sessions), 대화 (conversations), 메시지 (messages), 캐시 (caches) 및 기타 런타임 상태 (runtime state)는 ~/.apx/ 아래에 존재하며 절대 저장소 (repo)에 속하지 않습니다. 런타임 가용성 (runtime availability)도 동일한 철학을 따릅니다. 설치된 바이너리 (binaries)와 로컬 엔진 설정은 기기의 사실 (machine facts)입니다.

따라서 실질적인 규칙은 간단합니다:

• APC는 클론 (clone), 리뷰 (review), 인수인계 (handoff) 과정에서도 살아남을 수 있는 방식으로 프로젝트를 기술해야 합니다.
• APX는 현재 기기가 실제로 실행할 수 있는 것이 무엇인지 찾아내야 합니다.
• 저장소는 로컬 런타임 바이너리가 이식 가능한 아티팩트 (portable artifacts)인 것처럼 가장해서는 안 됩니다.

이는 APC의 신뢰성을 떨어뜨리는 것이 아니라 오히려 높여줍니다. 프로젝트 계약은 작고 지속 가능한 상태로 유지됩니다. APX는 로컬 역량 (local capability), 런타임 호출 (runtime invocation), 세션 추적 (session tracking)과 같은 복잡한 부분을 처리합니다.

이식 가능한 컨텍스트 (Portable context)는 벤더 종속 (vendor lock-in)과 반복적인 설정을 피할 수 있기 때문에 가치가 있습니다. 하지만 이식성은 적절한 경계에서 멈출 때만 작동합니다.

프로젝트는 이동할 수 있습니다.

하지만 런타임은 여전히 확인되어야 합니다.

이것이 바로 apx env detect가 단순한 편의 기능이 아닌 이유입니다. 이것은 APC를 이식 가능하게 유지하고 APX를 정직하게 만드는 운영상의 가드레일 (operational guardrail)입니다.