Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 09. 21:13

APC는 프로젝트를 이식 가능하게 하고, APX는 이를 유지합니다.

요약

본 글은 AI 프로젝트의 컨텍스트와 런타임 상태를 분리하는 방법론을 제시합니다. 'APC'는 이식 가능한 프로젝트 계약(공유 규칙, 에이전트 정의)을 담당하며 저장소에 보관됩니다. 반면, 'APX'는 일상적인 사용 및 실행 환경(세션 관리, 툴링)을 전담하여 로컬 상태를 유지합니다.

핵심 포인트

  • APC: 프로젝트의 이식 가능한 계약 레이어 (저장소와 함께 이동).
  • APX: 실제 런타임 및 툴링 레이어 (로컬 사용 환경 관리).
  • 분리를 통해 재현성, 개인 정보 보호, 그리고 깔끔한 작업 흐름을 확보.
  • 각 컴포넌트가 맡은 역할을 명확히 분리하여 AI 프로젝트의 안정성을 높임.

APC가 프로젝트의 이식성을 보장하고, APX가 생명력을 불어넣습니다.

대부분의 AI 툴체인은 같은 이유로 실패합니다. 바로 지속적인 프로젝트 컨텍스트와 로컬 런타임 상태를 혼합하기 때문입니다. 그 결과는 취약합니다. 한 기기는 올바른 프롬프트 히스토리를 가지고 있고, 다른 기기는 다른 에이전트 설정을 가지고 있으며, 무엇이 저장소에 속하고 무엇이 노트북에 속하는지 아무도 알 수 없습니다.

APC와 APX는 이 문제를 깔끔하게 분리합니다.

APC는 이식 가능한 컨텍스트 레이어입니다. 이는 프로젝트가 공유 규칙과 에이전트 정의를 위한 중립적인 장소를 갖도록 합니다: AGENTS.md, .apc/project.json, .apc/agents/*.md, 그리고 .apc/mcps.json에 포함된 공유 MCP 힌트들입니다. APX는 일상 사용의 런타임 및 툴링 레이어입니다. 이는 해당 프로젝트 컨텍스트를 읽고, 에이전트를 실행하며, 세션을 관리하고, 로컬 활동을 ~/.apx/ 외부에 유지합니다.

이 분리가 작게 들릴 수 있지만, 그렇지 않습니다. 팀의 작업 방식을 바꿉니다.

APC에 속해야 할 것들

APC는 저장소와 함께 이동해야 하는 사실들을 위한 것입니다.

팀원이 저장소를 클론할 때, 그들은 즉시 동일한 프로젝트 계약을 볼 수 있어야 합니다. APX에서 이는 다음과 같은 것들을 의미합니다:

  • 루트 프로젝트 규칙을 위한 AGENTS.md
  • 안정적인 프로젝트 메타데이터 및 식별자를 위한 .apc/project.json
  • 재사용 가능한 에이전트 정의를 위한 .apc/agents/<name>.md
  • 비밀을 포함하지 않는 공유 MCP 항목을 위한 .apc/mcps.json

이 파일들은 한 기기가 아닌 프로젝트 자체를 설명하기 때문에 이식성이 있습니다.

APC는 의도적으로 지루합니다. 그것이 좋습니다. 이는 모든 호환 가능한 툴이 여러분의 개인 런타임 설정 전체를 필요로 하지 않고 읽을 수 있는 부분이기 때문입니다.

APX에 속해야 할 것들

APX는 APC가 매일 사용 가능하게 만드는 것입니다.

APX README에는 명시되어 있습니다: APX는 데몬(daemon)과 CLI(Command Line Interface)의 조합입니다. 데몬은 프로젝트, 에이전트, 세션 및 로그를 관리합니다. CLI는 apx init, apx run, apx exec, apx memory, 그리고 apx messages tail 같은 명령을 제공합니다.

런타임 상태는 로컬에 유지됩니다. 이는 세션, 대화, 메시지, 캐시 및 유사한 휘발성 데이터가 저장소(repo)가 아닌 ~/.apx/ 아래에 존재한다는 의미입니다. 이 선택은 중요합니다. 왜냐하면 런타임 상태는 개인적이고, 노이즈가 많으며, 종종 사적인 성격을 띠기 때문입니다.

APX는 또한 APC가 다루지 않으려는 부분들(plumbing)을 추가합니다:

  • Claude Code, Codex, OpenCode 및 Aider용 런타임 지원
  • Anthropic, OpenAI, Gemini, Ollama 또는 모의 엔진을 통한 직접적인 엔진 호출
  • Telegram 플러그인 지원
  • MCP 스코프 처리

따라서 APC는 프로젝트 계약(project contract)을 정의하고, APX가 이를 실행합니다.

분리가 중요한 이유

만약 런타임 로그를 저장소에 넣으면 병합 노이즈(merge noise)가 발생하고 로컬 기록이 유출됩니다. 만약 공유 프로젝트 규칙만을 개인 앱 설정 파일에 넣으면 이식성(portability)을 잃게 됩니다. APC와 APX는 이 두 가지 실수를 모두 피합니다.

이러한 분리는 세 가지 실질적인 장점을 제공합니다:

  1. 재현성 (Reproducibility). 동일한 저장소가 동일하고 영속적인 컨텍스트를 담고 있습니다.
  2. 개인 정보 보호 (Privacy). 로컬 세션 및 메시지 로그는 생성된 기기에 남아있습니다.
  3. 더 깔끔한 협업 (Cleaner collaboration). 검토자는 우발적인 런타임 잔여물(debris)이 아닌 프로젝트 규칙을 검사합니다.

MCP 모델도 같은 패턴을 보여줍니다. 공유 MCP 힌트(hints)는 커밋해도 안전할 때 .apc/mcps.json에 속해야 합니다. 비밀 정보를 포함하는 MCP는 ~/.apx/projects/<apxId>/mcps.json 아래 APX 런타임 스코프에 속해야 합니다. 같은 기능군이지만, 보안성과 이식성은 동일한 문제가 아니기 때문에 저장 방식이 다릅니다.

Telegram도 같은 논리를 사용합니다. APX는 채널을 프로젝트나 마스터 에이전트로 라우팅할 수 있지만, 그 채널 연결(wiring)은 런타임 동작입니다. 프로젝트 컨텍스트는 여전히 APC에 존재하며, APX가 이를 가장자리(edge)에서 적용할 뿐입니다.

간단한 워크플로우

깔끔한 APC/APX 워크플로우는 다음과 같습니다:

apx init
apx agent list
apx run cody --runtime claude-code "Review the open PRs and summarize them"
...

이 흐름에서, APC가 APX에게 안정적인 프로젝트 형태를 제공합니다. 그런 다음 APX가 작업을 수행합니다: 에이전트를 실행하고, 세션을 로컬에 저장하며, 나중에 검사할 수 있도록 메시지 기록을 노출합니다.

이것이 바로 실제 설계 아이디어입니다. APC는 이식 가능한 계약(portable contract)이고, APX는 실행기(executor)입니다.

이러한 역할들이 분리되어 유지될 때, 프로젝트는 읽기 쉬워지고, 런타임은 로컬에 머무르며, 시스템 전체를 이해하기 더 쉬워집니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0