2026년 Mac mini ECC(Everything Claude Code) 설치 가이드
/plugin install ecc@ecc, 또는 (B) ./install.sh --profile minimal --target claude(훅 없는 기준선). 둘을 겹치면 안 됩니다. 중복은 상류 문서에서도 가장 흔한 지원 이슈입니다.
Mac mini에 ECC를 설치하는 이유
Claude Code는 macOS에서 안정적인 SSH, 빠른 NVMe, 상시 가동과 잘 맞습니다. 많은 팀이 노트북 절전 모드에 묶이지 않고 전용 Mac mini M4를 렌탈해 ECC를 올립니다.
- 지속적인
~/.claude상태 — 하네스를 서버에 두면 스킬·훅·규칙이 로컬 재부팅 후에도 유지됩니다 - Anthropic API 저지연 — 서울 노드에서 RTT 약 24ms. 리전이 맞지 않으면 180ms 이상도 나올 수 있습니다(리전 매트릭스)
- 16GB면 충분 — ECC + Claude Code CLI. OpenClaw나 무거운 Docker 사이드카까지 쓰면 24GB를 권장합니다
ECC는 Claude Code를 대체하지 않고 그 위의 설정·워크플로 레이어입니다. 246개 스킬이 필요 없다면 먼저 Claude Code 무료 대안을 보세요.
ECC 아키텍처: 무엇이 설치되는가
ECC(저장소 affaan-m/ECC, npm: ecc-universal)는 하네스별 디렉터리에 설치됩니다. macOS Claude Code 기준:
| 구성 요소 | 목적 | 설치 후 일반 경로 |
|---|---|---|
| 플러그인 번들 | 마켓플레이스를 통한 스킬·명령·훅 | Claude Code 플러그인 호스트가 로드 |
| Rules | 언어·프레임워크 코딩 표준 | ~/.claude/rules/ecc/common/, ~/.claude/rules/ecc/typescript/ 등 |
| Agents | 전문 서브에이전트 정의 | 플러그인 관리 또는 ~/.claude/agents/(프로필에 따름) |
| 훅 런타임 | SessionStart/Stop 자동화, 메모리 | ECC_HOOK_PROFILE=minimal|standard|strict |
| State store | SQLite 설치 추적, ecc doctor |
인스톨러에 따라 프로젝트 또는 사용자 범위 |
헷갈리지 말 3가지 공개 식별자:
- GitHub:
affaan-m/ECC - Claude 마켓플레이스 플러그인:
ecc@ecc - npm CLI:
ecc-universal/npx ecc-install
상류 경고: /plugin install + ./install.sh --profile full = 스킬 중복과 깨진 훅. 아래에서 경로 하나만 고르세요.
외부 참고: Anthropic Claude Code 문서.
Mac mini 사전 요구사항
설치 전 확인:
# macOS 14+ 권장(M4에서 Sequoia 검증)
sw_vers
# Node.js 20 LTS(ECC 스크립트 최소 18+)
node -v # v20.x 또는 v22.x 기대
npm -v
# Git
git --version
# Claude Code CLI(없으면 별도 설치)
claude --version
새 KuzCloud 노드에서는 Homebrew로 Node 설치:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node git
디스크 약 2GB(클론 + node_modules), 훅 유휴 시 RAM 약 500MB, Claude Code 본체도 가늠하세요. 첫 ECC 세팅·평가는 3~7일 버스트로 충분한 경우가 많습니다.
Mac mini에 ECC 설치: 8단계 런북
1단계 — SSH 접속 및 워크스페이스 생성
ssh -i ~/.ssh/kuzcloud.pem user@YOUR_NODE_IP
mkdir -p ~/ecc-lab && cd ~/ecc-lab
자격 증명은 주문 후 약 5분 내에 오는 경우가 많습니다. 다른 원격 Mac 가이드와 동일한 흐름입니다.
2단계 — ECC 저장소 클론
git clone https://github.com/affaan-m/ECC.git
cd ECC
git checkout main # 또는 v2.0.0-rc.1 등 태그 고정
3단계 — Node 의존성 설치
npm install
# 대안: pnpm install | yarn install | bun install
훅 어댑터와 인스톨러 스크립트를 받습니다. 첫 실행은 대역에 따라 3~8분 걸릴 수 있습니다.
4단계 — 설치 경로 하나만 선택
경로 A — Claude Code 플러그인(대부분의 사용자)
Mac mini에서 대화형 Claude Code 세션 안에서:
/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc
필요한 규칙 팩만 복사합니다(플러그인이 규칙을 자동 배포하지 않음):
mkdir -p ~/.claude/rules/ecc
cp -R rules/common ~/.claude/rules/ecc/
cp -R rules/typescript ~/.claude/rules/ecc/ # TS 미사용 시 생략
경로 A 이후 ./install.sh --profile full는 실행하지 마세요.
경로 B — 수동 minimal(훅 없음, 오버헤드 최소)
./install.sh --profile minimal --target claude
동일:
npx ecc-install --profile minimal --target claude
16GB 노드에서 훅이 과하거나 규칙+에이전트만 원할 때 적합합니다.
경로 C — 수동 full(파워 유저만)
./install.sh --profile full --target claude
경로 C를 택했다면 /plugin install ecc@ecc와 함께 쓰지 마세요.
5단계 —(선택) 추가 모듈 전 consult
npx ecc consult "security reviews typescript" --target claude
미리보기를 검토한 뒤 범위를 좁혀 설치합니다.
npx ecc install --profile minimal --target claude --with capability:machine-learning
6단계 — 설치 상태 검증
node scripts/ecc.js list-installed
node scripts/ecc.js doctor
node scripts/ecc.js repair # doctor 이슈 시 안전한 1차 복구
기대 결과: doctor가 중복 훅 등록 없이 설치된 프로필을 보고합니다.
7단계 — 훅 프로필 설정(경로 A 또는 full만)
export ECC_HOOK_PROFILE=standard # 또는 minimal | strict
export ECC_DISABLED_HOOKS= # 비활성화할 훅을 쉼표로
Mac mini의 ~/.zshrc에 추가해 SSH 세션 간에 유지합니다.
8단계 — ECC와 함께 Claude Code 스모크 테스트
cd ~/ecc-lab/sample-project # 본인 저장소
claude
세션 내 패키지 명령 예:
/harness-audit
또는 "ECC 스킬로 이 README의 토큰 과다 구간을 검토해줘"처럼 요청해도 됩니다.
경로 비교표
| 경로 | 명령 | 훅 | 적합한 경우 |
|---|---|---|---|
| A — 플러그인 | /plugin install ecc@ecc |
예(플러그인 경유) | 매일 Claude Code, 가장 빠른 온보딩 |
| B — Minimal | ./install.sh --profile minimal |
아니오 | 16GB RAM, CI 바스티온, 규칙만 |
| C — Full 수동 | ./install.sh --profile full |
예 | 에어갭·마켓플레이스 차단 환경 |
| Core(훅 제외) | --profile core --without baseline:hooks |
아니오 | 훅 켜기 전 중간 단계 |
권장: KuzCloud Mac mini를 ECC+Claude Code 전용으로 쓴다면 경로 A + rules/common만으로 시작하고 언어 팩은 점진적으로 추가하세요. 훅은 먼저 ECC_HOOK_PROFILE=minimal로 일주일 안정화 후 필요 시 standard로 올리세요.
문제 해결
오류: 스킬/명령이 두 번 실행됨
증상: 같은 슬래시 명령이 두 번; SessionStart 로그가 이중.
원인: 플러그인 + full install.sh 중첩.
조치:
node scripts/ecc.js doctor
# ECC README "Reset / Uninstall ECC" 안내 따르기
# 이후 경로 하나만으로 재설치
오류: 원격 Mac에서 claude: command not found
증상: 플러그인 명령 실패; claude --version 없음.
조치:
npm install -g @anthropic-ai/claude-code
# 또는 https://docs.anthropic.com/en/docs/claude-code/setup
export ANTHROPIC_API_KEY=sk-ant-...
재접속 후 4단계를 반복합니다.
오류: 마켓플레이스에서 ecc@ecc를 찾을 수 없음
증상: /plugin install ecc@ecc가 이름 해석에 실패.
조치: 경로 A를 건너뛰고 경로 B:
cd ~/ecc-lab/ECC && ./install.sh --profile minimal --target claude
오류: npm install 중 Node OOM
증상: 16GB Mac mini에서 Killed: 9.
조치: 임시 스왑 추가 또는 24GB 노드로 업그레이드; 상류가 지원하면 npm install --omit=dev.
Mac mini에서 ECC: 렌탈 vs 구매
ECC는 Apple Silicon GPU를 요구하지 않습니다. Node 20과 여유 디스크 약 10GB면 충분합니다. 월 22일 만근 미만으로 쓰면 $599+ 구매보다 렌탈이 유리한 경우가 많습니다(렌탈 vs 구매 가이드).
FAQ
ECC는 Claude Code와 같나요?
아니요. Claude Code는 Anthropic의 에이전트형 코딩 CLI이고, ECC는 github.com/affaan-m/ECC에서 유지되는 커뮤니티 하네스 확장 팩(스킬·규칙·훅)입니다. 먼저 Claude Code(또는 지원되는 다른 하네스)가 필요합니다.
Claude Code 없이 Cursor에 ECC를 설치할 수 있나요?
예. ECC는 Cursor, Codex, OpenCode 등을 --target cursor(또는 하네스별 인스톨러)로 지원합니다. 본 가이드는 KuzCloud에서 가장 흔한 Mac mini의 Claude Code 워크로드에 초점을 맞춥니다.
ECC가 코드를 제3자에게 전송하나요?
ECC는 로컬 규칙·훅·스킬을 추가합니다. LLM 호출은 하네스가 쓰는 모델 공급자(Anthropic, OpenAI 등)를 통합니다. 프로덕션 저장소 전에 ECC Security Guide를 검토하고 /security-scan(AgentShield)을 실행하세요.
ECC를 완전히 제거하려면?
상류 Reset / Uninstall ECC 절을 따릅니다. node scripts/ecc.js repair/list 명령을 실행하고, ~/.claude/rules/ecc/를 제거하며, Claude Code에서 플러그인을 제거하고, doctor가 가리키는 중복 스킬 폴더를 삭제합니다.
노트북에서 SSH로 ECC를 쓸 수 있나요?
예. 원격 Mac mini에 ECC를 설치하고 tmux나 screen에서 claude를 실행한 뒤 노트북에서 SSH로 붙습니다. ECC Tk 대시보드(npm run dashboard)를 로컬 GUI로 볼 때만 포트 포워딩이 필요할 수 있습니다.