배포 체크리스트

Apothem 에코시스템을 새 머신에 배포하거나, 다른 사람과 공유하거나, 프로덕션 준비 완료로 취급하기 전의 사전 검증 단계입니다.

1. YAML 유효성Copy Anchor Link

• 모든 규칙 파일이 YAML 오류 없이 파싱됨 — frontmatter 블록이 ---로 열리고 ---로 닫히며 블록 외부에 고립된 콘텐츠가 없음
• 모든 위임 작업자 파일이 YAML 오류 없이 파싱됨
• 모든 명령 파일이 YAML 오류 없이 파싱됨
• 모든 스킬 SKILL.md 파일이 YAML 오류 없이 파싱됨

검증: python scripts/dev/validate_ecosystem.py는 각 아티팩트의 frontmatter를 파싱하고 YAML 오류 + 누락된 필수 필드를 표시합니다. 즉석으로 고립된 목록 항목을 감지하려면: rg -n "^- " src/apothem/rules/*.md.

2. frontmatter 완전성Copy Anchor Link

각 아티팩트 유형에 대해 필수 필드가 존재하는지 확인하세요:

규칙 (src/apothem/rules/*.md)Copy Anchor Link

• name — 파일 이름과 일치하는 kebab-case 식별자
• description — 한 문장 요약
• alwaysApply — 항상 적용되는 규칙은 true, 경로 필터링 규칙은 false
• pathFilter — 모든 규칙에 있어야 합니다. 항상 적용되는 규칙(alwaysApply: true)에서는 "", 경로 필터링 규칙(alwaysApply: false)에서는 쉼표로 구분된 glob 목록입니다.

규칙은 version, updated, scope, portability 키를 포함하지 않습니다.

명령 (src/apothem/commands/*.md)Copy Anchor Link

• name — kebab-case 명령 이름
• version, updated, description, argument-hint, portability, allowed-tools 존재
• disable-model-invocation 존재하며 의도적임 (읽기 전용 또는 자문 명령의 경우 false, 명령 실행이 작업 트리 밖의 상태를 변경하거나 운영자가 시점을 선택하는 데 의존하는 경우에만 true)
• effort 키는 없어야 합니다: command.schema.json은 additionalProperties: false를 설정하며 이를 허용하지 않습니다.

위임 작업자Copy Anchor Link

경로:

src/apothem/agents/*.md

• name, version, updated, description 존재
• tools — 허용된 도구의 쉼표로 구분된 목록
• disallowedTools — 허용되지 않은 도구를 명시적으로 나열
• maxTurns — 설정됨(10을 넘으면 근거 주석 포함)
• permissionMode — "bypassPermissions"이면 안 됨. 이 키는 설정하지 않은 상태로 둡니다. 중립 태세가 권한 모드를 미리 지정하지 않기 때문입니다.
• memory — 영속 메모리를 의도한 경우가 아니라면 생략합니다. 설정하는 경우에는 user, project, local 중 하나여야 합니다(불리언 형식은 없음).

스킬 (src/apothem/skills/*/SKILL.md)Copy Anchor Link

• name, version, updated, description, archetype, disable-model-invocation, allowed-tools 존재
• userInvocable 선언됨(true/false). 소스 표기는 userInvocable이며, 스킬은 userInvocable 또는 user-invocable(Claude Code 표기) 중 정확히 하나만 가집니다.

3. 보안Copy Anchor Link

• 어떤 위임 작업자도 permissionMode: "bypassPermissions"를 사용하지 않음 — 이것은 Write/Bash 작업에 대한 대화형 확인을 우회함
• 작업자의 tools 목록은 최소한임 — 작업자가 정말로 필요로 하는 도구만 포함
• Bash 액세스를 가진 작업자는 정당화되었으며 maxTurns 제한이 있음
• 어떤 아티팩트에도 하드코딩된 경로, 토큰 또는 시크릿이 없음
• settings.json의 훅은 합리적인 타임아웃(≤ 60초)을 가지며 사용자 입력으로부터 임의의 코드를 실행하지 않음

4. 상호 참조 무결성Copy Anchor Link

• src/apothem/rules/ 테이블에 나열된 모든 규칙이 명시된 경로에 디스크에 존재함
• src/apothem/commands/ 테이블에 나열된 모든 명령이 디스크에 존재함
• src/apothem/agents/ 레지스트리 테이블에 나열된 모든 위임 작업자가 디스크에 존재함
• src/apothem/skills/ 테이블에 나열된 모든 스킬이 디스크에 존재함
• src/apothem/hooks/ 테이블의 모든 훅이 settings.json에 해당 항목을 가짐
• 모든 src/apothem/rules/*.md 파일이 존재하고 각 파일의 Bindings 상호 참조가 해석됨

5. 지령 커버리지Copy Anchor Link

• 모든 CM-N 지령이 시행 위치를 가짐 (규칙 파일 또는 명시적 인라인 정의)
• 어떤 규칙 파일도 다른 규칙 파일과 모순되지 않음 (특히 심각도 스케일링 주변에서)
• CM-21 3측면 구분이 존중됨 — 어떤 규칙도 다른 규칙의 CM-21 측면 소유권을 주장하지 않음

6. 기능 스모크 테스트Copy Anchor Link

먼저 Python 검증 표면을 실행하세요 — 빠르고 오프라인이며 구조적 회귀를 잡아냅니다:

• pytest tests — 훅 런타임의 단위 테스트, 모두 그린
• python scripts/dev/validate_hooks.py — 훅 구조 + Python 전용 위생 검사 통과
• python scripts/dev/validate_ecosystem.py — 전체 트리 + frontmatter + 위임 훅 검사 통과
• python scripts/dev/chaos_pass.py — 구성된 각 훅 명령이 저하된 입력 하에서 유효한 JSON 봉투를 반환함

그다음 라이브 시나리오:

• /plan-spec <sample-file> — 명령 수준 오류 없이 수집 및 명확화를 완료함
• /plan-generate --dry-run — 파일을 쓰지 않고 구조 미리보기를 생성함
• 완성된 플랜 스위트에 대한 /plan-status — 정확한 페이즈 수를 반환함
• 위임된 워커 디스패치: 작은 범위로 호출된 codebase-explorer 워커가 maxTurns 내에 완료되고 구조화된 출력을 반환함

7. 문서 최신성Copy Anchor Link

• CHANGELOG.md(에코시스템 루트)가 마지막 릴리스 이후의 모든 아티팩트 변경을 반영함; 다음 릴리스의 섹션이 태그가 안착하기 전에 채워졌거나, 모든 변경이 이미 릴리스된 섹션으로 분류됨
• site/content/docs/developer-guide.mdx가 현재 아티팩트 구조를 정확하게 기술함
• site/content/docs/reference/artifact-schema.mdx가 아티팩트에 실제로 존재하는 frontmatter 필드와 일치함
• site/content/docs/reference/settings-reference.mdx가 settings.json의 실제 훅 구성과 일치함
• README.md가 디스크상의 트리와 일관됨

8. 이식성 (다른 사람과 공유하는 경우)Copy Anchor Link

• 훅 명령의 모든 경로가 환경에 구애받지 않거나 ~ 확장을 사용함
• 훅 명령이 exec 형식을 사용하고 셸별 명령 문자열을 피함
• 어떤 아티팩트에도 하드코딩된 C:\Users\username 또는 /home/username 경로가 없음
• settings.json이 단일 훅 이벤트 커버리지 테이블과 표준 디스패치 모듈 경로를 사용함

9. 버전 정렬Copy Anchor Link

• CLAUDE.md version이 트리 내 어떤 아티팩트보다 가장 높음 (또는 관례상 가장 최근에 버전이 올라간 아티팩트의 버전과 같음)
• 각 아티팩트의 version이 명시된 semver(MAJOR.MINOR.PATCH)와 일치함
• CHANGELOG.md가 태깅 전에 정확히 대상 버전의 릴리스 항목을 포함함
• 각 아티팩트의 updated 필드가 마지막 동작 변경 편집 날짜이거나 그 이후임
• 어떤 아티팩트도 마지막으로 손댄 버전보다 낮은 version을 갖지 않음 (회귀 없음)
• src/apothem/skills/plan-suite/SKILL.md와 src/apothem/skills/plan-suite/master-template.md가 동일한 템플릿 버전 라인에 고정됨

승인Copy Anchor Link

배포 승인자: ___________________ 날짜: ___________________ 배포된 에코시스템 버전: ___________________