이식 가능한 에이전트 계약은 로컬 플랜에 연결할 수 없다

AGENTS.md 파일은 모든 호환 가능한 에이전트에게 저장소를 어떻게 처리해야 하는지 알려줄 수 있습니다. 하지만 규칙이 한 개발자의 컴퓨터에만 존재하는 플래닝 파일에 연결될 때 이 약속은 깨집니다. 그 링크는 작성자에게는 작동하지만, 새로 클론한 환경에서는 막다른 길이 됩니다.

이는 사소한 경계이지만, 이식 가능한 컨텍스트를 테스트하는 데 유용한 방법입니다. 만약 미래의 기여자가 지침과 그것이 의존하는 모든 문서를 읽을 수 없다면, 그 지침은 아직 프로젝트 계약이라고 할 수 없습니다.

APC는 이식 가능한 컨텍스트 레이어(portable context layer)입니다. 이는 저장소 소유의 규칙, 에이전트 정의, 스킬, 그리고 비공개 MCP 기대치를 AGENTS.md와 .apc/에 보관합니다. APX는 일상적인 사용 런타임 및 도구링 레이어(tooling layer)입니다. 이는 에이전트를 실행하고 세션, 개인 런타임 메모리, 캐시, 기계별 상태와 같은 로컬 운영 자료를 저장소 외부로 유지합니다.

로컬 플랜은 명시적으로 공유 가능한 프로젝트 아티팩트로 승격되지 않는 한, 이 경계의 APX 측에 속해야 합니다.

링크는 소유권 주장이다

다음 루트 지침을 고려해 봅시다:

Read `spec/release-notes.md` before changing the deployment flow.

만약 spec/이 탐색적인 메모나 원시 QA 증거를 담고 있어 무시된다면, 새로 클론한 환경에는 파일도 그 추론 과정도 없습니다. 루트 계약은 이제 에이전트에게 이용할 수 없는 컨텍스트를 따라가라고 요구합니다. 더 나쁜 것은, 작성자의 작업 트리(working tree)가 링크를 완벽하게 해결하기 때문에 검토자가 이 오류를 놓칠 수 있다는 것입니다.

동일한 문제가 절대 경로, 비공개 이슈 내보내기, 임시 디자인 메모, 런타임 로그에서도 나타납니다. 이들은 하나의 작업 중에는 유용할 수 있습니다. 하지만 이식 가능한 동작의 전제 조건이 될 수는 없습니다.

AGENTS.md, .apc/, 또는 추적되는 문서에서 나오는 모든 링크를 주장의 관점에서 다루십시오: 이 대상은 영구적이며, 공유하기 안전하고, 깨끗한 체크아웃(clean checkout)에도 이용 가능해야 합니다. 만약 그 주장이 거짓이라면, 계약을 변경하십시오.

스크래치패드가 아닌 결정을 승격시켜라

스크래치패드가 아닌 결정을 승격시켜라

로컬 플랜에는 임시 자료와 섞여 가치가 있는 사고 과정이 담겨 있을 때가 많습니다. 단순히 깨진 링크를 수리하기 위해 전체 파일을 APC에 복사하지 마십시오. 검토를 통과하는 부분만 추출하십시오.

예를 들어, 로컬 릴리스 조사에서는 '생성된 에셋은 게시 전에 확인되어야 한다'는 지속적인 규칙 하나가 확립될 수 있습니다. 이 규칙은 AGENTS.md에 직접 존재할 수도 있고, 간결한 설명이 추적되는 결정 문서가 될 수도 있습니다. 원시 명령어 출력, 불완전한 대안, 기계 경로 등은 로컬 상태로 남겨둡니다.

실용적인 승격 흐름은 다음과 같습니다:

1. 작업이 활성화된 동안에는 작업 진행 계획과 원시 증거를 로컬에 유지합니다.
2. 미래의 기여자들에게 실제로 필요한 결정을 식별합니다.
3. 이를 짧고 자체적으로 완결된 프로젝트 규칙이나 추적 문서로 재작성합니다.
4. APC 컨텍스트에서 해당 추적 아티팩트만 링크합니다.

이렇게 하면 깨끗한 클론이 사적이거나 오래된 작업 기록을 가져오지 않고도 행동할 수 있는 충분한 지침을 얻게 됩니다.

가장 작은 영속적인 표면을 사용하라

모든 노트가 새로운 문서를 필요로 하는 것은 아닙니다. 저장소 전체에 적용되는 지침은 AGENTS.md에 속합니다. 재사용 가능한 절차는 APC 스킬이 될 수 있습니다. 단지 하나의 폴더에만 관련된 규칙은 .apc/rules/에 위치해야 합니다. 더 길고 검토 가능한 근거는 일반적인 추적 프로젝트 문서에 존재할 수 있습니다.

중요한 부분은 파일 이름 자체가 아닙니다. 그 내용이 그것을 생성한 기계를 넘어 진실하고, 읽기 쉬우며, 유용하게 남아 있는가 여부입니다.

APX는 다른 카테고리도 포터블하다고 가장하는 대신 유용하게 유지하도록 돕습니다. 로컬 런타임은 자체 스토리지 하에 세션, 메시지, 작업 상태 및 사적인 작업 자료를 보존할 수 있습니다. 이를 통해 활성 작업이 상세 내용을 유지하면서 그 상세 내용이 저장소 계약으로 새어 나가는 것을 방지합니다.

신규 클론 테스트

컨텍스트 링크를 추가하기 전에 하나의 질문을 던지십시오. '오늘 다른 기계에서 이 저장소를 클론한 에이전트에게도 이것이 도움이 될까?'

만약 그렇다면, 이를 추적하고 대상 자체를 완결하게 만드십시오. 그렇지 않다면, 로컬 플랜이나 런타임 상태에 남겨두고, 실제 프로젝트 제약 조건이 되었을 때 검증된 결론만을 승격시키십시오.

포터블 컨텍스트(Portable context)는 참조들로 가득 찬 디렉토리가 아닙니다. 그것은 그 자체로 설 수 있는 계약입니다. APC가 그 계약을 지니고 있으며, APX가 주변의 로컬 작업을 처리합니다.