AGENTS.md, project.json, 그리고 rules: 작동 가능한 가장 작은 APC 경계

APC는 그 레이어(layer)가 작고 뚜렷하게 유지될 때만 유용합니다. 흔히 하는 실수는 하나의 파일을 모든 종류의 프로젝트 지식을 담는 만능 도구로 만드는 것입니다. 이는 첫날에는 더 간단해 보일 수 있지만, 결국 드리프트(drift), 중복, 그리고 도구별 잡동사니(clutter)로 변질됩니다.

더 나은 분할 방식은 다음과 같이 좁게 설정하는 것입니다:

• AGENTS.md: 저장소 전체(repo-wide) 계약용
• .apc/project.json: 안정적인 프로젝트 메타데이터(metadata)용
• .apc/rules/: 경로 범위(path-scoped) 또는 작업 범위(task-scoped) 규칙용
• .apc/agents/ 및 .apc/skills/: 재사용 가능한 구조화된 지침(structured instructions)용

이것은 단순히 깔끔함을 위한 것이 아닙니다. 이것이 바로 APC를 도구 간에 이식 가능(portable)하게 만들고, 기기 간에 반복 가능(repeatable)하게 유지하는 방법입니다.

AGENTS.md는 광범위한 계약입니다

APC는 AGENTS.md를 루트 프로젝트 표면(root project surface)으로 사용합니다. 문서에서는 이를 광범위한 저장소 계약(broad repository contract)으로 설명합니다. 즉, 호환 가능한 모든 에이전트(agent)가 저장소에 진입할 때 반드시 확인해야 하는 규칙들을 위한 장소입니다.

이는 다음과 같은 항목들을 의미합니다:

• 빌드(build) 또는 테스트(test) 기대 사항
• 보안 경계(security boundaries)
• 저장소 전체 컨벤션(conventions)
• 주요 워크플로(workflow) 참고 사항

만약 규칙이 모든 곳에 적용되어야 한다면, AGENTS.md가 적절한 위치입니다.

중요한 부분은 범위(scope)입니다. AGENTS.md가 기록물 더미(transcript dump)가 되거나 모든 사소한 예외 사항을 숨겨두는 장소가 되어서는 안 됩니다. 이것은 최상위 신호(top-level signal)입니다. 즉, 이 저장소가 무엇인지, 어떻게 동작하는지, 그리고 에이전트가 무언가를 건드리기 전에 무엇을 준수해야 하는지를 나타냅니다.

.apc/project.json은 안정적인 정체성입니다

워크스페이스 메타데이터(workspace metadata) 파일은 프로젝트에 일관된 정체성을 부여합니다. 현재 초안 및 참조 구현(reference implementation)에서 해당 파일은 .apc/project.json입니다.

문서에서는 다음과 같은 최소한의 형태를 보여줍니다:

{
  "name": "My Project",
  "version": "0.1.0",
...

해당 파일은 다음과 같은 소수의 질문에 답할 수 있어야 합니다:

• 이 프로젝트의 이름은 무엇인가
• 어떤 프로젝트 버전인가
• 어떤 APC 타겟 버전(target version)을 기대하는가
• APC 메타데이터 세트가 언제 생성되었는가

그것으로 충분합니다. 이 파일은 지루할 정도로 단순하게 유지되어야 합니다.

왜 작게 유지해야 할까요? 메타데이터는 안정적이어야 하기 때문입니다. 만약 프로젝트의 정체성 (identity)이 지침 (instructions), 런타임 상태 (runtime state), 또는 워크플로 노이즈 (workflow noise)를 흡수하기 시작한다면, 그 파일은 정체성이 아닌 잡동사니 서랍 (junk drawer)이 되어버립니다.

.apc/rules/는 정밀함이 필요한 곳입니다

어떤 지침은 리포지토리 전체에 적용되지 않습니다. 어떤 지침은 단 하나의 경로 (path), 하나의 서브시스템 (subsystem), 또는 하나의 작업 유형에만 중요합니다. 그것이 바로 .apc/rules/가 존재하는 이유입니다.

문서에서는 다음과 같은 경로 범위 지정 규칙 파일 (path-scoped rule files)을 권장합니다:

.apc/rules/backend.mdc
.apc/rules/frontend.mdc
.apc/rules/security-review.md

규칙이 전체 리포지토리보다 좁은 범위일 때 이 레이어 (layer)를 사용하세요:

• 백엔드 요청 검증 (backend request validation)
• 프론트엔드 스타일 제약 사항 (frontend style constraints)
• 보안 리뷰 노트 (security review notes)
• 마이그레이션 전용 리마인더 (migration-specific reminders)

이러한 분리가 중요한 이유는 루트 계약 (root contract)을 짧게 유지할 수 있기 때문입니다. 프론트엔드 규칙이 리포지토리 전체 지침을 어지럽힐 필요가 없으며, 백엔드 규칙이 일반적인 프로젝트 개요에 강제로 포함될 필요도 없습니다.

이것이 APX에도 중요한 이유

APX는 APC를 소비하는 런타임/툴링 레이어 (runtime/tooling layer)입니다. APX의 README에 따르면 파일 시스템이 진실의 근원 (source of truth)입니다. 즉, 프로젝트 정의와 큐레이션된 메모리 (curated memory)는 리포지토리에 머물고, 런타임 상태 (runtime state)는 ~/.apx/에 존재합니다.

이는 APC 자체가 깨끗하게 유지될 때만 작동합니다.

만약 경계면 (surfaces)을 모호하게 만들면, APX는 추측을 해야만 합니다. 반면 이들을 분리해 두면 APX는 더 단순한 작업을 수행할 수 있습니다:

• AGENTS.md에서 루트 계약 (root contract)을 읽음
• .apc/project.json에서 프로젝트 정체성 (project identity)을 읽음
• .apc/rules/에서 경로 범위 지정 지침 (path-scoped guidance)을 로드함
• 세션 (sessions), 로그 (logs), 그리고 기타 런타임 상태를 리포지토리 외부로 유지함

그 결과 드리프트 (drift)가 줄어듭니다. 새로운 도구들도 동일한 프로젝트 계약을 읽을 수 있습니다. 기존 도구들은 별도의 예외 처리를 할 필요가 없습니다. 리포지토리는 이식성 (portable)을 유지합니다.

실질적인 테스트

파일을 추가하거나 규칙을 옮기기 전에, 세 가지 질문을 던져보세요:

1. 모든 에이전트 (agent)에게 이것이 필요한가? 그렇다면 AGENTS.md에 넣으세요.
2. 이것이 안정적인 정체성 데이터 (stable identity data)인가? 그렇다면 .apc/project.json에 넣으세요.
3. 이것이 단 하나의 경로 또는 작업에만 중요한가? 그렇다면 .apc/rules/에 넣으세요.

만약 이 중 어디에도 해당하지 않는다면, 그것은 APC가 아니라 APX 런타임 상태 (runtime state) 또는 일반적인 프로젝트 문서에 속할 가능성이 높습니다.

이 확인 과정은 간단하지만, 대부분의 혼란을 방지해 줍니다.

결론 (Bottom line)

APC는 하나의 거대한 설정 덩어리 (config blob)가 아닙니다. 명확한 계층을 가진 작은 계약 (contract)입니다.

AGENTS.md는 저장소 (repo)를 어떻게 다뤄야 하는지를 말해줍니다. .apc/project.json은 프로젝트가 무엇인지를 말해줍니다. .apc/rules/는 예외 사항들이 어디에 있는지를 말해줍니다.

이러한 경계를 명확하게 유지하면, APC는 또 다른 도구 전용 폴더로 변질되지 않고 휴대성 (portable)을 유지할 수 있습니다.