프로젝트 설정은 APC와 함께 이동해야 합니다

팀이 에이전트가 하나의 리포지토리에서 어떻게 행동해야 할지 결정할 때, 그 결정은 리포지토리와 함께 이동해야 합니다.

그것이 바로 프로젝트 설정이 APC에 존재해야 하는 이유입니다.

APC는 휴대 가능한 컨텍스트 레이어(portable context layer)입니다. 이는 리포지토리가 소유한 에이전트 컨텍스트를 AGENTS.md와 .apc/에 보관합니다. APX는 일상 사용 런타임 및 도구링 레이어(daily-use runtime and tooling layer)입니다. 이는 해당 휴대 가능한 컨텍스트를 읽고, 기계 로컬 런타임 설정과 병합하며, 세션, 메시지, 비밀 정보는 리포지토리 외부에 보관합니다.

이러한 분리는 특히 구성(configuration)과 함께 사용될 때 유용해집니다.

APX는 두 가지 구성 레이어를 문서화합니다.

• 전역 설정은 ~/.apx/config.json에 존재합니다.
• 프로젝트 설정은 .apc/config.json에 존재합니다.

규칙은 간단합니다: 기계 로컬 설정은 기계 로컬에 머무르지만, 리포지토리 소유의 동작(behavior)은 프로젝트와 함께 이동합니다.

이것은 단순한 편리함을 넘어섭니다. 이는 조용한 표류(silent drift)를 방지하는 경계입니다.

팀이 한 프로젝트가 Telegram 메시지를 reviewer 에이전트로 라우팅하고 기본 기계 설정과 다른 슈퍼 에이전트 모델을 사용하기를 원한다고 상상해 보세요. 만약 그 선택이 단지 개발자 한 명의 ~/.apx/config.json에만 존재한다면, 그 동작은 더 이상 진정으로 프로젝트의 일부가 아닙니다. 다른 기계에서 클론된 또 다른 시스템은 동일한 APC 프로젝트를 등록하고도 눈치채지 못하게 다른 운영 동작을 얻게 될 수 있습니다.

이 오버라이드를 .apc/config.json에 넣는 것이 문제를 해결합니다.

APX 문서의 작은 예시는 다음과 같습니다:

{
  

같은 문서들은 가장 중요한 경계선도 그어줍니다: 비밀 정보를 절대 `.apc/config.json`에 넣지 마십시오. API 키, 제공업체 자격 증명(provider credentials), 사용자의 장치용 데몬 설정, 기타 사적인 런타임 세부 정보는 저장소에 있는 것이 아니라 `~/.apx/config.json`에 속해야 합니다. APC는 안전하고 검토 가능한 프로젝트 동작을 담아야 하며, APX는 사적인 운영 상태를 로컬에 유지해야 합니다.

이것은 팀들에게 깔끔한 모델을 제공합니다:

-   프로젝트 오버라이드를 커밋한다.
-   자격 증명은 로컬에 보관한다.
-   APX가 런타임 시 두 가지를 병합하도록 한다.

이러한 분리가 없다면, 팀들은 보통 두 가지 나쁜 패턴 중 하나에 빠집니다.

첫 번째 나쁜 패턴은 프로젝트 동작을 하나의 노트북에 숨기는 것입니다. 중요한 에이전트 설정(agent settings)이 코드 검토에서 더 이상 보이지 않기 때문에 프로젝트를 재현하기가 어려워집니다.

두 번째 나쁜 패턴은 너무 많은 것을 커밋하는 것입니다. 프로젝트 설정과 런타임 설정 사이에 명확한 경계가 없기 때문에, 사람들이 키(keys), 로컬 제공업체 엔드포인트(local provider endpoints), 또는 일회성 장치 수정 사항을 공유 파일에 넣기 시작합니다.

APC와 APX는 이 두 가지 실수를 모두 피하면서 경계를 직접 명명합니다.

여기에는 휴대성(portability)상의 이점도 있습니다. APC는 APX가 세션, 메시지 또는 캐시를 어떻게 저장하는지 알 필요가 없습니다. 단지 다른 런타임이 나중에 이해할 수 있는 프로젝트 소유의 사실들만 보존하면 됩니다. 커밋된 `.apc/config.json`은 그 프로젝트 계약(project contract)의 일부입니다. 설령 다른 APC 호환 런타임이 결국 그것의 일부만을 읽는다 하더라도, 저장소에는 여전히 의도된 동작에 대한 가시적이고 검토 가능한 진실의 원천(source of truth)이 남아 있습니다.

따라서 실질적인 논지는 작지만 중요합니다:

만약 어떤 설정이 이 저장소가 어떻게 동작해야 하는지를 설명한다면, 그것을 APC에 넣으십시오.

만약 어떤 설정이 사용자의 장치, 자격 증명 또는 로컬 런타임 상태를 설명한다면, 그것을 APX에 유지하십시오.

휴대 가능한 컨텍스트(Portable context)는 이동해야 합니다. 사적인 런타임 상태는 이동해서는 안 됩니다. 프로젝트 설정은 이 APC/APX 경계가 매일 빛을 발하는 가장 명확한 장소 중 하나입니다.