구조화된 에이전트 파일은 상세 정보를 소유해야 하며, AGENTS.md는 이식성이 유지되어야 한다.

APC가 가장 잘 작동하는 방식은 두 가지 작업을 동시에 수행하면서도 이를 혼합하지 않는 것입니다.

첫 번째 작업: 모든 도구에 명확한 프로젝트 진입점(entrypoint)을 제공합니다. 즉, 리포지토리 루트의 AGENTS.md입니다.

두 번째 작업: APC를 인식하는 도구들을 위해 구조화된 상세 정보를 담을 더 깔끔한 장소를 제공합니다. 즉, .apc/agents/<slug>.md 파일로, 이는 .apc/project.json 옆에 위치합니다.

이러한 분리는 중요합니다. 왜냐하면 호환성(compatibility)과 구조(structure)는 같은 문제가 아니기 때문입니다.

AGENTS.md에 대한 APC 보조 사양(companion spec)에서, 루트 파일은 에이전트 검색을 위한 호환성 측면의 계약(contract)으로 정의됩니다. 이 파일은 프로젝트 루트, .apc/ 옆에 위치하며, 많은 도구들이 이미 이를 찾고 읽는 방법을 알고 있습니다. 같은 사양은 또한 동일한 슬러그(slug)에 대해 .apc/agents/<slug>.md가 존재하는 경우, 해당 구조화된 파일이 권위 있는 구조적 정의로 취급되어야 한다고 명시합니다.

이것이 올바른 경계입니다.

만약 모든 상세 정보를 AGENTS.md에 넣으려고 하면, 루트 계약이 복잡해집니다. 긴 설명(description), 사용자 지정 필드(custom fields), 메모리 재정의(memory overrides), 스킬 목록(skill lists), 그리고 서식 처리 예외 사례들이 모두 런타임이 가장 먼저 스캔해야 하는 하나의 파일에 쌓이게 됩니다. '단순한 진입점'이 마치 데이터베이스처럼 행동하기 때문에 이식성이 확보되는 것이 더 어려워집니다.

반대로 AGENTS.md를 완전히 제거한다면, 이식성은 더 나빠집니다. 많은 도구들이 리포지토리를 탐색하며 익숙한 루트 파일을 찾을 수 있습니다. 하지만 적은 수의 도구만이 첫날부터 사용자의 내부 구조화된 레이아웃을 알게 됩니다.

APC는 두 계층(layer)을 모두 유지함으로써 이러한 트레이드오프를 피합니다.

작은 루트 계약은 다음과 같을 수 있습니다:

# Agents

## reviewer
...

이것만으로도 검색, 라우팅, 그리고 프로젝트에 대한 1차적인 이해를 하기에 충분합니다.

그런 다음 더 풍부한 정의는 APC 인식 도구들이 예상하는 위치에 존재할 수 있습니다:

.apc/
  project.json
  agents/
...

이것은 APX가 프로젝트를 사용하는 방식과도 일치합니다.

APX는 런타임에 AGENTS.md를 프로젝트 가이드로 읽습니다. buildProjectAgentsBlock에서는 루트 파일을 로드하고, 필요할 경우 잘라낸 다음, “프로젝트 가이드 (AGENTS.md)”라는 프롬프트로 주입합니다. 이는 의도된 크기와 목적에 대한 강력한 힌트입니다. 즉, 끊임없이 커지는 에이전트 내부 정보의 나열이 아니라 유용한 시작 규칙이어야 합니다.

APX는 또한 AGENTS.md 섹션을 위한 전용 파서(parser)를 가지고 있습니다. 이 파서는 # Agents라는 헤딩을 찾고, 각 ## <slug> 블록을 읽어 Role, Model, Skills, Description과 같은 불릿 필드를 추출합니다. 이러한 파서는 루트 계약(root contract)이 예측 가능하고 포터블하게 유지되어야 하기 때문에 존재합니다.

따라서 실질적인 규칙은 간단합니다:

• 도구 간 발견(cross-tool discovery) 정보는 AGENTS.md에 넣습니다.
• 개별 에이전트에 대한 구조화된 상세 정보는 .apc/agents/에 넣습니다.
• 런타임 세션, 대화, 개인 상태는 둘 다에 넣지 않습니다. APX가 ~/.apx/ 아래에 저장합니다.

이를 통해 APC는 내구성 있고 포터블한 레이어를 얻고, APX는 깔끔한 일상 사용 런타임 레이어를 얻게 됩니다.

AGENTS.md는 사람이 읽기 쉽고 광범위하게 호환되는 도구에 의해 접근할 수 있도록 유지됩니다. .apc/agents는 더 풍부한 APC 네이티브 구조를 위해 계속 사용할 수 있습니다. 그러면 APX가 어느 쪽도 잘못된 종류의 저장소로 만들지 않으면서 둘 다를 연결(bridge)할 수 있게 됩니다.

포터블 프로젝트들은 보통 모두가 만지는 첫 번째 파일을 과부하하는 바람에 실패합니다. APC는 인덱스를 작게 유지하고 구조가 있어야 할 곳에 상세 정보를 두어 더 나아갑니다.