아티팩트 스키마 명세

Apothem 생태계의 모든 아티팩트에 대한 클래스별 YAML 프런트매터 템플릿과 필수 필드.

진실 공급원. 기계가 읽을 수 있고 게이트가 강제하는 계약은 src/apothem/schemas/ 아래의 클래스별 JSON 스키마(agent.schema.json, command.schema.json, skill.schema.json, …)입니다. 스킬과 명령 스키마는 additionalProperties: false를 선언하므로 알 수 없는 키를 거부하고, 에이전트, 출력 스타일, 플랜 스키마는 additionalProperties: true를 선언합니다. 이 페이지와 frontmatter-schema.mdx는 이 스키마들을 사람이 읽을 수 있게 투영한 두 문서입니다. 이 페이지는 클래스별 템플릿과 상세 예시를 담고, frontmatter-schema는 간결한 필수 키 색인을 담습니다. 페이지가 JSON 스키마와 어긋나는 경우에는 스키마가 우선합니다.

개요Copy Anchor Link

Apothem 소스 트리(src/apothem/ 아래와 루트 구성 표면)의 모든 아티팩트는 아티팩트 타입별 필수 필드와 선택 필드를 갖춘 YAML 프런트매터 블록(--- 구분자 사이)을 포함해야 합니다. 이 문서는 각 타입의 정식 스키마를 정의합니다.

공통 규칙:

• 프런트매터는 YAML 1.2를 준수합니다
• 모든 문자열 값은 큰따옴표를 사용하며, 빈 문자열은 ""로 씁니다
• 필드 순서: 필수 필드를 먼저 두고, 선택 필드는 관련성에 따라 묶습니다
• 프런트매터의 주석은 뒤에 공백이 오는 #를 사용합니다: # comment
• 경로 값은 상대 경로여야 하며(앞에 / 없음), 크로스 플랫폼 호환성을 위해 슬래시(/)를 사용해야 합니다

버전 관리 규약(버전이 매겨지는 아티팩트 클래스 — 명령, 헬퍼, 스킬, CLAUDE.md):

• version은 시맨틱 버전(MAJOR.MINOR.PATCH)입니다. 스키마나 계약을 깨는 변경에는 MAJOR를, 호환성을 깨지 않는 추가형 변경(새 선택 필드, 추가 섹션, 추가 안티패턴)에는 MINOR를, 계약을 깨지 않으면서 기존 지침을 바로잡는 동작 변경에는 PATCH를 올립니다.
• 오타 수정, 링크 수정, 서식, 주석 전용 또는 문서 전용 편집은 version을 그대로 둡니다. 동작 변경만 버전을 올립니다.
• updated는 가장 최근 편집의 ISO 8601 날짜(YYYY-MM-DD)입니다. 모든 version 변경과 함께 반드시 바뀌어야 하며, 버전을 올리지 않는 오타나 링크 수정에서도 바뀝니다.
• 새 아티팩트는 v0.Y.Z에서 시작합니다. vX.Y.Z로의 승격은 아티팩트의 계약이 공개적 약속이 될 만큼 충분히 안정적임을 나타냅니다.
• 플랜 스위트는 이 규약 밖에 있습니다. 플랜 스위트의 오타 수정은 스위트 버전의 PATCH 번호를 올리고(vX.Y.Z에서 vX.Y.(Z+1)로), Revision History 행을 추가합니다. 개발자 가이드는 플랜 스위트 개정 절에서 플랜 스위트 규칙을 설명합니다.

스키마: 규칙Copy Anchor Link

경로 패턴: src/apothem/rules/*.md

목적: 행동 맨데이트와 운영 지침.

필수 필드Copy Anchor Link

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

선택 필드Copy Anchor Link

규칙에는 선택 프런트매터 필드가 없으며, 다른 아티팩트 클래스와 달리 version / updated / scope / portability 필드도 없습니다. 위의 네 가지 필수 필드가 frontmatter_grep이 강제하는 규칙 프런트매터 계약의 전부입니다.

예시Copy Anchor Link

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

스키마: 명령Copy Anchor Link

경로 패턴: src/apothem/commands/*.md

목적: 슬래시 명령 정의(/plan-execute, /freshify 등).

필수 필드Copy Anchor Link

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

선택 필드Copy Anchor Link

명령에는 선택 프런트매터 필드가 없습니다. 위의 여덟 가지 필수 필드가 command.schema.json(additionalProperties: false)이 강제하는 명령 프런트매터 계약의 전부입니다.

예시Copy Anchor Link

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

# /plan-execute — Execute a Specific Phase
...

스키마: 헬퍼Copy Anchor Link

경로 패턴:

src/apothem/agents/*.md

목적: 병렬 탐색, 감사, 품질 게이트를 위한 영속적인 헬퍼 정의(위임 작업자라고도 함).

필수 필드Copy Anchor Link

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

선택 필드Copy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

예시Copy Anchor Link

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
portability: "universal"
---

You are a codebase exploration specialist...

스키마: 스킬Copy Anchor Link

경로 패턴: src/apothem/skills/*/SKILL.md

목적: 탐지 신호와 실행 절차를 갖춘 재사용 가능한 기법 정의.

필수 필드Copy Anchor Link

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
---

선택 필드Copy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

예시Copy Anchor Link

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

스키마: 훅Copy Anchor Link

경로 패턴: settings.json의 hooks 블록과 src/apothem/hooks/ 아래의 Python 구현.

목적: 호스트가 명확히 정의된 라이프사이클 지점에서 호출하는 이벤트 트리거 검증기와 상태 관리 핸들러를 선언합니다.

설정 파일 스키마Copy Anchor Link

hooks 최상위 키는 이벤트 이름을 매처 블록의 배열에 매핑합니다.

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

-m apothem.hooks.dispatch 형식은 PYTHONPATH=src를 설정한 소스 체크아웃에서 개발할 때 사용합니다.

필수 이벤트Copy Anchor Link

Claude Code 템플릿은 SessionStart, PreToolUse, PostToolUse, Stop의 네 가지 이벤트를 등록합니다. scripts/dev/validate_hooks.py는 settings.json에서 아래 표의 다섯 가지 이벤트(앞의 네 가지와는 다른 집합)를 확인하고, 찾지 못한 각 이벤트를 실패가 아니라 경고로 보고합니다. PostToolUse는 등록되어 있지만 이 다섯 가지에 속하지 않습니다. PreCompact와 PostCompact는 이 다섯 가지에 속하지만 Claude Code에는 등록되어 있지 않으므로(훅 참조), 검사기는 Claude Code에서 이 둘에 대해 경고합니다.

타임아웃 값은 정식 훅 이벤트 예산을 그대로 따릅니다 — 아래 표는 독자의 편의를 위해 이를 재현한 것이며, 정식 출처가 우선합니다.

dispatch.py는 향후 호환성을 위해 이벤트 허용 목록에서 UserPromptSubmit과 Notification도 받아들입니다. 둘 다 배포되는 템플릿에는 연결되어 있지 않습니다. 활성화하려면 같은 exec 형식 패턴으로 매처 블록을 추가하세요.

Python 계층Copy Anchor Link

모든 훅 명령은 같은 Python 디스패처를 거칩니다.

검증Copy Anchor Link

scripts/dev/validate_hooks.py는 훅 계약을 강제합니다.

• settings.json이 JSON으로 파싱되고 표의 다섯 가지 이벤트를 각각 선언합니다. 누락된 이벤트는 실패가 아니라 경고입니다.
• 세 Python 스크립트가 모두 존재하고 유효한 Python으로 파싱됩니다.
• --context-file 인수가 참조하는 모든 메시지 파일이 존재합니다.
• 하드코딩된 절대 사용자 경로(C:\Users\... 등)가 src/apothem/hooks/**.py에 나타나지 않습니다.
• src/apothem/hooks/와 scripts/ 아래의 셸 아티팩트는 승인된 로케이터 / 부트스트랩 스텁으로 제한됩니다.

스키마: CLAUDE.mdCopy Anchor Link

경로: CLAUDE.md(루트)

목적: 프로젝트 범위의 Claude Code 지침.

필수 YAML 프런트매터Copy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

섹션Copy Anchor Link

CLAUDE.md는 산문 섹션으로 작성되며, CLAUDE.md에 설명되어 있습니다. 고정된 섹션 목록을 요구하는 검증기는 없습니다. scripts/dev/validate_ecosystem.py는 위의 프런트매터 키를 검사합니다.

검증 체크리스트Copy Anchor Link

모든 아티팩트는 다음 검사를 충족해야 합니다.

프런트매터 검증Copy Anchor Link

• YAML이 구문상 유효함(파싱 오류 없음)
• 아티팩트 타입의 모든 필수 필드가 있음
• name이 kebab-case 규약을 따름
• version이 시맨틱 버전임(MAJOR.MINOR.PATCH)
• updated가 ISO 8601 날짜 형식임(YYYY-MM-DD)
• description이 비어 있지 않은 한 줄 문자열임
• 선택 필드가 예상되는 enum 값과 일치함(해당하는 경우)
• 필드 이름에 오타가 없음(스키마의 정식 이름 사용)
• 불필요한 공백이나 서식 문제가 없음

콘텐츠 검증Copy Anchor Link

• 콘텐츠가 닫는 --- 뒤의 새 줄에서 시작하며, Markdown 계열 파일에서는 정식 SPDX 헤더 줄이 그 뒤의 첫 콘텐츠임
• 플랜 내부 참조가 없음(CM-7 준수)
• 상호 참조가 해석됨(다른 아티팩트를 나열하는 경우)
• 링크가 슬래시를 쓰는 상대 경로를 사용함

이식성 검증Copy Anchor Link

• 하드코딩된 절대 경로가 없음(상대 경로 사용)
• universal 범위 아티팩트에 Windows 전용 구문이 없음
• 경로 구분자로 슬래시를 사용함
• 환경 변수가 플랫폼 독립적 형식을 사용함(${VAR} 또는 도구 네이티브)

참고Copy Anchor Link

• 보안으로서의 일관성: 정식 프런트매터는 자동화된 검증, 도구화, 아티팩트 간 검증을 가능하게 합니다. 편차는 빠르게 누적됩니다.
• 이식성 선언: 모든 아티팩트가 범용 이식성을 가질 수는 없습니다. 제약을 명시적으로 선언하세요. 드러나지 않는 버그를 배포하는 것보다는 주의 사항을 문서화하는 편이 낫습니다.
• 이름에는 kebab-case: URL, 스크립트, 명령줄 맥락에서 쓰기 쉽습니다. 이름에는 공백, 밑줄, camelCase를 피하세요.
• 버전 올림 위생: 동작을 바꾸는 모든 편집은 version과 updated를 함께 올려야 합니다. 오타 수정, 링크 수정, 서식 변경은 버전을 바꾸지 않습니다. 새 선택 섹션이나 안티패턴은 MINOR를, 구조 재편이나 계약 변경은 MAJOR를 올립니다.