외부 런타임(External Runtimes)은 AGENTS.md를 직접 읽어야 합니다

가장 깔끔한 APX 설계는 번역 계층(translation layer)이 아닙니다. 그것은 핸드오프(handoff)입니다.

APC는 휴대 가능한 컨텍스트 계층(portable context layer)입니다. APX는 일상적인 사용을 위한 런타임(runtime) 및 툴링(tooling) 계층입니다. APX가 Claude Code, Codex, OpenCode 또는 Aider와 같은 외부 런타임을 실행할 때, 작업은 간단합니다: 프로젝트를 찾고, 런타임을 시작하며, 해당 런타임이 프로젝트 자체의 계약(contract)을 읽도록 하는 것입니다.

이렇게 하면 저장소(repo) 내에 단일 진실 공급원(one source of truth)을 유지할 수 있으며 APX를 가볍게 유지할 수 있습니다.

이것이 중요한 이유

실패 모드(failure mode)는 놓치기 쉽습니다. 도구가 처음에는 유용하게 시작되지만, 프로젝트 규칙을 머신 로컬 프롬프트 블롭(machine-local prompt blobs), 캐시된 요약(cached summaries) 또는 숨겨진 어댑터 상태(hidden adapter state)로 복사하기 시작합니다. 처음에는 편리해 보입니다. 나중에는 괴리가 발생합니다.

런타임 전용 복사본이 존재하게 되면, 모든 변경 사항은 두 번 이동해야 합니다:

• 프로젝트 계약이 존재하는 APC에서 한 번
• 복사된 버전이 머물러 있는 런타임 래퍼(runtime wrapper)에서 한 번

이것이 팀들이 하나의 저장소를 가지면서도 두 개의 현실을 마주하게 되는 방식입니다.

APX는 실행 경계(execution boundary)에 머무름으로써 이를 방지합니다. 계약을 다시 작성할 필요가 없습니다. 단지 계약으로 가는 경로를 보존하기만 하면 됩니다.

APX가 해야 할 일

APX는 이미 올바른 작업 형태를 갖추고 있습니다:

• apx init은 APC 프로젝트 구조를 생성합니다.
• apx project add는 저장소를 프로젝트로 등록합니다.
• apx run은 작업을 런타임에 위임합니다.
• 런타임 상태(runtime state), 세션(sessions) 및 메시지 로그(message logs)는 ~/.apx/에 로컬로 유지됩니다.

이러한 분리가 핵심입니다. APC는 저장소를 휴대 가능하게 유지합니다. APX는 머신 로컬 작업을 로컬에 유지합니다.

따라서 외부 런타임이 시작될 때, 가장 좋은 결과는 지루할 정도로 단순한 것입니다: AGENTS.md를 읽고, 저장소 규칙을 로드하며, 그에 따라 직접 행동하는 것입니다.

중복된 프롬프트 저장소도, 미러링된 정책 파일도, 프로젝트 계약의 런타임 전용 복사본도 필요 없습니다.

구체적인 예시

다음과 같은 구조를 가진 저장소를 상상해 보세요:

project-root/
├── AGENTS.md
└── .apc/
...

리뷰 작업은 다음과 같을 수 있습니다:

apx run reviewer --runtime claude-code "Review the open PR and summarize risk"

저장소(repo)는 이미 프로젝트의 의도를 정의하고 있습니다. APX는 이를 두 번째 형식으로 다시 진술할 필요가 없습니다. APX는 제어권을 런타임(runtime)에 전달할 수 있으며, 런타임은 다음 개발자나 에이전트(agent)가 디스크에서 읽을 것과 동일한 계약(contract)을 읽을 수 있습니다.

이는 저장소가 검토 가능한 상태(reviewable)로 유지된다는 점에서 가치가 있습니다. 만약 AGENTS.md가 변경되면 git에서 그 변경 사항을 확인할 수 있습니다. 만약 런타임 동작이 변경되면 APX를 점검하면 됩니다. 각 계층은 하나의 작업만을 수행합니다.

하지 말아야 할 것

APX를 프로젝트의 의미를 축적하는 장소로 취급하지 마십시오.

만약 어떤 규칙이 저장소와 함께 이동해야 한다면, 그것을 APC에 유지하십시오. 만약 어떤 규칙이 이 머신이나 이 세션에서만 유효하다면, 그것을 APX 런타임 상태(runtime state)에 유지하십시오. 만약 이 경계를 모호하게 만든다면, 프로젝트의 이식성(portability)은 사라집니다.

흔한 실수는 더 많은 적응(adaptation)이 더 나은 UX를 의미한다고 생각하는 것입니다. 대개는 그 반대가 사실입니다. 추가적인 변환 계층(translation layers)은 모호함을 더합니다. 또한 버그가 저장소의 계약(repo contract)에 있는지, 아니면 그것을 복사한 래퍼(wrapper)에 있는지 아무도 알 수 없게 만들기 때문에 디버깅을 더 어렵게 만듭니다.

결론

APC는 프로젝트 계약(project contract)을 단 한 번 정의해야 합니다.

APX는 그 계약을 다시 쓰는 것이 아니라, 실행해야 합니다.

외부 런타임(external runtimes)이 AGENTS.md를 직접 읽을 때, 저장소는 신뢰할 수 있는 단일 원천(source of truth)으로 유지되고, 런타임은 가볍게(thin) 유지되며, 전체 시스템을 더 신뢰하기 쉬워집니다.

이것이 분리(split)의 진정한 가치입니다.