superclaude-plusplus

SuperClaude++ v3.4

Claude Code를 위한 harness-aware 개발 프레임워크 - 44개 스킬, 9개 에이전트, 4개 훅 이벤트 + mod 1개. 모델이 스스로 알 수 없는 것만 문서로 남기고, 사람의 기억에 의존하던 규칙은 훅으로 강제합니다.

왜 이 프레임워크인가

Claude 5 세대 모델과 Claude Code 하네스는 검증 후 완료 선언, 지속 실행, 스코프 절제, 병렬 도구 호출, 세션 메모리, 응답 언어 같은 것을 이미 보장합니다. 이런 것을 CLAUDE.md에 다시 적는 건 컨텍스트만 차지하는 순비용입니다. SuperClaude++는 세 가지만 다룹니다.

프로세스 지식(모드, 플래그, 추론 템플릿, MCP 가이드)은 optional/ 25개 문서와 스킬로 내려가 필요할 때만 로드됩니다. Claude Code가 자체 번들하는 스킬(docx/pdf/pptx/xlsx, skill-creator, mcp-builder, 디자인 자산류)과 내장 명령(/code-review /simplify /security-review /loop /memory)은 여기서 다시 배포하지 않습니다. 이 원칙이 어떻게 자리 잡았는지는 CHANGELOG의 v2.0(시스템 강제)·v3.0(harness-aware slim)·v3.4(플러그인화) 항목에 있습니다.

빠른 시작

설치

이 저장소는 Claude Code 공식 플러그인입니다(.claude-plugin/plugin.json + 자체 마켓플레이스).

# 1. 플러그인 (스킬·에이전트·훅·mod)
/plugin install superclaude-plusplus --marketplace excatt/superclaude-plusplus

# 2. 플러그인이 설치할 수 없는 것 (상시 로드 .md, optional/, settings 병합, 상태바)
git clone https://github.com/excatt/superclaude-plusplus.git
cd superclaude-plusplus
scripts/sync-global.sh --dry-run   # 무엇이 바뀌는지 먼저 확인
scripts/sync-global.sh

이 체크아웃을 그대로 쓰려면 1번 대신 폴더를 마켓플레이스로 등록합니다. 폴더 소스 플러그인은 복사본이 아니라 폴더에서 직접 읽히므로, 편집 후 /reload-plugins만 하면 됩니다.

claude plugin marketplace add /path/to/superclaude-plusplus
/plugin install superclaude-plusplus@superclaude-plusplus

sync-global.sh는 CLAUDE.md 등 5개 .md, optional/, skill-rules.json(fallback), scripts/statusline.sh만 ~/.claude/로 복사하고 settings.json은 병합합니다. v3.3 이전이 ~/.claude/skills|agents|scripts에 복사해 둔 것과 ~/.claude/scripts/를 가리키는 settings 훅은 플러그인과 두 번 실행되지 않도록 제거합니다.

설치 후

1. Claude Code 재시작. enabledPlugins에 선언된 플러그인이 업스트림에서 설치됩니다.
2. /config-doctor 로 설정 정합성 확인.
3. LSP 플러그인용 바이너리 설치: ``bash pnpm add -g pyright typescript typescript-language-server ``

함께 켜지는 플러그인 (참조 선언, 코드 미포함)

출처와 검토 후 미채택한 플러그인은 NOTICE.md에 있습니다.

작업 흐름

모든 구현 요청은 아래 순서를 따릅니다. 난이도에 따라 단계가 생략됩니다.

Step 0  난이도 평가 (Simple / Medium / Complex)
   │
   ├─ Medium+  /confidence-check ─ 90% 미만이면 조사 후 재평가
   │
   ▼
구현 ── 훅이 편집마다 컨벤션·console.log·보안 패턴 체크
   │
   ▼
Two-Stage Review ── Stage 1 스펙 준수 → Stage 2 코드 품질(내장 /code-review) → (Complex) Stage 3 연쇄 영향
   │
   ▼
/verify → /audit ── 빌드·테스트·프로젝트 규칙
   │
   ▼
/learn ── 재사용 패턴 추출 (선택)

검증 가능한 종료 조건이 있는 멀티턴 작업은 /goal "<조건>"로 자율 루프를 돕습니다. 약한 조건("잘 되게 해줘")은 절대 /goal에 넘기지 않습니다. 패턴은 optional/GOAL_PATTERNS.md.

구성 요소

상시 로드 문서 (5개)

응답 언어 자체는 config/settings.json의 language 설정이 하네스 수준에서 강제합니다. 플러그인은 CLAUDE.md를 프로젝트 컨텍스트로 로드하지 않으므로 이 5개는 sync-global.sh가 ~/.claude/에 둡니다.

Skills (44개)

스킬 메타데이터는 idle에도 컨텍스트에 상주하므로, 모델이 이미 할 수 있는 것과 Claude Code가 이미 번들하는 것은 스킬로 두지 않습니다. 남은 기준은 네 가지입니다. 기계 장치나 데이터를 가진 것, 프레임워크 워크플로우의 코어, 검증된 큐레이션 콘텐츠, 출처가 추적되는 서드파티 스킬.

/sc-help가 전체 목록을 보여줍니다. 플러그인 스킬의 정식 이름은 superclaude-plusplus:<name>이고, 다른 명령과 겹치지 않으면 /<name>만으로도 호출됩니다. 겹치면 기존 명령이 이깁니다 — help를 sc-help로 바꾼 이유입니다(/help는 Claude Code 자체 명령).

Agents (9개)

에이전트는 frontmatter로 model, tools, maxTurns, effort, isolation을 선언합니다. 범용 페르소나(architect, frontend 등)는 하네스의 general-purpose 에이전트와 model 오버라이드로 대체 가능해 두지 않았습니다. 남은 것은 프레임워크 배선에 연결되어 있거나 고유한 실행 구성을 가진 것입니다.

Hooks (4개 이벤트, 10개 훅) + mod

훅은 플러그인의 hooks/hooks.json에 선언되고 ${CLAUDE_PLUGIN_ROOT}/scripts/*를 실행합니다. 모든 스크립트는 Claude Code의 훅 계약을 따릅니다. stdin으로 이벤트 JSON을 받고, hookSpecificOutput.additionalContext(컨텍스트 주입) 또는 decision: block(Stop 차단)으로 응답합니다. 상태 파일은 전부 ~/.claude/state/에 두고 프로젝트 디렉토리에는 아무것도 쓰지 않습니다. 공통 파서는 scripts/lib/hook-common.sh(jq → python3 폴백), 계약 테스트는 tests/hooks/run.sh.

mod (hooks/register.ts, Claude Code function hooks). 프롬프트가 아니라 엔진이 직접 적용하는 훅입니다. claude plugin validate .가 매니페스트와 모듈을 검사하고 claude plugin test .가 hooks/register.test.ts를 엔진 위에서 실행합니다.

스킬 자동 활성화 규칙 (.claude/skill-rules.json, 발췌):

{
  "skill": "python-best-practices",
  "mode": "auto",                       // auto: 즉시 실행 | suggest: 확인 후 실행
  "triggers": {
    "prompt_patterns": ["(리뷰|review|검토).*(python|파이썬|\\.py\\b)"],  // 대상 언어를 함께 언급할 때만
    "file_patterns": ["*.py"]           // 프로젝트에 해당 파일이 있을 때만
  },
  "cooldown": 600                        // 같은 스킬 재발동 간격(초)
}

auto 10개: build-fix confidence-check verify checkpoint audit brainstorm react-best-practices python-best-practices pytest-runner web-design-guidelines. suggest 13개: tdd security-audit feature-planner learn impeccable ui-ux-pro-max 등. auto 활성화는 세션당 15회로 제한되고, suggest는 제한이 없습니다. 제안 강도는 --suggest-all(기본) --suggest-minimal --suggest-off로 조절합니다.

Modes & Flags

--think --think-hard --ultrathink는 extended thinking이 상시 켜진 뒤로 토큰 예산이 아니라 노력 수준 힌트입니다. 상황 모드는 --ctx dev|review|research. 전체 정의는 optional/FLAGS.md.

MCP 서버는 번들되지 않습니다. --c7 --seq --magic --serena --tavily 플래그는 해당 서버가 프로젝트나 머신에 설치돼 있을 때만 의미가 있고, 미설치 시 폴백 (WebFetch, --think-hard, /frontend-design, Grep, WebSearch)은 optional/MCP_SERVERS.md에 있습니다.

핵심 개념

Build Ladder (PRINCIPLES.md). 무언가를 만들기 전에 8단을 순서대로 묻고 첫 번째로 해당하는 단에서 멈춥니다. 0 존재할 필요가 있는가 → 1 이 코드베이스에 이미 있는가 → 2 stdlib → 3 플랫폼 네이티브 → 4 설치된 의존성 → 5 검증된 라이브러리 → 6 신흥 라이브러리 → 7 직접 구현. 디버깅에는 적용하지 않습니다(최소 diff 편향이 증상 패치를 만듭니다). 사례 카탈로그는 optional/OVERENGINEERING_TRAPS.md.

Circuit Breaker (RULES.md, circuit-breaker.sh). 같은 에러가 3회 반복되면 수정을 멈추고 아키텍처 리뷰와 Agent Struggle Report(Task, 시도, 실패 분류, 권고)를 씁니다. 분류는 Repo Gap / Architecture / External / Requirement / Capability. 자동 수정은 하지 않고 사용자가 결정합니다.

Two-Stage Review (RULES.md). 리뷰어 원칙은 "구현자의 보고를 믿지 않는다". Stage 1은 요구사항 대비 누락과 과잉을, Stage 2는 코드 품질(내장 /code-review로 수행, 80% 미만 확신은 Minor로 강등)을, Complex 난이도에서만 Stage 3이 변경된 심볼의 호출부와 전체 테스트를 확인합니다.

Harness Engineering (PRINCIPLES.md). 저장소 자체가 도메인 지식의 단일 원천이어야 합니다. 의존 방향은 Types → Config → Domain → Service → Runtime → UI 단방향. 에이전트가 실패하면 저장소에 부족한 것(도구, 가드레일, 타입, 문서)을 진단하되 자동으로 고치지는 않습니다. codebase-gc 에이전트가 주기적으로 엔트로피를 점검합니다.

PDCA (RULES.md, templates/). Plan → Design → Do → Check → Act → Report. /gap-analysis가 설계 문서와 구현을 비교해 Match Rate를 내고, 90% 미만이면 Act로 돌아갑니다(최대 5회). 산출물은 docs/01-plan ~ docs/04-report.

DESIGN.md. 디자인 에이전트가 읽는 시각 디자인 시스템 문서(Google Stitch 포맷). npx getdesign@latest add {brand}로 66개 브랜드 중 가져오거나 /ui-ux-pro-max --design-system --persist로 생성합니다. 파이프라인은 DESIGN.md → /ui-ux-pro-max → /frontend-design → /web-design-guidelines. 템플릿은 templates/visual-design.template.md.

Memory. Claude Code 내장 Auto Memory(~/.claude/projects/<slug>/memory/, /memory)가 단일 메모리입니다. 이 프레임워크는 session-summary.py로 마지막 세션 요약을 같은 디렉토리에 둘 뿐이고, 프로젝트 간 재사용 패턴만 /learn이 ~/.claude/skills/<name>/SKILL.md로 꺼냅니다. v3.3까지 있던 /note 노트패드와 컴팩션 전 메모 훅은 하네스가 컴팩션 요약을 직접 보존하므로 제거했습니다. 저장 기준은 skills/learn/SKILL.md, 레이아웃은 optional/PROTOCOLS.md.

패키지 관리. Python은 uv, Node.js는 pnpm만 허용합니다. requirements.txt, poetry.lock, package-lock.json, yarn.lock이 보이면 마이그레이션을 제안합니다. Dockerfile·CI 패턴은 CONVENTIONS.md와 optional/PROJECT_RULES.md.

커스터마이즈

변경 후 bash scripts/lint.sh로 검증하고, 폴더 마켓플레이스로 설치했다면 /reload-plugins, .md·settings를 바꿨다면 scripts/sync-global.sh.

검증

이 저장소는 자기 자신의 정합성을 기계적으로 검사합니다. 문서의 개수·버전이 실제와 어긋나거나, 훅이 존재하지 않는 스크립트를 가리키면 CI가 실패합니다.

bash scripts/config-doctor.sh   # 에이전트/스킬 frontmatter, skill-rules 참조, hooks.json 경로·${CLAUDE_PLUGIN_ROOT}·
                                #   timeout 단위, 버전·개수 정합, 문서 참조, 심볼릭 링크, bash -n/py_compile/shellcheck,
                                #   claude plugin validate
bash tests/hooks/run.sh         # 실제 이벤트 JSON 픽스처로 훅 계약 검증 (23건, jq 없이도 통과)
python3 -m unittest tests/test_skill_matcher.py   # glob·지연 순회·세션 상한·쿨다운·로그 고정 경로 (12건)
claude plugin test .            # mod 테스트 (hooks/register.test.ts, 엔진 위에서 실행)
bash scripts/lint.sh            # 위 전부 + shellcheck = .github/workflows/ci.yml과 동일

/config-doctor 스킬이 첫 번째 스크립트를 실행합니다.

디렉토리 구조

superclaude-plusplus/
├── .claude-plugin/
│   ├── plugin.json                # 공식 플러그인 매니페스트
│   └── marketplace.json           # 이 저장소 자체가 마켓플레이스 (source: ./)
├── hooks/
│   ├── hooks.json                 # 셸 훅 10개 (${CLAUDE_PLUGIN_ROOT}/scripts/*) + modules: register.ts
│   ├── register.ts                # mod: attribution.text(commit) 제거, session.start 토스트
│   └── register.test.ts           # claude plugin test
├── CLAUDE.md  RULES.md  PRINCIPLES.md  MODES.md  CONVENTIONS.md   # 상시 로드 (sync-global이 ~/.claude로)
├── CONTEXT.md                     # 도메인 어휘 사전 (/grill-with-docs가 갱신)
├── NOTICE.md                      # 서드파티 출처·라이선스·미채택 사유
├── CHANGELOG.md
├── config/settings.json           # 권한, statusLine, language, Agent Teams env, 플러그인 선언 (훅 없음)
├── .claude/skill-rules.json       # 스킬 자동 활성화 규칙 23개
├── skills/                        # 44개 (각 SKILL.md)
├── agents/                        # 9개 (frontmatter: model, tools, maxTurns, effort, isolation)
├── scripts/
│   ├── lib/hook-common.sh         # 훅 공통: stdin 파싱, additionalContext / decision:block 출력
│   ├── skill-matcher.py           # UserPromptSubmit
│   ├── console-log-check.sh  auto-format.sh  convention-check.sh   # PostToolUse (Edit|Write)
│   ├── injection-scanner.py       # PostToolUse (mcp__*)
│   ├── todo-continuation.sh  circuit-breaker.sh  evaluate-session.sh  session-summary.py   # Stop
│   ├── config-doctor.sh           # 정합성 진단
│   ├── lint.sh                    # 로컬 CI
│   ├── sync-global.sh             # 플러그인이 못 하는 부분 → ~/.claude
│   └── statusline.sh              # 상태바
├── tests/
│   ├── hooks/run.sh  hooks/fixtures/*.json
│   └── test_skill_matcher.py
├── optional/                      # 25개 온디맨드 문서
│   ├── FLAGS.md  CONTEXTS.md  GOAL_PATTERNS.md  OVERENGINEERING_TRAPS.md
│   ├── REASONING_TEMPLATES.md  WORKER_TEMPLATES.md  PROTOCOLS.md  PROJECT_RULES.md
│   ├── MODE_*.md (8)              # 모드별 상세
│   ├── MCP_SERVERS.md  MCP_*.md (7)   # MCP 선택 매트릭스, 서버별 가이드, 미설치 폴백
│   └── BUSINESS_PANEL_EXAMPLES.md
├── templates/                     # PDCA 4종, visual-design
└── .github/workflows/ci.yml

요구사항

• Claude Code CLI 2.1.290 이상 (function hooks attribution.text, claude plugin test). /goal은 2.1.139, security-guidance는 2.1.144 이상
• Claude 구독 또는 Anthropic API 키
• Python 3.9 이상 (skill-matcher.py, injection-scanner.py, session-summary.py, 훅의 jq 폴백)
• jq (선택. 없으면 python3 폴백)
• pnpm (LSP 바이너리 설치용), shellcheck (선택. lint.sh)

업데이트 / 삭제

# 업데이트
/plugin update superclaude-plusplus@superclaude-plusplus   # 플러그인 (폴더 마켓플레이스면 /reload-plugins)
git pull && scripts/sync-global.sh                         # .md / optional / settings

# 삭제
/plugin uninstall superclaude-plusplus@superclaude-plusplus
rm -f  ~/.claude/{CLAUDE,RULES,PRINCIPLES,MODES,CONVENTIONS}.md ~/.claude/skill-rules.json ~/.claude/scripts/statusline.sh
rm -rf ~/.claude/optional
# ~/.claude/settings.json의 statusLine·enabledPlugins 항목은 직접 정리

~/.claude 전체를 지우면 메모리·세션·개인 설정까지 사라지니 위처럼 선택 삭제하세요.

버전 히스토리

상세는 CHANGELOG.md.

출처

이 프로젝트는 SuperClaude Framework를 기반으로 개인 사용에 맞게 확장한 것입니다. 벤더링한 스킬과 차용한 개념의 라이선스·출처· 미채택 사유는 NOTICE.md가 단일 원천이며, 아래는 요약입니다.

License

MIT License - see LICENSE.