Superclaude Plusplus

SuperClaude++ v2.0

Claude Code를 위한 시스템 강제 개발 프레임워크 - 140개 스킬, 23개 에이전트, 16개 훅 타입으로 생산성과 코드 품질을 자동화합니다.

[](https://opensource.org/licenses/MIT)

About

SuperClaude++는 SuperClaude Framework를 기반으로 개인 사용에 맞게 확장한 프로젝트입니다. 원본 SuperClaude의 강력한 구조 위에 다양한 커뮤니티 베스트 프랙티스, 자동화 워크플로우, 전문가 에이전트 시스템을 통합하여 Claude Code의 잠재력을 최대한 끌어냅니다.

v2.0 패러다임 전환

v0.x: "Claude야, 이 규칙 읽고 따라줘"  (prompt-dependent)
v2.0: "시스템이 규칙을 강제한다"         (system-enforced)

v0.x에서는 CLAUDE.md에 규칙을 적어두고 Claude가 이를 읽고 따르기를 기대했습니다. v2.0에서는 skill-rules.json + settings.json 훅 시스템이 규칙 실행을 기계적으로 강제합니다. Circuit Breaker가 동일 에러 3회 반복을 자동 차단하고, Prompt Injection Scanner가 MCP 응답을 실시간 검사하며, Skill Matcher가 프롬프트 패턴에 따라 스킬을 자동 활성화합니다.

태그라인: Harness Engineering이 자기 자신에게 적용되는 프레임워크

Features

Core Framework

| 파일 | 설명 | |------|------| | CLAUDE.md | 엔트리 포인트 및 언어 설정 (한국어) | | FLAGS.md | 행동 플래그 시스템 (--think, --ultrathink, --uc 등) | | RULES.md | 개발 규칙 및 자동화 트리거 (Karpathy Guidelines + Harness Engineering 통합) | | PRINCIPLES.md | SOLID, DRY, KISS, YAGNI, Search Before Building 등 엔지니어링 원칙 | | MODES.md | 상황별 행동 모드 (Brainstorming, Orchestration, Harness, Token Efficiency 등) | | MCP_SERVERS.md | MCP 서버 통합 가이드 (Context7, Magic, Serena 등) | | CONTEXTS.md | DEV/REVIEW/RESEARCH/PLANNING 컨텍스트 모드 | | CONVENTIONS.md | 네이밍 컨벤션 + 패키지 관리 규칙 (uv/pnpm 필수) | | PATTERNS.md | 재사용 가능한 코드 패턴 모음 | | KNOWLEDGE.md | 축적된 인사이트 및 트러블슈팅 가이드 |

Agent System (23개)

v2.0에서 에이전트는 AGENT.md frontmatter로 정의됩니다. model, tools, maxTurns, effort, isolation 등의 속성을 선언적으로 지정하여, 에이전트 행동이 프롬프트 의존이 아닌 시스템 수준에서 제어됩니다.

# 예시: agents/backend-architect.md
---
name: backend-architect
model: opus
tools: Read, Grep, Glob, Write, Edit, Bash, WebFetch
disallowedTools: Agent
maxTurns: 20
effort: high
skills: [api-design, db-design, security-audit]
---

| Agent | 역할 | model | isolation | |-------|------|-------|-----------| | backend-architect | 백엔드 시스템 설계 | opus | - | | frontend-architect | UI/UX 및 프론트엔드 아키텍처 | sonnet | - | | system-architect | 시스템 아키텍처 설계 | opus | - | | security-engineer | 보안 취약점 분석 (Read-only) | opus | - | | performance-engineer | 성능 최적화 | sonnet | - | | quality-engineer | 테스트 및 QA | sonnet | - | | python-expert | Python 전문가 | sonnet | worktree | | refactoring-expert | 코드 리팩토링 | sonnet | worktree | | deep-research-agent | 심층 리서치 (WebFetch/WebSearch) | opus | - | | root-cause-analyst | 근본 원인 분석 (Read-only) | opus | - | | codebase-gc | 코드베이스 정리 (dead code, import, doc-code 동기화) | haiku | - | | pm-agent | 프로젝트 관리 | sonnet | - | | technical-writer | 기술 문서 작성 | sonnet | - | | requirements-analyst | 요구사항 분석 | sonnet | - | | devops-architect | DevOps 및 인프라 | sonnet | - | | learning-guide | 학습 가이드 | haiku | - | | socratic-mentor | 소크라틱 멘토 | sonnet | - | | business-panel-experts | 비즈니스 전략 분석 (9명의 전문가 패널) | opus | - | | generator | Generator+Validator 쌍 - 코드 생성 담당 | sonnet | worktree | | validator | Generator+Validator 쌍 - Read-only 검증 담당 | sonnet | - | | harness-worker | Harness Mode worktree 워커 | sonnet | worktree | | team-implementer | Agent Teams 구현 담당 | sonnet | worktree | | team-reviewer | Agent Teams 리뷰 담당 (Read-only) | opus | - |

Skills (140개)

모든 스킬은 skills/ 단일 디렉토리 아래 각각의 폴더에 SKILL.md로 정의됩니다. v0.x의 commands/ 디렉토리는 완전히 폐기되었으며, 모든 커맨드가 skills/로 통합되었습니다.

Core Skills

| Skill | 설명 | |-------|------| | /confidence-check | 구현 전 신뢰도 평가 (>=90% 필요) | | /verify | 완료 후 6단계 검증 체크리스트 + Dynamic Context Injection | | /checkpoint | 위험 작업 전 복원 지점 생성 | | /note | 컴팩션에서 살아남는 영구 메모 시스템 | | /learn | 재사용 가능한 패턴 추출 및 저장 | | /audit | 프로젝트 고유 규칙 검증 (비즈니스 로직, 아키텍처 패턴) | | /config-doctor | SuperClaude++ 설정 유효성 검증 (v2.0 신규) | | /goal | 자율 실행 루프 — 검증 가능한 종료 조건 충족 시까지 자동 반복 (Claude Code 빌트인, v2.2 통합) |

Development Skills

| Skill | 설명 | |-------|------| | /react-best-practices | React/Next.js 코드 리뷰 (40+ 규칙) | | /web-design-guidelines | Vercel UI/UX 리뷰 (100+ 규칙) + AI Slop Detection | | /composition-patterns | React Compound Components 패턴 | | /python-best-practices | Python 코드 리뷰 및 베스트 프랙티스 | | /pytest-runner | pytest 실행, 커버리지 분석 | | /uv-package | uv 패키지 관리 | | /feature-planner | 기능 구현 계획 수립 | | /gap-analysis | 설계-구현 비교, Match Rate 계산 | | /tdd | RED-GREEN-REFACTOR 주기 강제 + Git checkpoint | | /ui-ux-pro-max | AI 디자인 인텔리전스 (67 스타일, 96 팔레트, 57 폰트) + DESIGN.md 통합 | | /fix-pr | PR 코멘트 기반 자동 수정 (v2.0 신규) |

Impeccable Design Language (v2.1 신규, Apache 2.0)

pbakaus/impeccable v2.1.1 통합. "AI slop" 문제 — AI가 생성한 UI가 뻔한 AI 티를 내는 현상 — 을 해결하기 위한 디자인 어휘 시스템. 엔트리 skill + 17개 서브 커맨드.

| Skill | 설명 | |-------|------| | /impeccable [craft\|teach\|extract] | 엔트리. teach로 프로젝트 디자인 컨텍스트(audience/use case/brand tone)를 .impeccable.md에 고정. 나머지 커맨드의 전제조건 | | /shape | 레이아웃·아이디어·비주얼 방향 shape-then-build. craft 진입점 | | /layout | 공간·그리드·레이아웃 구조 설계 | | /typeset | 타이포그래피 (크기·행간·계층·페어링) | | /colorize | 컬러 팔레트·대비·테마 적용 | | /animate | 모션·트랜지션·인터랙션 피드백 | | /delight | 디테일·이스터에그·감성 포인트 | | /polish | 최종 다듬기 (normalize 흡수) | | /critique | UX 관점 정성 비평 (페르소나·휴리스틱·P0-P3 점수) | | /design-audit | 기술 품질 감사 (a11y·성능·테마·반응형·안티패턴, P0-P3 스코어) | | /harden | 엣지 케이스·에러 상태·접근성 강화 | | /optimize | 성능 최적화 (번들·렌더·이미지) | | /clarify | 정보 구조·UX writing 명료화 | | /distill | 군더더기 제거, 본질 추출 | | /quieter / /bolder | 시각적 강도 축소 / 강화 | | /adapt | 반응형·디바이스 적응 | | /overdrive | 맥시멀리즘·극한 대담함 모드 |

전제: /impeccable teach로 프로젝트 컨텍스트를 먼저 세팅해야 나머지 커맨드가 맥락에 맞게 동작. 기존 /frontend-design(Anthropic 원본)과 병렬 제공 — Impeccable이 그 계보의 확장판.

> 네임스페이스 주의: Impeccable 원본의 audit → SuperClaude++의 기존 /audit(프로젝트 룰 검증)과 충돌해 /design-audit으로 리네이밍됨. 저작권/라이선스는 NOTICE.md 및 skills/impeccable/{LICENSE,NOTICE.md} 참조.

Document Skills

| Skill | 설명 | |-------|------| | /docx | Word 문서 생성/편집 (OOXML 기반) | | /pdf | PDF 폼 처리 및 조작 | | /pptx | PowerPoint 프레젠테이션 생성 | | /xlsx | Excel 스프레드시트 처리 |

Domain Skills

• Architecture: /architecture, /api-design, /db-design, /design-patterns, /clean-arch, /hexagonal, /ddd, /cqrs
• Security: /security-audit (OWASP + STRIDE + LLM Security), /auth, /error-handling
• Performance: /perf-optimize, /caching, /scaling
• Frontend: /react-best-practices, /nextjs, /vue, /svelte, /remix, /responsive, /a11y, /seo, /state
• Backend: /fastapi, /nestjs, /graphql, /websocket, /queue, /pagination, /rate-limit
• DevOps: /docker, /cicd, /monitoring, /env, /logging, /backup
• Quality: /clean-code, /refactoring, /testing, /code-review, /code-smell, /naming, /solid
• Domain Modeling (MIT, mattpocock/skills): /grill-with-docs — 기존 도메인 모델에 대한 1대1 인터뷰 stress-test. 용어 충돌·코드 모순을 즉시 챌린지하고 CONTEXT.md(도메인 어휘 사전) / ADR을 인라인 갱신. /brainstorm이 새 기능 탐색이라면 이쪽은 기존 모델 검증. 부속 문서: [skills/grill-with-docs/CONTEXT-FORMAT.md](skills/grill-with-docs/CONTEXT-FORMAT.md), [skills/grill-with-docs/ADR-FORMAT.md](skills/grill-with-docs/ADR-FORMAT.md). 우리 프로젝트 자체의 어휘 사전 예시는 루트 [CONTEXT.md](CONTEXT.md). 출처 추적: [NOTICE.md](NOTICE.md).

> /brainstorm 보강 노트: grill-me 원본의 3대 행동 규칙(한 번에 한 질문 / 추천답 동반 / 코드 우선 탐색)이 기존 /brainstorm에 흡수되었습니다 (별도 스킬 미생성, 중복 방지).

Automation

Skill Auto-Activation (v2.0 핵심)

v2.0에서 스킬 자동 활성화는 .claude/skill-rules.json에 선언적으로 정의되고, scripts/skill-matcher.py가 UserPromptSubmit 훅으로 실행하여 프롬프트 패턴을 매칭합니다. Claude의 판단에 의존하던 v0.x와 달리, 기계적으로 트리거됩니다.

// .claude/skill-rules.json (발췌) — 57 rules, 332 triggers (200 Korean + 132 English)
{
  "skill": "build-fix",
  "mode": "auto",
  "triggers": {
    "prompt_patterns": [
      "error TS\\d+", "Build failed",
      "빌드 에러", "빌드 실패", "에러 났어", "안 돌아가"
    ],
    "exit_codes": [1]
  },
  "cooldown": 300
}

Auto-Invoke 스킬 (확인 없이 즉시 실행):

• build-fix - 빌드 에러 패턴 감지 시
• confidence-check - 구현 키워드 + 난이도 Medium 이상
• verify - 완료/커밋 키워드 감지 시
• checkpoint - 리팩토링/삭제 키워드 감지 시
• react-best-practices - .jsx/.tsx + 리뷰 키워드
• python-best-practices - .py + 리뷰 키워드
• debug - 테스트 실패 패턴 감지 시

Suggest 스킬 (확인 후 실행):

• tdd - 버그 수정 + tests/ 디렉토리 존재 시
• security-audit - 보안 관련 키워드/파일 패턴 감지 시
• code-smell - 50줄 이상 함수 감지 시

전체 규칙은 .claude/skill-rules.json 참조.

Proactive Suggestions

작업 컨텍스트에 맞는 스킬/에이전트/MCP 서버를 적극 제안 (확인 후 실행):

| 상황 | 제안 도구 | 트리거 조건 | |------|----------|-------------| | 복잡한 함수 | /code-review, /code-smell | 50줄+ 함수 | | API 설계 | /api-design, backend-architect | endpoint, REST | | 성능 이슈 | performance-engineer | 느림, slow, optimize | | 보안 관련 | security-engineer, /security-audit | 로그인, JWT, 보안, LLM 보안 | | 프레임워크 | Context7 MCP | React, Next.js, Vue | | UI 컴포넌트 | Magic MCP | button, form, modal | | 복잡한 분석 | Sequential MCP | 디버깅 3회+, 설계 | | 프로젝트 규칙 검증 | /audit | commit, PR + .claude/audit-rules/ 존재 시 | | 테스트 가능 기능 | /tdd | 새 기능 + tests/ 존재, 버그 수정 | | UI/UX 디자인 | /ui-ux-pro-max | landing page, 디자인 시스템 |

제안 강도 플래그: --suggest-all (기본) | --suggest-minimal | --suggest-off

Hook System (16개 타입)

config/settings.json에서 16개 훅 타입을 통해 자동화를 구성합니다.

| Hook Type | 역할 | |-----------|------| | UserPromptSubmit | 프롬프트 제출 시 skill-matcher 실행, 사전 노트 저장 | | PostToolUse | 파일 작성 후 타입 체크, 포맷팅, 컨벤션 체크, injection 스캔 | | PreToolUse | 편집 전 컴팩션 제안 | | Stop | TODO 미완료 방지, 세션 평가, circuit breaker | | SessionStart | 세션 시작 알림 | | SessionEnd | 세션 종료 알림 | | SubagentStart | 서브에이전트 시작 알림 | | SubagentStop | 서브에이전트 종료 + 결과 품질 게이트 | | TaskCompleted | 자동 Two-Stage Review 트리거 | | PreCompact | 컴팩션 전 상태 보존 | | Notification | 알림 이벤트 | | PermissionRequest | 권한 요청 이벤트 | | PostToolUseFailure | 도구 실행 실패 시 알림 | | FileChanged | .env 파일 등 민감 파일 변경 경고 | | ConfigChange | 설정 변경 시 유효성 검증 | | InstructionsLoaded | 프로젝트별 설정 자동 적용 |

v2.0 안전장치

| 기능 | 설명 | |------|------| | Circuit Breaker | 동일 에러 3회 반복 감지 시 자동 중단 + Architecture Alert (Stop 훅) | | Prompt Injection Scanner | MCP 응답에서 instruction injection, data exfiltration 패턴 스캔 (PostToolUse 훅) | | Skill Matcher | 프롬프트 패턴 기반 스킬 자동 활성화 (UserPromptSubmit 훅) | | Config Doctor | AGENT.md frontmatter, skill-rules.json, 훅 경로 유효성 검증 |

Sound Notifications (peon-ping)

peon-ping 연동으로 AI 코딩 에이전트 이벤트를 게임 캐릭터 음성으로 알림합니다.

| 기능 | 설명 | |------|------| | 오디오 알림 | 작업 완료, 에러, 입력 요청 시 게임 캐릭터 보이스 재생 | | 데스크톱 오버레이 | macOS JXA 기반 화면 상단 배너 (멀티스크린 지원) | | 모바일 푸시 | ntfy.sh / Pushover / Telegram 연동 | | MCP 서버 | Claude가 대화 중 play_sound tool로 직접 사운드 재생 |

설치된 사운드 팩: Orc Peon, Human Peasant, GLaDOS (Portal), Sarah Kerrigan (StarCraft), Battlecruiser

Quick controls:

peon toggle           # 음소거/해제
peon volume 0.7       # 볼륨 조절
peon packs use glados # 팩 변경
/peon-ping-toggle     # Claude Code 내에서 토글

Flags & Modes

Analysis Depth

| Flag | 토큰 | 용도 | |------|------|------| | --think | ~4K | 중간 복잡도 | | --think-hard | ~10K | 아키텍처 분석 | | --ultrathink | ~32K | 시스템 재설계 |

MCP Server Flags

| Flag | 서버 | 용도 | |------|------|------| | --c7 | Context7 | 공식 문서 조회 | | --magic | Magic | UI 컴포넌트 생성 | | --seq | Sequential | 다단계 추론 | | --serena | Serena | 시맨틱 코드 이해 | | --tavily | Tavily | 웹 검색/리서치 |

Context Modes

| Flag | 모드 | 특성 | |------|------|------| | --ctx dev | 개발 | 작동 > 완벽, 코드 먼저 | | --ctx review | 리뷰 | 심층 분석, 심각도별 정리 | | --ctx research | 리서치 | 완전성 > 속도, 증거 기반 |

Harness Mode

| Flag | 용도 | |------|------| | --harness | 에이전트 주도 구현 (5-Phase: Intent - Scaffold - Implement - Verify - Deliver) | | --harness --orchestrate | 병렬 에이전트 최대 활용 | | --harness --safe-mode | 모든 Phase에서 사용자 확인 (/goal 비호환) | | --harness + /goal | DELIVER 조건을 검증 가능한 명령으로 표현, 자율 루프 활성화 (v2.2 신규, 상세: optional/GOAL_PATTERNS.md) |

Proactive Suggestion Flags

| Flag | 설명 | |------|------| | --suggest-all | 모든 관련 도구 적극 제안 (기본값) | | --suggest-minimal | 핵심 도구만 제안 | | --suggest-off | 자동 제안 비활성화 | | --auto-agent | 에이전트 자동 제안 활성화 | | --auto-mcp | MCP 서버 자동 활성화 제안 |

Installation

Plugin Install (권장)

/plugin install github:excatt/superclaude-plusplus

Claude Code 내에서 위 명령어를 실행하면 plugin.json 매니페스트에 따라 스킬, 에이전트, 훅, 스크립트가 자동 설치됩니다.

Manual Install

git clone https://github.com/excatt/superclaude-plusplus.git
cd superclaude-plusplus
scripts/sync-global.sh

설치 후

1. Claude Code 재시작 - 변경 사항 적용
2. /config-doctor - 설정 유효성 검증
3. /note --show - 노트 시스템 확인
4. 기존 settings.json이 있었다면 hooks 설정 병합 필요

Directory Structure

superclaude-plusplus/                # 프로젝트 저장소 (source of truth)
├── plugin.json                     # Plugin manifest (v2.0 설치 진입점)
├── CLAUDE.md                       # 메인 엔트리 포인트
├── FLAGS.md                        # 플래그 시스템
├── RULES.md                        # 행동 규칙
├── PRINCIPLES.md                   # 엔지니어링 원칙
├── MODES.md                        # 행동 모드
├── MCP_SERVERS.md                  # MCP 서버 가이드
├── CONTEXTS.md                     # 컨텍스트 모드
├── CONVENTIONS.md                  # 네이밍 컨벤션
├── PATTERNS.md                     # 코드 패턴
├── KNOWLEDGE.md                    # 인사이트/트러블슈팅
├── notepad.md                      # 영구 메모
├── skills/                         # 140개 스킬 (각각 SKILL.md)
│   ├── confidence-check/SKILL.md
│   ├── verify/SKILL.md
│   ├── tdd/SKILL.md
│   ├── config-doctor/SKILL.md      # v2.0 신규
│   ├── fix-pr/SKILL.md             # v2.0 신규
│   ├── ui-ux-pro-max/              # AI 디자인 인텔리전스 (BM25 검색)
│   ├── web-design-guidelines/      # UI/UX 리뷰
│   ├── impeccable/                 # Impeccable Design Language 엔트리 (+ 17 서브)
│   ├── grill-with-docs/            # v2.3 신규 (도메인 stress-test, MIT)
│   └── ...                         # 140개 스킬 디렉토리
├── agents/                         # 23개 에이전트 (AGENT.md frontmatter)
│   ├── backend-architect.md
│   ├── generator.md                # v2.0 신규 (Generator+Validator)
│   ├── validator.md                # v2.0 신규 (Generator+Validator)
│   ├── harness-worker.md           # v2.0 신규 (Worktree 워커)
│   ├── team-implementer.md         # v2.0 신규 (Agent Teams)
│   ├── team-reviewer.md            # v2.0 신규 (Agent Teams)
│   └── ...                         # 23개 에이전트 정의
├── scripts/                        # 17개 자동화 스크립트
│   ├── skill-matcher.py            # v2.0: UserPromptSubmit hook 핸들러
│   ├── circuit-breaker.sh          # v2.0: 에러 반복 자동 차단
│   ├── injection-scanner.py        # v2.0: MCP injection 방어
│   ├── statusline.sh               # 상태바 스크립트
│   ├── checklist.sh                # 프로젝트 검증 (P0-P4)
│   ├── convention-check.sh         # 네이밍 컨벤션 자동 체크
│   ├── type-check.sh               # 타입 체크
│   ├── auto-format.sh              # 자동 포맷팅
│   ├── session-summary.py          # 세션 요약 자동 생성
│   └── ...                         # 17개 스크립트
├── config/                         # 설정 파일
│   ├── settings.json               # 16개 hook 타입 + 권한 + MCP 설정
│   └── peon-ping.json              # peon-ping 설정 (포터블)
├── .claude/                        # Claude Code 내부 설정
│   ├── skill-rules.json            # v2.0: 스킬 자동 활성화 규칙
│   ├── settings.local.json         # 로컬 설정 오버라이드
│   ├── context.md                  # 프로젝트 컨텍스트
│   └── state/                      # 세션 상태 저장
├── optional/                       # 25개 선택적 로딩 문서
│   ├── MCP_*.md                    # MCP 서버별 상세 가이드 (7개)
│   ├── MODE_*.md                   # MODE별 상세 가이드 (8개)
│   ├── BUSINESS_PANEL_EXAMPLES.md  # 비즈니스 패널 예제
│   ├── BUSINESS_SYMBOLS.md         # 비즈니스 심볼
│   ├── REASONING_TEMPLATES.md      # 구조화된 추론 템플릿
│   ├── CONTEXT_BUDGET.md           # 컨텍스트 예산 관리
│   ├── WORKER_TEMPLATES.md         # 워커 에이전트 프롬프트 템플릿
│   ├── GOAL_PATTERNS.md            # v2.2 신규: /goal 조건 패턴, 안티 패턴, /loop vs /goal 결정표
│   └── ...                         # 25개 문서
├── docs/
│   └── PLAN-v2.0.md                # v2.0 마이그레이션 계획
└── templates/                      # PDCA + 디자인 시스템 템플릿
    ├── plan.template.md
    ├── design.template.md
    ├

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [excatt](https://github.com/excatt)
- **Source:** [excatt/superclaude-plusplus](https://github.com/excatt/superclaude-plusplus)
- **License:** MIT

Install and usage instructions live in the source repository linked above.