APX 프로젝트가 Git 리포지토리와 같지 않은 이유

에이전트 툴링에서 흔한 실수는 '프로젝트'를 코드 저장소로 정의하는 것입니다. 이는 개발자 데모에서는 작동하지만, 작업이 클라이언트 운영, 연구 노력, 가계 계획 또는 창의적 제작과 관련된 순간에는 실패합니다.

APX는 더 넓은 시각을 취합니다: 프로젝트란 크루가 공유해야 하는 작업 경계(shared working boundary)가 필요한 장소입니다. 코드베이스일 수도 있지만, 이름이 지정된 에이전트, 지침 및 반복 가능한 작업을 받을 자격이 있는 모든 디렉토리일 수도 있습니다. Git은 이력 관리와 협업이 필요할 때 유용합니다. 하지만 작업 자체를 프로젝트로 만드는 것은 아닙니다.

저장소가 아닌 '작업'부터 시작하기

APX는 먼저 기계에 설정된 다음, 하나의 에이전트로 실제 작업을 수행하는 데 사용될 수 있습니다. 이때는 어떤 리포지토리도 필요하지 않습니다. 이는 유용한 에이전트 작업이 코드가 존재하기 전에 시작되는 경우가 많기 때문에 중요합니다:

• 소규모 사업체는 주간 연구 보고서가 필요합니다.
• 작가에게는 편집자와 출판 체크리스트가 필요합니다.
• 가정은 반복적인 계획과 의사 결정 기록이 필요합니다.
• 제품 팀은 리포지토리가 생성되기 전 탐색 공간이 필요합니다.

각 경우에 유용한 경계는 .git 디렉토리가 아니라 작업 자체와 관련된 사람 또는 에이전트입니다.

디렉토리가 프로젝트가 될 때 포터블 컨텍스트 추가하기

디렉토리에 명시적인 APX/APC 프로젝트 경계가 필요할 때는 초기화합니다:

cd /path/to/project
apx init --name "Research Desk"

이 명령어는 AGENTS.md와 .apc/를 생성합니다. APC는 포터블 레이어(portable layer)입니다. 이는 프로젝트 지침과 디렉토리와 함께 이동할 수 있는 영구적이고 검토 가능한 컨텍스트를 담고 있습니다. 만약 해당 디렉토리가 나중에 Git에 커밋된다면, 동일한 파일들이 리포지토리와 함께 이동할 수 있습니다. 그렇지 않더라도, 호환되는 툴들에게 명확한 로컬 계약(local contract) 역할을 합니다.

APX는 그 계약 주변의 일상 사용 런타임(runtime)을 제공합니다: 에이전트, 대화, 루틴, 채널 및 로컬 실행. 이 런타임 상태는 프로젝트 디렉토리 외부인 ~/.apx/에 유지되므로, 포터블 프로젝트 컨텍스트와 혼동해서는 안 됩니다.

이러한 분리는 두 가지 잘못된 가정을 방지합니다. 첫째, 모든 비공개 대화나 자격 증명을 소스 제어(source control)에 속하는 파일로 취급하는 것을 피할 수 있습니다. 둘째, 코드 프로젝트가 기본적으로 얻는 구조를 비코드 작업에도 부여하는 것을 피할 수 있습니다.

유용한 발전 과정

실용적인 경로는 간단합니다:

1. 실제 작업을 위해 APX를 사용합니다.
2. 작업에 공유된 지침이나 재사용 가능한 역할이 필요할 때 프로젝트 디렉토리를 생성합니다.
3. apx init을 실행하여 APC 계약(contract)을 만듭니다.
4. 버전 기록이나 팀 협업이 실제로 요구될 때만 Git을 추가합니다.

이 순서는 도구를 작업에 맞게 유지시킵니다. Git은 여전히 훌륭한 인프라지만, 선택적인 인프라입니다. 프로젝트는 사람과 에이전트가 조정하는 지속 가능한 경계이며, 리포지토리(repository)는 그 경계를 저장하고 공유할 수 있는 단 하나의 방법일 뿐입니다.

APC는 그 경계를 포터블하게 만듭니다. APX는 그것을 매일 유용하게 만듭니다. 어느 것도 모든 의미 있는 프로젝트가 코드로 시작해야 한다고 가장할 필요성을 요구하지 않습니다.