APX Init: AGENTS.md에서 실제 APC 프로젝트로 넘어가는 가교

APC는 프로젝트에 컨텍스트 (Context)를 위한 하나의 휴대 가능한 홈을 제공합니다. APX는 그 홈을 매일 사용할 수 있게 만듭니다. 이 두 레이어 사이의 깔끔한 핸드오프 (Handoff)는 apx init에서 시작됩니다.

클론된 레포지토리 (Repo)에는 이미 유용한 규칙들이 포함되어 있을 수 있지만, APX가 초기화된 APC 프로젝트를 인식하기 전까지는 작업할 수 있는 안정적인 프로젝트 경계가 없습니다. 이것이 apx init이 중요한 이유입니다. 이는 노이즈를 추가하는 것이 아닙니다. 지침이 담긴 폴더를 APX가 인식하고, 로드하고, 작동할 수 있는 프로젝트로 변환합니다.

AGENTS.md는 스타트업 규칙이며, 프로젝트 전체가 아닙니다

APX에서 AGENTS.md는 컨벤션 (Convention)을 이해하는 에이전트 (Agents)와 도구 (Tools)를 위한 스타트업 파일입니다. 스캐폴드 (Scaffold)는 이를 명확히 합니다: 이는 AGENTS.md를 인식하는 도구들에 의해 읽히며, 에이전트 레지스트리 (Agent registry) 그 자체는 아닙니다. 실제 에이전트 정의는 .apc/agents/<slug>.md에 존재합니다.

이러한 분리는 유용합니다. AGENTS.md는 도구들에게 이 레포지토리에서 어떻게 행동해야 하는지를 알려줍니다. .apc/는 APX가 기반으로 삼을 수 있는 프로젝트별 APC 데이터를 보유합니다.

apx init이 실제로 작성하는 것

apx init 명령은 의도적으로 단순하게 설계되었습니다. 선택한 경로에 APC 프로젝트 형태를 생성하고 APX가 기대하는 핵심 파일들을 작성합니다. CLI 도움말에 따르면, 이는 현재 디렉토리 또는 대상 경로에 APC 프로젝트 파일들을 초기화하며, 스캐폴드는 프로젝트 메타데이터 (Metadata)를 .apc/project.json에 작성합니다.

그 메타데이터는 폴더 이름보다 더 중요합니다. 이는 프로젝트에 안정적인 정체성, 표시 이름, 그리고 이 디렉토리가 단순한 레포지토리가 아님을 APX가 알 수 있게 하는 마커 (Marker)를 부여합니다. 만약 APX가 해당 프로젝트 마커를 찾지 못하면, 프로젝트 컨텍스트에 의존하는 명령들은 실행을 거부합니다.

이러한 동작은 제한 사항이 아니라 기능입니다. 이는 APX가 추측하는 것을 방지합니다.

이 경계가 일상 업무에 도움이 되는 이유

실질적인 가치는 설정이 명시적으로 유지된다는 점에 있습니다:

cd my-repo
apx init
apx agent add editor --role "Software Developer" --model inherit
...

apx init 이후, 저장소(repo)는 안정적인 APC 루트를 갖게 됩니다. 그러면 APX는 .apc/ 내의 프로젝트 파일들을 사용할 수 있는 반면, 런타임 상태(runtime state)는 ~/.apx/ 아래에 머신 로컬(machine-local)로 유지됩니다. 이러한 분리를 통해 이식 가능한 레이어(portable layer)는 깨끗하게 유지되고, 로컬 레이어(local layer)는 언제든 폐기 가능한 상태로 유지됩니다.

따라서 간단한 원칙은 다음과 같습니다:

• APC는 이식 가능한 컨텍스트 레이어 (portable context layer)입니다.
• APX는 일상적인 사용을 위한 런타임 및 툴링 레이어 (runtime and tooling layer)입니다.
• apx init은 이 둘 사이를 잇는 가교입니다.

만약 이 가교를 건너뛴다면, 파일들이 흩어지고 특정 도구에 종속된 가정(tool-specific assumptions)들이 생겨나게 됩니다. 반면 이 가교를 사용한다면, 저장소는 APX가 매일 신뢰할 수 있는 대상이 됩니다.

이것이 apx init의 진정한 역할입니다. 단순한 설정을 넘어, 프로젝트를 런타임(runtime)이 읽을 수 있는 상태로 만드는 것입니다.