경로 범위 규칙은 단순한 메모가 아닌 매칭 계약

모든 곳에 적용되는 규칙은 작성하기는 쉽지만, 유지보수하기는 비용이 많이 듭니다.

프로젝트에는 지침들이 쌓입니다: API 입력 유효성 검사, 마이그레이션 호환성 유지, 릴리스 노트 작성, 문서화 예제 최신 상태 유지. 이 모든 지침들은 유용합니다. 하지만 에이전트가 같은 파일을 편집하는 동안에는 모두 관련성이 있는 것은 아닙니다.

APC(Agent Project Context)는 이러한 구분을 휴대 가능한 형태로 제공합니다. 리포지토리 전체에 걸친 기대 사항은 AGENTS.md에 속해야 합니다. 트리의 특정 부분에만 중요한 규칙은 해당 규칙이 적용되는 곳을 명시하는 프론트매터와 함께 .apc/rules/에 위치해야 합니다. 핵심 주장은 간단합니다: 경로 범위 규칙은 매칭 계약입니다. 그 glob(글롭) 패턴 자체가 의미의 일부를 구성합니다.

작은 규칙

API와 문서화 사이트를 가진 리포지토리를 상상해 보세요. API는 요청 경계 유효성 검사와 신중한 호환성 처리가 필요합니다. 문서 페이지는 정확한 예제가 필요하지만, 모든 편집에서 라우트 유효성 검사에 대한 경고가 필요하지는 않습니다.

API에 특화된 지침을 .apc/rules/backend.mdc와 같은 규칙 파일에 넣습니다:

---
description: "백엔드 API 규칙"
globs:
...

이 파일은 두 가지 다른 사실을 담고 있습니다. 마크다운 본문은 무엇을 해야 하는지 설명합니다. 프론트매터는 지침이 언제 중요한지를 설명합니다. 둘 중 어느 하나를 제거하면 계약 자체가 변경됩니다.

alwaysApply: false가 중요한 이유

alwaysApply: false는 유용한 제약을 표현합니다: 이것을 프로젝트 전체의 명령으로 만들지 말라는 것입니다. src/api/orders.ts를 변경하는 작업은 백엔드 규칙을 받아야 합니다. docs/getting-started.mdx를 업데이트하는 작업이 이 규칙들을 주요 컨텍스트로 다룰 필요는 없습니다.

이는 중요한 제약 사항을 숨기려는 시도가 아닙니다. 오히려 제약 사항을 더 쉽게 따르도록 만드는 방법입니다. 관련성이 높고 좁은 규칙일수록 눈에 띄기 쉬우며, 무관한 지침들 사이에 희석될 가능성이 적습니다.

대안은 거대한 루트 파일 하나입니다. 이는 좋은 시작점입니다. 모든 규칙이 한 곳에서 보이기 때문입니다. 시간이 지나면서 데이터베이스 마이그레이션 조언, UI 컨벤션, 배포 명령어 및 사고 절차가 첨부된 문서 변경 사항이 도착합니다. 에이전트는 어떤 부분이 중요한지 추측해야 합니다. 인간도 검토 과정에서 같은 일을 합니다.

매칭 표면(matching surface)은 유지보수의 일부입니다

규칙 텍스트가 잘못되지 않아도 glob 패턴은 틀어질 수 있습니다. 예를 들어, API가 src/api/에서 services/http/로 이동한다고 가정해 봅시다. 유효성 검사 규칙은 여전히 올바른 관행을 설명할 수 있지만, src/api/**/*.ts는 더 이상 그 규칙이 필요한 파일을 지정하지 않습니다. 규칙이 조용히 도달 범위를 잃어버린 것입니다.

이를 계약 변경(contract change)으로 간주하십시오:

---
description: HTTP 서비스 규칙
globs:
...

이는 코드 검토에 구체적인 질문을 던집니다. 매칭 표면이 코드와 함께 이동했는가?

APC와 APX가 만나는 지점

APC는 이식 가능한 컨텍스트 레이어(portable context layer)입니다. 이는 프로젝트 내에 루트 계약, 재사용 가능한 스킬, 에이전트 정의 및 범위 지정된 규칙을 유지하며, 도구 브랜드 폴더에는 그렇지 않습니다. .mdc 규칙은 대상이 해당 프로젝트를 기준으로 상대적으로 설명되기 때문에 체크아웃과 함께 이동할 수 있습니다.

APX는 일상 사용 런타임 및 도구링 레이어(tooling layer)입니다. 이는 세션, 메시지, 루틴 및 비공개 런타임 상태가 로컬로 유지되는 동안 해당 프로젝트 컨텍스트를 소비할 수 있습니다. 여기서 경계가 중요합니다. 범위 지정된 규칙은 지속 가능한 공유 프로젝트 지식인 반면, 특정 편집에 대한 런타임 대화는 그렇지 않습니다.

병합(merging) 전 실용적인 점검

범위 지정된 APC 규칙을 추가하거나 편집할 때 세 가지 질문을 해보십시오:

1. 본문이 이 파일들에 진정으로 국한된 하나의 동작을 명시하는가?
2. globs가 관련 없는 작업을 포착하지 않으면서, 해당 동작이 필요한 모든 파일을 매칭하는가?
3. 폴더 이름 변경이 이 파일을 업데이트하도록 요구할 것인가?

마지막 질문에 대한 답이 '예'라면, 그 규칙은 유용한 작업을 수행하고 있는 것입니다. 검토 과정에서 그 매칭 표면을 보이게 유지하십시오. 지침이 명확한 집과 명확한 경계를 가질 때 이식 가능한 컨텍스트는 신뢰할 수 있습니다.