글로벌 컨텍스트는 APC 외부에 있어야 합니다

APC는 휴대 가능한 컨텍스트 레이어 (context layer)입니다. APX는 APC를 매일 유용하게 사용할 수 있도록 만드는 로컬 런타임 (local runtime) 및 툴링 (tooling) 레이어입니다. 이 분리를 건강하게 유지하는 가장 쉬운 방법은 명확한 선을 긋는 것입니다. 만약 어떤 것이 새로운 클론 (fresh clone) 후에도 살아남아야 한다면, 그것은 APC에 속해야 합니다. 만약 그것이 한 명의 사용자, 하나의 워크스테이션 (workstation), 또는 하나의 실행 중인 프로세스 (running process)에 의존한다면, APC 외부에 머물러야 합니다.

프로젝트가 커지기 시작하기 전까지는 이 말이 당연하게 들립니다. 하지만 프로젝트가 커지면 유혹이 나타납니다. 설정 하나 더, 토큰 (token) 하나 더, 로컬 경로 (local path) 하나 더, 개인적인 선호도 하나 더 추가하고 싶은 유혹 말입니다. 엄격하게 관리하지 않으면, 프로젝트 컨텍스트 (project context)는 서서히 기계가 알고 있는 모든 것을 쏟아붓는 쓰레기통으로 변합니다. 그 시점에서 리포지토리 (repo)는 휴대성을 잃고 취약해지기 시작합니다.

APC에 속하는 것

APC는 프로젝트가 소유한 의미를 위한 것입니다. APC 문서와 README에서 이는 리포지토리가 함께 가지고 다닐 수 있는 공유된 계약 (shared contract)을 의미합니다.

좋은 APC 콘텐츠는 다음과 같습니다:

• 프로젝트 정체성 (project identity)
• 에이전트 역할 (agent roles)
• 재사용 가능한 기술 (reusable skills)
• 큐레이션된 프로젝트 메모리 (curated project memory)
• 프로젝트 레벨의 MCP 힌트 (project-level MCP hints)
• AGENTS.md에 포함된 리포지토리 전역 지침 (repo-wide instructions)

이것들은 팀 동료, 새로운 런타임 (runtime), 또는 두 번째 머신이 체크아웃 (checkout) 직후에 읽을 수 있어야 하는 사실들입니다. 이것들은 다른 도구가 숨겨진 로컬 상태 (local state) 없이도 프로젝트를 이해할 수 있도록 도와줍니다.

APC에 속하지 않는 것

글로벌 컨텍스트 (Global context)는 다릅니다. 그것은 사용자 계정, 워크스테이션, 또는 런타임 설치 (runtime installation)에 속합니다.

예시:

• API 키 (API keys)
• 에디터 설정 (editor preferences)
• 로컬 별칭 (local aliases)
• 머신 특정 툴 경로 (machine-specific tool paths)
• 프라이빗 런타임 메모리 (private runtime memory)
• 캐시 (caches)
• 세션 트랜스크립트 (session transcripts)
• 메시지 로그 (message logs)
• 일회성 디버그 노트 (one-off debug notes)

APX는 의도적으로 이러한 종류의 상태를 로컬에 유지합니다. APX의 README는 명시적입니다: 런타임 상태 (runtime state)는 리포지토리가 아니라 ~/.apx/ 아래에 존재합니다. 이 분리는 단순히 외관상의 문제가 아닙니다. 이것이 프로젝트를 공유 가능하게 유지해 주는 핵심입니다.

분리가 중요한 이유

글로벌 컨텍스트와 프로젝트 컨텍스트가 섞이면, 세 가지 문제가 빠르게 나타납니다.

첫째, 이식성 (portability)이 깨집니다. 한 개인의 로컬 설정에 암묵적으로 의존하는 저장소는 클론 (clone)하기 어렵고 신뢰하기도 더 어렵습니다.

둘째, 리뷰가 지저분해집니다. 풀 리퀘스트 (pull request)는 누군가의 워크스테이션 (workstation) 잔재가 아니라 프로젝트의 결정 사항을 보여주어야 합니다.

셋째, 비밀 정보 (secrets)가 더 쉽게 유출됩니다. 저장소가 머신 로컬 (machine-local) 상세 정보를 저장하기 시작하는 순간, 사람들은 어떤 파일이 커밋 (commit)해도 안전한지, 어떤 것이 그렇지 않은지를 잊어버리게 됩니다.

APC는 이식 가능한 레이어 (layer)를 작고 읽기 쉽게 유지함으로써 이 세 가지 문제를 모두 방지합니다.

간단한 테스트

파일이나 설정을 추가하기 전에 한 가지 질문을 던져보세요:

이 저장소를 클론하는 다른 기여자 (contributor)에게 이것이 즉시 필요할 것인가?

만약 그렇다면, APC에 넣으세요.
만약 아니라면, APC 외부에 두세요.

몇 가지 구체적인 예시가 도움이 될 것입니다:

• 모든 클론이 알고 있어야 하는 리뷰어 에이전트 (reviewer agent)? APC.
• 개인 API 키? APC 아님.
• 권한을 어떻게 처리할지에 대한 프로젝트 결정 사항? APC.
• 로컬 브라우저 프로필 경로? APC 아님.
• 이 저장소에 어떤 서버가 중요한지 도구들에게 알려주는 공유 MCP 힌트 (hint)? APC.
• 마지막 실행의 캐시 (cache)? APC 아님.

이 규칙은 지루하지만, 효과적입니다.

APX가 경계를 다루는 방식

APX는 APC를 읽어 실행 가능하게 만드는 런타임 (runtime)입니다. 프로젝트를 등록하고, 에이전트를 실행하며, 메모리를 읽고, 메시지를 테일링 (tailing)하며, 런타임 및 MCP와 브릿지 (bridge) 역할을 합니다.

이것이 바로 APX가 저장소를 오염시키지 않으면서도 로컬 상태 (local state)를 유지할 수 있는 이유입니다. 프로젝트는 git 상에서 깨끗하게 유지될 수 있는 동시에, APX는 이 머신에서 무슨 일이 일어났는지 기억할 수 있습니다.

작은 워크플로 (workflow)가 이 분리를 보여줍니다:

apx init
apx memory reviewer
apx messages tail

apx init은 프로젝트를 런타임에 가시적으로 만듭니다. apx memory는 지속적이고 큐레이션된 사실들을 보여줍니다. apx messages tail은 실시간 런타임 활동을 보여줍니다. 하나의 프로젝트, 두 개의 레이어, 어떤 상태가 이동해야 하는지에 대한 혼란은 없습니다.

더 깊은 이유

이 경계는 순수성에 관한 것이 아닙니다. 자동화를 지속 가능하게 만드는 것에 관한 것입니다.

Portable context (이동 가능한 컨텍스트)는 저장소(repo)가 노이즈가 아닌 의미를 담고 있을 때만 작동합니다. Local runtime (로컬 런타임)은 머신이 프로젝트의 진실(project truth)을 다시 쓰지 않고도 자체적인 transient state (일시적 상태)를 유지할 수 있을 때만 작동합니다. APC는 첫 번째를 제공하고, APX는 두 번째를 제공합니다.

이 경계선을 명확하게 유지한다면, 스택은 디버깅하기 더 쉽고, 공유하기 더 쉬우며, 도구 간에 이동하기 더 쉬운 상태를 유지할 것입니다.

Bottom line (결론)

저장소와 함께 이동해야 하는 컨텍스트에는 APC를 사용하세요.
현재 머신에 속하는 컨텍스트에는 APX를 사용하세요.

만약 어떤 것이 진정한 프로젝트의 진실(project truth)이라면, 이를 portable (이동 가능)하게 만드세요. 만약 그것이 개인적이고, 비공개적이거나, transient (일시적)인 것이라면, 로컬(local)에 유지하세요. 이 단 하나의 규칙이 APC를 작게 유지하고 APX를 유용하게 만듭니다.