설명(Description)은 로딩을 트리거해야 하며, 컨텍스트를 저장해서는 안 됩니다

짧은 설명(description) 필드는 런타임(runtime)이 무엇을 로드할지 결정하는 데 도움을 주어야 합니다. 프로젝트의 절반을 숨겨두는 은신처가 되어서는 안 됩니다.

그 경계는 APC와 APX에서 매우 중요합니다.

APC는 휴대 가능한 컨텍스트 레이어(portable context layer)입니다. 이는 AGENTS.md, .apc/agents/<slug>.md, .apc/skills/<slug>/SKILL.md와 같은 파일에 저장된 리포지토리 소유의 계약(contract)을 유지합니다. APX는 일상적으로 사용하는 런타임 및 툴링 레이어(runtime and tooling layer)입니다. APX는 해당 계약을 읽고, 프롬프트(prompts)를 구축하며, 어떤 스킬 바디(skill bodies)를 로드할지 선택하고, 런타임 상태(runtime state)를 로컬로 유지합니다.

이러한 분리를 수용하고 나면 규칙은 간단해집니다: 설명은 라우팅 힌트(routing hints)입니다. 지속적인 컨텍스트(Durable context)는 다른 곳에 있어야 합니다.

왜 이 구분이 중요한가

AGENTS.md를 위한 APC 컴패니언 스펙(companion spec)은 Description을 에이전트(agent)의 한 줄 요약으로 정의합니다. 이는 이미 올바른 방향을 가리키고 있습니다. 그것은 인덱스 필드(index field)이지, 메모리 덤프(memory dump)가 아닙니다.

APC의 apc-context 스킬은 description이 의미론적 활성화(semantic activation)를 위해 존재해야 한다고 명시함으로써 동일한 설계 의도를 더욱 명확하게 만듭니다.

그 후 APX는 그 설계를 런타임 동작으로 전환합니다.

apx-skill-builder 스킬에서 규칙은 명시적입니다: 스킬의 description은 모델이 load_skill을 호출할지 결정할 때 보는 것이므로, 본문 요약이 아닌 트리거 조건(trigger condition)으로 작성되어야 합니다. apx-agent 스킬에서도 규칙은 똑같이 직접적입니다: Description에 장기 실행 컨텍스트(long-running context)를 넣지 마세요; 대신 memory.md에 넣으세요.

이것이 축소된 형태의 깨끗한 APC/APX 계약입니다:

• APC는 지속적인 아티팩트(durable artifact)를 저장합니다.
• APX는 짧은 설명을 사용하여 해당 아티팩트가 이번 턴(turn)에 활성화되어야 하는지 결정합니다.

각 위치에 들어갈 내용

만약 어떤 세부 사항이 모델이 에이전트나 스킬을 언제 사용할지 인식하는 데 도움이 된다면, 그것은 짧은 설명(short description)에 속합니다.

만약 어떤 세부 사항이 에이전트가 시간이 지남에 따라 어떻게 행동해야 하는지를 설명하거나, 지속적인 프로젝트 사실(durable project facts)을 보존한다면, 그것은 본문(body)이나 메모리(memory)에 속합니다.

즉, 다음과 같습니다:

• 에이전트 (agent) Description은 책임을 명시하고 트리거(trigger) 언어를 포함해야 합니다.
• 스킬 프론트매터 (skill frontmatter)의 description은 언제 이를 로드해야 하는지 명시해야 합니다.
• 에이전트 메모리 (agent memory)는 여러 턴(turn) 동안 유지되어야 하는 지속적인 컨텍스트 (context)를 보유해야 합니다.
• 스킬 본문 (skill bodies)은 실제 지침 (instructions), 예시 (examples), 그리고 주의 사항 (gotchas)을 보유해야 합니다.

실수는 이 네 가지 작업을 하나의 필드에 모두 뭉쳐 넣는 것입니다.

실질적인 예시

어떤 프로젝트에 MCP 설정을 위한 스킬이 있다고 가정해 봅시다.

잘못된 설명 (Bad description):

description: 이 스킬은 APX의 MCP 시스템을 설명합니다.

이것은 APX에게 언제 이를 로드해야 하는지에 대해 거의 아무것도 알려주지 않습니다.

더 나은 설명 (Better description):

description: APX에서 MCP 서버를 등록하고 디버깅합니다. `apx mcp add` 또는 `apx mcp check`를 실행하기 전에 로드하십시오. 스코프 (scopes), stdio 주의 사항 (gotchas), 그리고 비밀 정보 (secrets) 처리를 다룹니다.

이제 이 필드는 실제적인 역할을 수행합니다. 런타임 (runtime) 트리거 문구, 명령 이름, 그리고 결정 경계 (decision boundary)를 제공합니다.

동일한 패턴이 에이전트 (agents)에도 적용됩니다.

취약한 에이전트 설명 (Weak agent description):

- **Description**: 다양한 도메인에 걸친 폭넓은 경험과 품질에 강력한 초점을 맞춘 시니어 엔지니어.

이것은 사람에게는 좋게 들리겠지만, 런타임 힌트 (runtime hint)로서는 모호합니다.

더 강력한 설명 (Stronger description):

- **Description**: 풀 리퀘스트 (pull requests)를 검토하고, 테스트 위험 및 마이그레이션 위험 요소를 확인합니다. 회귀 (regressions), 누락된 커버리지 (missing coverage), 그리고 위험한 차이점 (risky diffs)에 사용하십시오.

이것은 APX가 더 명확한 프롬프트 (prompt)를 구성하도록 도우며, 다른 도구들이 거대한 덩어리 (blob)를 먼저 읽지 않고도 적절한 에이전트를 발견할 수 있도록 돕습니다.

이것이 APC의 이식성을 유지하는 이유

팀이 설명 (descriptions)에 너무 많은 내용을 집어넣으면, 이식 가능한 컨텍스트 (portable context)는 빠르게 노이즈가 심해집니다.

인덱싱 (indexable) 가능한 상태로 유지되어야 할 필드에 미니 프롬프트 (mini-prompts)를 담기 시작하면, 리포지토리 (repo)가 무거워집니다. 디프 (diff) 품질이 떨어집니다. 발견성 (discovery)이 악화됩니다. 두 도구가 동일한 프로젝트를 파싱하더라도, 설명이 깔끔한 요약이 아니라 과부하된 지침 바구니 (instruction bucket)가 되어버리면 서로 다른 동작을 나타낼 수 있습니다.

트리거 중심의 짧은 설명은 이를 방지합니다.

이러한 방식은 APC 파일을 Git에서 읽기 쉽게 유지하고, 도구 간에 이식 가능하게 하며, 재생성하거나 정규화 (normalize)하기 쉽게 만듭니다.

이것이 APX를 효율적으로 유지하는 이유

APX는 매 턴마다 모든 무거운 명령 블록 (instruction block)을 미리 로드하지 않을 때 가장 잘 작동합니다.

이것이 짧은 트리거 텍스트 (trigger text)가 중요한 이유입니다. APX는 먼저 작은 의미적 표면 (semantic surface)을 스캔한 다음, 작업이 실제로 필요할 때만 일치하는 스킬 본문 (skill body) 또는 메모리 (memory)를 로드할 수 있습니다. 프롬프트 노이즈 (prompt noise)는 줄어들고, 라우팅 (routing)은 개선되며, 컨텍스트 (context)는 더 작아집니다.

따라서 이 규칙은 미적인 것이 아니라 운영적인 것입니다.

설명 (description)은 "언제 이것이 활성화되어야 하는가?"라는 질문에 답하는 데 사용하십시오.
메모리 (memory)와 스킬 본문 (skill body)은 "활성화되면 무엇을 해야 하는가?"라는 질문에 답하는 데 사용하십시오.

이를 통해 APC를 작고 이식 가능하게 유지하는 동시에, APX는 일상적인 사용에서 정밀함을 유지할 수 있습니다.