Claude Code ECC 플러그인 설치 및 룰팩 설정 방법

Claude Code는 개발자의 로컬 터미널 환경에서 코드베이스를 탐색하고 수정 작업을 직접 보조하는 Anthropic의 공식 CLI 기반 코딩 에이전트 도구입니다. ECC(affaan-m/ECC)는 이러한 에이전트 환경에서 일관된 엔지니어링 표준을 유지할 수 있도록 테스트 주도 개발(TDD), 체계적인 코드 리뷰, 보안 감사 규칙, 그리고 전후 처리용 훅(Hooks)을 제공하는 오픈소스 프레임워크입니다.

두 도구를 결합하면 Claude Code가 프로젝트의 코딩 컨벤션과 아키텍처 지침을 스스로 준수하며 작업을 진행하도록 환경을 구성할 수 있습니다. 하지만 설치 과정에서 공식 내장 플러그인 명령어와 저장소의 수동 셸 스크립트 실행이 중복되거나, 플러그인 번들에서 자체 제공되지 않는 코딩 규칙 팩(Rule packs)을 로컬에 배치하는 방법을 혼동하여 설정 오류를 겪는 경우가 빈번합니다. 이 글에서는 단일 설치 경로를 유지하면서 ECC 네이티브 플러그인을 활성화하고, 필수 룰팩을 올바른 디렉터리 구조로 배치하는 공인 설정 절차를 구체적으로 다룹니다.

Claude Code와 ECC의 역할 관계 및 사전 이해

Claude Code와 ECC를 연동할 때 가장 먼저 이해해야 하는 핵심 원칙은 플랫폼과 확장 구성 요소 간의 경계입니다. Claude Code는 사용자 터미널에서 입력된 명령을 받아 모델 API와 상호작용하고 파일 시스템 및 셸 도구를 호출하는 호스트 하네스(Harness) 역할을 수행합니다. 반면 ECC는 해당 하네스 위에서 작동하는 서브에이전트 역할 정의, 전문 스킬(Skills), 라이프사이클 이벤트 훅, 그리고 프로젝트 코딩 표준(Rules)을 공급하는 플러그인 패키지입니다.

여기서 중요한 구조적 제약이 있습니다. Claude Code의 네이티브 플러그인 시스템은 스킬, 에이전트, 내장 커맨드, 플러그인 전용 훅을 자동으로 하네스에 등록하지만, 코딩 규칙 모음인 룰팩(rules)은 플러그인 시스템을 통해 자체 배포되지 않습니다. 따라서 플러그인을 정상 설치하더라도 언어별 코딩 가이드라인과 공통 엔지니어링 표준이 자동으로 적용되지 않으며, 별도의 규칙 디렉터리 구성 작업이 반드시 수반되어야 합니다.

또한 설치 경로는 크게 두 갈래로 나뉩니다. Claude Code 대화창 내에서 직접 실행하는 네이티브 /plugin 경로와 로컬 터미널에서 구동하는 Node/Shell 기반 설치 스크립트(install.sh) 경로입니다. 동일한 Claude Code 하네스에 이 두 가지 방식을 겹쳐서 설치하면 스킬과 훅, 설정 항목이 이중으로 적재되어 심각한 충돌을 일으킵니다. 따라서 공식 권장 사항에 따라 네이티브 플러그인 경로를 기본으로 삼고, 추가 셸 전체 설치를 실행하지 않는 원칙을 준수해야 합니다.

Claude Code CLI 내부 명령어로 ECC 네이티브 플러그인 설치하기

Claude Code 터미널 환경에서 플러그인 설치 명령어를 입력하는 개발자 작업 환경 — Claude Code CLI 환경에서 내장 /plugin 명령을 통한 네이티브 플러그인 등록

Claude Code 환경에서 ECC를 가장 안전하게 활성화하는 공식 경로는 CLI 세션 내부의 내장 플러그인 명령어를 이용하는 것입니다. Claude Code를 구동한 후 대화창에서 마켓플레이스 등록과 플러그인 설치 명령을 순서대로 입력합니다.

/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

이 내장 명령어를 적용하는 구체적인 실행 단계는 다음과 같습니다.

터미널에서 claude를 입력하여 Claude Code 세션을 시작합니다.
프롬프트 입력창에 /plugin marketplace add https://github.com/affaan-m/ECC를 입력하고 엔터를 눌러 ECC 저장소를 신규 마켓플레이스로 등록합니다.
등록이 확인되면 /plugin install ecc@ecc를 입력하여 ECC의 네이티브 플러그인 번들을 설치합니다.

명령이 정상 처리되면 Claude Code는 마켓플레이스 매니페스트를 해석하여 ecc@ecc에 정의된 에이전트 프롬프트, TDD 및 코드 리뷰 스킬, 플러그인 관리형 훅을 즉시 활성화합니다.

설정 파일(settings.json)을 통한 선언적 등록 방법

CLI 입력창에서 매번 명령을 실행하는 대신 개발 환경의 형상 관리나 일관된 배포를 선호한다면, 사용자 홈 디렉터리의 ~/.claude/settings.json 파일에 마켓플레이스와 플러그인 항목을 선언적으로 직접 등록할 수 있습니다. 이 구성은 위의 두 내장 /plugin 명령어를 실행한 것과 완전히 동일한 설치 상태를 보장합니다.

{
  "extraKnownMarketplaces": {
    "ecc": {
      "source": {
        "source": "github",
        "repo": "affaan-m/ECC"
      }
    }
  },
  "enabledPlugins": {
    "ecc@ecc": true
  }
}

이 선언적 방식을 적용할 때는 ~/.claude/settings.json 파일을 열어 extraKnownMarketplaces 객체 아래에 GitHub 저장소 경로를 명시하고, enabledPlugins에서 ecc@ecc를 true로 지정합니다. 파일을 저장한 후에는 실행 중이던 Claude Code 세션을 완전히 종료하고 다시 시작해야 설정 변경 사항이 온전히 반영됩니다.

수동 전체 설치 금지와 룰팩(Rules) 디렉터리 배치 규칙

계층 구조를 유지하며 정리된 규칙 디렉터리 구조 화면 — 상대 경로 참조 보존을 위해 디렉터리 단위로 배치해야 하는 ECC 룰팩 구조

동일 하네스에 플러그인과 셸 전체 프로필이 동시에 설치되면 동일한 스킬과 슬래시 커맨드, 훅 트리거가 중복 등록됩니다. 이로 인해 Claude Code 실행 중 툴 호출 인터셉트가 이중으로 발생하거나 알 수 없는 내부 에러가 유발될 수 있습니다. 훅 스크립트 런타임만을 별도로 관리해야 하는 특수한 상황(bash ./install.sh --target claude --modules hooks-runtime --enable-hooks)이 아니라면 전체 설치 스크립트는 실행하지 않아야 합니다.

규칙(Rules)과 스킬(Skills)의 구조적 차이

ECC 내부에서 규칙과 스킬은 서로 다른 계층의 역할을 수행합니다. 규칙(Rules)은 “80% 이상의 테스트 커버리지 유지”, “하드코딩된 시크릿 금지”와 같이 에이전트의 모든 개발 행동에 상시 적용되는 코딩 표준, 컨벤션, 체크리스트를 정의합니다. 반면 스킬(Skills)은 특정 언어나 작업 단위(예: Python 디자인 패턴 적용, Go 단위 테스트 작성)를 만났을 때 호출되는 심층적이고 실행 가능한 참조 지침입니다. 규칙이 ‘무엇을 지켜야 하는가’를 규정한다면, 스킬은 ‘어떻게 구현할 것인가’를 안내합니다.

디렉터리 계층 보존 및 평탄화 복사 금지 원칙

Claude Code 플러그인은 룰팩을 포함하지 않으므로, 개발자는 ECC 공식 저장소를 클론한 뒤 필요한 언어 팩만을 선별하여 복사해야 합니다. 이때 가장 주의해야 할 사항은 와일드카드(/*)를 사용해 하위 파일을 하나의 디렉터리로 평탄화(Flatten)하여 복사해서는 안 된다는 점입니다.

ECC의 규칙 디렉터리 구조를 살펴보면 rules/common/과 언어별 디렉터리(rules/typescript/, rules/python/ 등)는 모두 coding-style.md, testing.md, patterns.md와 같이 동일한 파일명을 사용하고 있습니다. 언어별 규칙 파일 상단에는 > This file extends [common/xxx.md](../common/xxx.md) with <Language> specific content.와 같은 상대 경로 상속 선언이 포함되어 있습니다. 따라서 파일을 평탄화하여 한 폴더에 복사하면 언어별 파일이 공통 규칙 파일을 덮어써 버리고 상대 경로 링크가 파괴됩니다.

올바른 룰팩 배치를 위해서는 반드시 전용 네임스페이스인 ~/.claude/rules/ecc를 생성하고 디렉터리 단위(-R)로 복사해야 합니다.

# 1. ECC 공식 저장소 클론 및 디렉터리 이동
git clone https://github.com/affaan-m/ECC.git
cd ECC

# 2. 사용자 전역 ECC 전용 규칙 네임스페이스 디렉터리 생성
mkdir -p ~/.claude/rules/ecc

# 3. 모든 프로젝트에 공통 적용되는 기본 규칙 복사 (필수)
cp -R rules/common ~/.claude/rules/ecc/

# 4. 실제 프로젝트 스택에 필요한 언어 팩만 디렉터리 단위로 복사
cp -R rules/typescript ~/.claude/rules/ecc/

만약 사용하는 기술 스택이 파이썬이나 고랭이라면 위 명령어의 마지막 줄을 cp -R rules/python ~/.claude/rules/ecc/ 또는 cp -R rules/golang ~/.claude/rules/ecc/로 대체합니다. 항상 공통 원칙을 담은 rules/common을 먼저 복사하고, 실제로 다루는 언어 팩만 추가하는 것이 원칙입니다.

전역 홈 디렉터리가 아닌 특정 프로젝트 저장소에만 규칙을 한정하고 싶다면 프로젝트 루트에서 동일한 네임스페이스 경로를 생성하여 적용할 수 있습니다.

mkdir -p .claude/rules/ecc
cp -r rules/common .claude/rules/ecc/
cp -r rules/typescript .claude/rules/ecc/

설치 확인 및 충돌 방지: /ecc:configure-ecc와 정상 작동 점검

플러그인 활성화와 룰팩 복사를 마친 후에는 시스템이 올바르게 구성되었는지 단계별로 점검해야 합니다.

Claude Code 세션 재시작: 기존 터미널 세션을 종료하고 새 터미널 창에서 claude를 실행합니다.
설정 재구성 스킬 실행: 프롬프트 창에 /ecc:configure-ecc 명령어를 입력합니다.
정상 응답 확인: ECC 고유의 대화형 설정 인터페이스가 호출되어 현재 활성화된 하네스 프로필과 설정을 안내하는지 확인합니다.
룰팩 참조 동작 확인: 코드 작성 또는 리팩토링 요청 시 Claude Code가 ~/.claude/rules/ecc/ 내의 공통 가이드라인 및 언어별 코딩 스타일 지침을 바탕으로 응답하는지 점검합니다.

여기서 중요한 작동 제약은 /ecc:configure-ecc 명령어가 플러그인이 이미 설치된 이후에만 로드되는 네임스페이스 기반 스킬이라는 점입니다. 이 명령어는 최초 설치 단계에서 사용되는 내장 /plugin 명령어를 대신할 수 없습니다. 이미 설치된 상태에서 환경 설정을 안전하게 재구성하거나 프로필을 점검할 때 위임되어 동작하는 보조 도구입니다.

대표적인 실패 원인과 문제 해결

설치 및 운영 과정에서 발생할 수 있는 주요 장애 상황과 공식 대처 방안은 다음과 같습니다.

1. 마켓플레이스 중복 등록 또는 스코프 충돌 에러
내장 /plugin marketplace add 또는 /plugin install 실행 시 이미 존재하는 마켓플레이스나 스코프 충돌(conflicting scope) 메시지가 출력될 수 있습니다. 이는 Claude Code 내장 파서가 직접 감지하고 반환하는 시스템 에러입니다. ECC 플러그인은 호스트 CLI 파서의 동작을 가로챌 수 없습니다. 이러한 에러가 발생했을 때 셸 스크립트(install.sh)를 덧씌워 강제 설치하려고 시도하면 설정이 더욱 꼬이게 됩니다. 충돌 메시지가 나타나면 기존 플러그인 스코프를 먼저 정리하거나 ~/.claude/settings.json 파일의 중복 항목을 제거한 후 다시 시도해야 합니다.

2. 훅(Hooks) 설정 변경 시 미반영 문제
settings.json이나 훅 설정 파일을 수정한 후 변경 사항이 실시간으로 적용되지 않는 증상이 발생할 수 있습니다. Claude Code는 실행 중인 세션 내에서 훅 변경 사항을 즉각 핫 리로드(Hot-reload)하지 않습니다. 훅 동작 방식을 수정했다면 반드시 Claude Code 세션을 완전히 종료하고 재시작해야 새로운 훅 바이너리가 적재됩니다.

3. 보안 감사 실행 시 사이버 세이프가드 차단 에러
ECC의 보안 검토 에이전트(ecc:security-reviewer) 또는 /security-scan을 실행할 때 자신의 코드베이스를 감사함에도 불구하고 API 에러와 함께 사용 정책 위반(Cyber-related safeguards) 경고가 발생할 수 있습니다. 이는 ECC 내부의 차단이 아니라 Anthropic의 업스트림 모델 수준 세이프가드가 작동한 결과입니다. 이 경우 계정 토큰 링크를 통해 Anthropic의 Cyber Verification Program에 승인을 신청하여 차단을 해제할 수 있습니다. 승인 전까지는 악용 목적의 표현(PoC 생성 등)을 피하고, “보안 취약점 점검 및 코드 개선”과 같이 방어적이고 명확한 개선 목적으로 프롬프트를 구성하여 개별 모듈 단위로 스캔을 진행하는 것이 권장됩니다.