콘텐츠로 이동

ADR-0001: Auto-Load First

We will make auto-loading the default for all skills, minimizing explicit slash command invocations.

Status

Accepted

  • Decided at — 2026-04-15
  • Decided by — pabloism0x

Context

Claude Code 플러그인은 두 가지 방식으로 활성화된다: 사용자의 /skill-name 호출, 또는 Claude의 description 기반 자동 매칭. Bonie의 목표는 팀원이 skill 목록을 학습하지 않아도 전문 지식이 자동으로 적용되는 것이다. 사용자가 어떤 skill이 있는지 알고 직접 호출해야 한다면, skill이 많아질수록 학습 비용이 선형으로 증가한다.

Decision

자동 로드를 기본으로 한다.

  • Layer 3(Stack Skills)의 모든 skill은 user-invocable: false로 설정
  • description 기반 자동 매칭과 paths glob 기반 자동 로드를 활용
  • 명시적 호출(disable-model-invocation: true)은 Layer 1(Primitives)의 진입점에만:
  • /bonie:init — 프로젝트 초기화 (의도적 행위)
  • /todo:plan — 계획 수립 (의도적 행위)
  • 부작용이 있는 행위(파일 생성, 배포 등)는 반드시 사용자 직접 호출

Consequences

Positive

  • 팀원이 skill 목록을 외울 필요 없음
  • 관련 파일 작업 시 자동으로 전문 지식 활성화
  • 새 skill 추가 시 팀원에게 별도 안내 불필요

Negative

  • description과 paths 설계가 정밀해야 함 (잘못 매칭되면 불필요한 skill 로드)
  • skill description 총량이 컨텍스트 예산(context window의 1%)을 초과하지 않도록 관리 필요

Neutral

  • Claude Code의 "skills > commands" 설계 철학과 일치

Alternatives considered

Alternative 1: 모든 skill을 명시적 호출

Pros - 사용자가 어떤 지식이 적용되는지 완전히 통제

Cons - 수십 개의 skill을 외워야 함 - 새 skill 추가 시 팀 전체에 공지 필요

Why rejected — 팀원의 학습 비용이 skill 수에 비례하여 증가하므로 확장성이 없다.

Alternative 2: CLAUDE.md에 모든 지식 직접 작성

Pros - 구조가 단순, 항상 로드됨

Cons - CLAUDE.md가 비대해져 컨텍스트 소비 증가 - 스택별 지식이 불필요하게 항상 로드됨

Why rejected — 컨텍스트 효율성이 떨어지고, skill의 "필요 시에만 로드" 장점을 활용하지 못한다.

Compliance

  • 새 skill PR에서 disable-model-invocation: true 설정 여부를 리뷰 시 확인
  • L3 skill에 user-invocable: false 누락 시 CI lint (추후)

Revisit triggers

  • skill description 예산 초과로 매칭 정확도가 저하될 때
  • 팀원이 "왜 이 skill이 자동으로 적용되는지 모르겠다"고 반복 피드백할 때

References

  • ADR-0002 — Main-Bundle Structure (번들링 전략과 auto-load가 결합)