Component Model¶

Claude Code의 5가지 확장 메커니즘(skills, agents, hooks, rules, commands)을 Bonie가 어떻게 활용하는지 정의한다.

Why this structure¶

Claude Code는 여러 확장 메커니즘을 제공하지만 각각의 용도가 다르다. 잘못된 메커니즘을 선택하면 자동 로드가 안 되거나, 불필요하게 컨텍스트를 소비하거나, 사용자 경험이 나빠진다. 컴포넌트 선택 기준을 명확히 하여 일관된 설계를 보장한다.

System view¶

flowchart LR
    subgraph Session["Claude Code Session"]
        Context["Context\n(대화)"]
        Tools["Tools"]
        Skills["Skills\n(지식)"]
        Agents["Agents\n(위임)"]
        Hooks["Hooks\n(강제)"]
        Rules["Rules\n(제약)"]

        Context -- "자동 매칭" --> Skills
        Context -- "자동 위임" --> Agents
        Tools -- "이벤트" --> Hooks
        Rules -. "항상 로드" .-> Context
        Context --> Tools
    end

Components¶

Skills¶

Responsibility — 상황별 전문 지식, 절차적 가이드, 반복 작업 자동화
Inputs — description 매칭, paths glob, 사용자 호출
Outputs — SKILL.md 내용이 컨텍스트에 주입
Dependencies — 없음 (독립적)

SKILL.md frontmatter 주요 필드:

Field	Description	Bonie 활용
`description`	자동 매칭 키워드 (1,536자 제한)	핵심 키워드 front-load
`disable-model-invocation`	`true`: 사용자만 호출	L1 진입점 (`/bonie:init`)
`user-invocable`	`false`: Claude만 호출	L3 자동 지식 로드
`paths`	파일 매칭 glob	확장자/경로 기반 로드
`context: fork`	subagent에서 실행	독립 작업
`allowed-tools`	권한 사전 승인	도구 제한

Agents¶

Responsibility — 독립 컨텍스트에서 전문화된 작업 수행
Inputs — Claude 자동 위임 (description 기반)
Outputs — 작업 결과 요약을 메인 컨텍스트에 반환
Dependencies — 없음 (독립 컨텍스트)

Agent frontmatter 주요 필드:

Field	Description	Bonie 활용
`description`	자동 위임 트리거	"Use proactively." 포함
`model`	sonnet, opus, haiku, inherit	L4: opus, L3: sonnet
`memory`	user, project, local	L4: `project`
`tools` / `disallowedTools`	도구 제한	최소 권한 원칙

Plugin agent 제약: hooks, mcpServers, permissionMode 미지원.

Hooks¶

Responsibility — 이벤트 기반 강제 실행
Inputs — Claude Code lifecycle 이벤트
Outputs — 스크립트 실행 결과 (exit code로 차단/허용)
Dependencies — 이벤트 소스 (도구 호출, 세션 상태 등)

Bonie 활용 이벤트:

Event	Matcher	Purpose
`SessionStart`	`startup\\|resume`	TODO.md 상태 로드, session.json 초기화
`PostToolUse`	`Write\\|Edit`	TODO.md task 완료 감지
`PreToolUse`	`Bash`	위험 명령 차단
`Stop`	—	statusline 진행률 갱신
`FileChanged`	`TODO.md`	진행 상태 재계산

Exit code: 0=성공, 2=블로킹(도구 차단), 기타=경고만

Rules¶

Responsibility — 항상 적용되는 제약과 가이드라인
Inputs — .claude/rules/ 디렉토리의 markdown
Outputs — 세션 컨텍스트에 규칙 주입
Dependencies — .claude/ 구조

하위 분류: - guides/ — 팀 공통 강제 규칙 (code-style, git-convention, mcp-required) - project/ — 프로젝트별 동적 규칙 (anti-patterns, directory-structure, conventions)

Commands¶

.claude/commands/ 파일은 skill의 단축 진입점으로 사용한다. /start, /bonie, /todo, /git 커맨드가 여기에 위치하며, 각각 대응하는 plugin skill을 호출한다.

Interactions¶

컴포넌트 선택 가이드¶

flowchart TD
    Start["새 기능 추가"] --> Q1{"항상 적용?"}
    Q1 -- Yes --> Rules["rules/"]
    Q1 -- No --> Q2{"이벤트 반응?"}
    Q2 -- Yes --> Hooks["hooks/"]
    Q2 -- No --> Q3{"독립 컨텍스트 필요?"}
    Q3 -- Yes --> Agents["agents/"]
    Q3 -- No --> Q4{"사용자 직접 호출?"}
    Q4 -- Yes --> SkillManual["skills/\n(disable-model-invocation: true)"]
    Q4 -- No --> SkillAuto["skills/\n(auto-loaded)"]

Trade-offs¶

Benefit	Cost
각 메커니즘의 용도가 명확	올바른 메커니즘 선택에 판단 필요
auto-load로 사용자 부담 최소	description/paths 설계 정밀도 요구
agent 독립 컨텍스트로 메인 보존	agent 호출 latency 발생

Constraints¶

skill description + when_to_use 합계 1,536자 제한
skill 전체 description 예산은 context window의 1%
plugin agent는 hooks, mcpServers, permissionMode 미지원
hook script는 반드시 실행 권한 필요 (chmod +x)