APC는 클론 안전(Clone-Safe)을 유지해야 하고, APX는 머신 로컬(Machine-Local)을 유지해야 합니다

APC/APX에서 어떤 것이 어디에 속해야 하는지 결정하는 가장 깔끔한 방법은 간단합니다: **"이 항목이 정확히 그대로 다른 머신에서의 새로운 클론(fresh clone) 후에도 살아남기를 원하는가?"**입니다.

만약 그렇다면, 그것은 APC에 속합니다. 아니라면, APX에 속합니다.

이 질문 하나가 스택(stack)의 정직함을 유지합니다. APC는 휴대성(portable)을 유지합니다. APX는 실제로 작업을 수행 중인 머신에서 유용함을 유지합니다. 이 두 계층이 모호해지면, 프로젝트를 공유하기 어려워지고, 감사(audit)하기 어려워지며, 도구나 노트북을 변경한 후 복구하기가 어려워집니다.

한 문장으로 요약하는 분리

APC는 프로젝트 계약(project contract)입니다. APX는 이를 실행하는 런타임(runtime)입니다.

APC 리포지토리(repo)의 README는 목표가 프로젝트 수준의 에이전트 컨텍스트(agent context)를 위한 단일 중립 디렉토리라고 말합니다. APX README는 파일 시스템이 프로젝트 정의와 큐레이션된 메모리(curated memory)의 진실의 원천(source of truth)인 반면, 런타임 상태(runtime state)는 ~/.apx/에 존재하며 절대 커밋되지 않는다고 말합니다. 그것이 경계입니다.

클론 안전(Clone-safe)은 APC에 속해야 합니다

클론 안전(Clone-safe) 데이터는 다른 개발자, 다른 에이전트 런타임, 또는 다른 머신이 체크아웃(checkout) 직후에 즉시 읽을 수 있어야 하는 것입니다. 이는 git에서 검토 가능해야 하며, 이동할 수 있을 만큼 충분히 안정적이어야 합니다.

좋은 APC 사례:

• 리포지토리 전반의 계약을 위한 AGENTS.md
• 안정적인 프로젝트 식별을 위한 .apc/project.json
• 에이전트 역할 및 지침을 위한 .apc/agents/<slug>.md
• 재사용 가능한 프로젝트 기술(skills)을 위한 .apc/skills/
• 비밀 정보(secrets) 없는 공유 MCP 힌트를 위한 .apc/mcps.json

이것이 프로젝트의 의미입니다. 이것은 노트북이 아니라 리포지토리를 따라가야 하는 것입니다.

빠른 확인 방법: git clone 이후에도 파일이 여전히 의미가 있다면, 그것은 아마도 APC에 속할 것입니다.

머신 로컬(Machine-local)은 APX에 속해야 합니다

머신 로컬(Machine-local) 데이터는 머신과 함께 사라지거나 그곳에서 재구축되어야 하는 것입니다. 유용할 수는 있지만, 공유되는 프로젝트의 진실(shared project truth)이 되어서는 안 됩니다.

좋은 APX 사례:

• ~/.apx/config.json에 있는 런타임 설정 (runtime configuration)
• 권한 모드 (permission mode) 및 기타 로컬 정책 (local policy)
• ~/.apx/ 아래의 세션 (sessions), 대화 (conversations), 메시지 로그 (message logs)
• 캐시 (caches) 및 기타 런타임 상태 (runtime state)
• 머신별 MCP 비밀 정보 (per-machine MCP secrets)

해당 데이터는 실제 데이터이지만, 휴대 가능한 컨텍스트 (portable context)가 아닙니다. 그것은 실행 상태 (execution state)입니다.

이것이 중요한 이유는 저장소 (repo)가 한 사람의 로컬 설정 (local setup)을 다른 모든 사람의 클론 (clone) 속으로 몰래 들여보내서는 안 되기 때문입니다. 프로젝트는 무엇이 필요한지 말할 수 있고, 머신은 그것을 오늘 어떻게 실행할지 결정할 수 있습니다.

경계 설정이 주는 이점

APC가 클론 안전 (clone-safe)을 유지하면, 저장소 (repo)를 검토하기가 더 쉬워집니다. 숨겨진 저장소를 열지 않고도 프로젝트의 형태를 볼 수 있습니다. 부수 효과 (side effects)를 쫓는 대신 지침 (instructions)을 비교 (diff)할 수 있습니다. 저장소를 다른 곳에 클론 (clone)하더라도 프로젝트가 무엇을 원하는지 여전히 이해할 수 있습니다.

APX가 머신 로컬 (machine-local)을 유지하면, 런타임 (runtime)이 저장소 (repo)를 오염시키지 않고도 적응할 수 있습니다. 어떤 머신은 다른 권한 모드 (permission mode)를 사용할 수 있고, 다른 머신은 다른 모델 기본값 (model default)을 사용할 수 있으며, 세 번째 머신은 더 긴 로컬 메시지 기록 (local message history)을 유지할 수 있습니다. 프로젝트 계약 (project contract)은 변하지 않습니다.

이것이 진정한 승리입니다. 프로젝트는 안정적으로 유지되면서, 런타임 (runtime)은 유연하게 유지됩니다.

실질적인 결정 테스트

새로운 파일이나 설정을 추가하기 전에, 다음 세 가지 질문을 던져보세요:

1. 모든 호환 가능한 도구가 이것을 읽어야 하는가? 그렇다면 APC에 넣으세요.
2. 이것이 머신이 아닌 프로젝트를 설명하는가? 그렇다면 APC에 넣으세요.
3. 이것이 로컬 신뢰 (local trust), 로컬 자격 증명 (local credentials), 또는 최근 실행 (recent execution)에 의존하는가? 그렇다면 APX에 넣으세요.

예시:

• 코드 리뷰를 위한 새로운 에이전트 역할 (agent role)? APC.
• 텔레그램 봇 토큰 (Telegram bot token)? APX.
• 프로젝트가 리뷰를 처리하는 방식에 대한 영구적인 노트 (durable note)? APC.
• 마지막 리뷰 대화의 로그 (log)? APX.

여전히 확신이 서지 않는다면, 클론 테스트 (clone test)를 사용하세요. 만약 답변이 새로운 체크아웃 (fresh checkout) 후에도 유지되어야 한다면, 휴대 가능하게 (portable) 유지하세요. 그렇지 않다면, 로컬 (local)로 유지하세요.

APX가 가능하게 하는 것

APX는 단순히 로컬 쓰레기들을 위한 저장소가 아닙니다. APX는 클론 안전 (clone-safe) 컨텍스트를 일상적인 사용으로 전환하는 계층 (layer)입니다. APX는 프로젝트를 등록하고, 에이전트 (agents)를 실행하며, 메모리 (memory)를 읽고, 메시지를 추적 (tails messages)하며, 런타임 (runtimes) 및 MCP와 브릿지 (bridge) 역할을 합니다.

작은 워크플로우만으로도 그 분리를 체감하기에 충분합니다:

apx init
apx memory reviewer
apx messages tail

apx init은 런타임 (runtime)이 프로젝트를 읽을 수 있게 만듭니다. apx memory는 에이전트 (agent)를 위해 큐레이션된 영구적인 사실 (durable facts)을 보여줍니다. apx messages tail은 런타임이 현재 수행 중인 작업의 실시간 흔적 (live trail)을 보여줍니다. 하나의 리포지토리 (repo), 하나의 런타임 (runtime), 두 개의 서로 다른 작업입니다.

핵심 요약 (Bottom line)

APC는 클론 (clone) 후에도 살아남는 것을 담아야 합니다. APX는 현재 머신 (machine)에서만 유효한 것을 담아야 합니다.

이 규칙은 단순하지만, 시스템 전체의 건전성을 유지해 줍니다. APC는 이식성 (portable)과 검토 가능성 (reviewable)을 유지합니다. APX는 로컬 (local) 상태와 실용성을 유지합니다. 그리고 그 사이의 경계는 다른 런타임 (runtime)이 추측 없이도 동일한 프로젝트를 읽을 수 있을 만큼 명확하게 유지됩니다.