# cc-agents-kit

위험한 명령 점검부터 세션 인수인계, 커밋 전 확인까지. 지금 반복해서 겪는 문제를 고르면 필요한 도구와 작동 예시를 볼 수 있습니다.

[플러그인 소스 · 4a8947c3110459730e5c91eb75f7ecfe620be394](https://github.com/AndrewDongminYoo/cc-agents-kit/tree/4a8947c3110459730e5c91eb75f7ecfe620be394) · [Apache-2.0 라이선스](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/LICENSE) · [크레딧](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/CREDITS.md)

- 3 플러그인
- 11 워크플로 스킬
- 8 방어용 훅

## guard-hooks

Claude Code의 도구 호출을 방어용 훅 여덟 개가 점검합니다. 다섯 개는 위험한 명령 형태를 실행 전에 차단하며, 두 개는 편집 후 경고를 추가하고, 한 개는 Bash 출력에서 자격 증명으로 보이는 값을 가립니다.

명령, 비밀 정보, 저장소 변경을 훅으로 점검합니다.

기존 훅이 같은 항목을 점검한다면 다른 가드를 추가하기 전에 규칙, 동작, 의존성을 비교하세요.

### dangerous-command-guard

되돌리기 어려운 명령을 실행 직전에 점검합니다.

이런 상황에서: Claude Code가 홈 디렉터리를 재귀 삭제하거나, 다운로드한 내용을 셸로 바로 실행하려고 합니다.

도구가 하는 일: 알려진 위험 명령 형태에 해당하면 실행 전에 차단합니다.

주의사항을 기억하는 데만 의존하지 않고 도구 호출 시점에 검사합니다. 패턴 검사이므로 의도적으로 우회한 명령까지 막지는 못합니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/guard-hooks/hooks/dangerous-command-guard.sh)

### zsh-quoting-guard

따옴표 실수로 명령의 뜻이 바뀌는 일을 점검합니다.

이런 상황에서: find 명령에 따옴표 없는 파일명 글로브가 들어갑니다.

도구가 하는 일: 명령을 차단하고 글로브를 따옴표로 감싸도록 안내합니다.

알려진 zsh 인용 오류를 검사합니다. 따옴표로 감싼 heredoc을 만나면 이후 내용의 검사는 중단합니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/guard-hooks/hooks/zsh-quoting-guard.sh)

### pathless-rewriter-guard

포맷터가 바꿀 파일의 범위를 먼저 정합니다.

이런 상황에서: Claude Code가 대상 경로 없이 포맷터의 파일 쓰기 명령을 실행하려고 합니다.

도구가 하는 일: 파일 경로나 따옴표로 감싼 글로브를 지정할 때까지 차단합니다.

등록된 재작성 명령을 점검합니다. 별칭이나 패키지 스크립트 안에 숨은 명령까지 모두 추적하지는 않습니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/guard-hooks/hooks/pathless-rewriter-guard.sh)

### staged-secret-guard

커밋에 들어갈 비밀 정보 패턴을 확인합니다.

이런 상황에서: 스테이징된 추가 내용에 알려진 자격 증명 패턴이 있는 상태에서 커밋을 요청합니다.

도구가 하는 일: 커밋을 차단해 스테이징된 내용을 수정할 기회를 줍니다.

커밋에 추가될 내용에서 확실한 패턴을 찾습니다. 모든 형태의 비밀 정보를 탐지하는 범용 스캐너는 아닙니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/guard-hooks/hooks/staged-secret-guard.sh)

### secrets-path-guard

실제 비밀 정보 파일에 대한 도구 접근을 막습니다.

이런 상황에서: Claude Code가 실제 자격 증명을 담은 파일에 접근하려고 합니다.

도구가 하는 일: 알려진 비밀 정보 경로의 접근은 차단하고, 지원하는 예시 파일은 읽을 수 있게 둡니다.

비밀 정보 경로를 패턴으로 검사합니다. 설명문에 적힌 경로도 검사에 걸릴 수 있습니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/guard-hooks/hooks/secrets-path-guard.sh)

### lockfile-drift-check

의존성 목록만 바꾸고 잠금 파일을 놓쳤는지 알립니다.

이런 상황에서: package.json을 수정한 뒤 해당 잠금 파일을 다시 생성하지 않았습니다.

도구가 하는 일: 편집 후 잠금 파일이 함께 갱신됐는지 확인하라는 경고를 추가합니다.

편집 후 알려주는 점검입니다. 편집을 차단하거나 잠금 파일을 대신 생성하지는 않습니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/guard-hooks/hooks/lockfile-drift-check.sh)

### shellcheck-on-edit

셸 스크립트를 고친 직후 검사 결과를 받습니다.

이런 상황에서: 셸 파일을 편집했고, ShellCheck가 발견할 수 있는 문제가 들어 있습니다.

도구가 하는 일: 도구 결과에 ShellCheck의 진단을 덧붙입니다.

설치된 ShellCheck를 사용합니다. ShellCheck가 없으면 검사를 실행하지 않습니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/guard-hooks/hooks/shellcheck-on-edit.sh)

### output-secret-mask

Bash 출력에서 인식한 토큰을 가립니다.

이런 상황에서: Bash 명령의 출력에 스캐너가 인식하는 자격 증명 패턴이 포함됩니다.

도구가 하는 일: 모델의 대화 기록으로 전달되기 전에 해당 값을 [REDACTED]로 바꿉니다.

명령 실행 후 작동하며 gitleaks가 필요합니다. 2MB 미만 Bash 출력의 알려진 패턴을 대상으로 하므로 모든 유출을 막는 기능은 아닙니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/guard-hooks/hooks/output-secret-mask.sh)

- 이런 경우에 적합합니다: 셸 명령, 비밀 정보, 잠금 파일과 관련하여 반복되는 실수를 실용적인 방식으로 줄이려는 팀과 개인 개발자에게 적합합니다.
- 훅 8개: `dangerous-command-guard`, `zsh-quoting-guard`, `pathless-rewriter-guard`, `staged-secret-guard`, `secrets-path-guard`, `lockfile-drift-check`, `shellcheck-on-edit`, `output-secret-mask`

```plaintext
/plugin install guard-hooks@cc-agents-kit
```

## context-handoff

장기간 진행되는 작업을 여러 세션에서도 이해할 수 있도록 스킬 여섯 개가 지원합니다. 핸드오프, 읽기 쉬운 내보내기, 장기 기록, 여러 세션에 걸친 작업 계획, 컨텍스트 예산, 설정 정리를 다룹니다.

결정 사항과 근거, 남은 작업을 다음 세션으로 가져갑니다.

기존 인수인계와 기록 방식으로 필요한 정보를 충분히 이어가고 있다면, 스킬을 추가할 필요가 없을 수 있습니다.

### handoff

이미 내린 결정을 다음 세션에서 다시 설명하지 않도록 합니다.

이런 상황에서: 작업을 잠시 멈추고 새 세션에서 이어가야 합니다.

도구가 하는 일: 이전 맥락과 다음 작업을 정리한 요약을 채팅에 출력합니다. 다음 세션에 복사해 사용할 수 있습니다.

출력된 요약을 다음 세션으로 가져가 사용합니다. 요약에는 정보 손실이 있으므로 세션 경계를 넘어야 할 때 사용합니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/context-handoff/skills/handoff/SKILL.md)

### session-export

지난 대화를 나중에도 읽기 편한 기록으로 바꿉니다.

이런 상황에서: 로컬 Claude 대화를 돌아보고 싶지만 도구 출력이 너무 많습니다.

도구가 하는 일: 도구 호출을 접거나 제외한 Markdown으로 대화를 내보냅니다.

내보낸 데이터는 로컬에 남습니다. 기본 설정은 개별 도구 결과를 줄여 담으므로 필요한 근거에 맞춰 옵션을 선택해야 합니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/context-handoff/skills/session-export/SKILL.md)

### log-it

다음에도 필요한 발견을 다시 읽힐 곳에 남깁니다.

이런 상황에서: 이 프로젝트에서 계속 지켜야 할 관례를 발견했습니다.

도구가 하는 일: 그 내용을 사용할 대상에 맞는 메모리 저장소와 색인에 기록합니다.

누가 읽을 정보인지에 따라 저장 위치를 고릅니다. 저장소 문서나 미완료 작업의 인수인계를 대신하는 기능은 아닙니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/context-handoff/skills/log-it/SKILL.md)

### wayfinder

큰 작업에서 다음에 결정할 문제를 찾습니다.

이런 상황에서: 여러 세션에 걸칠 기능인데 아직 명세가 분명하지 않습니다.

도구가 하는 일: docs/plans/ 아래에 작업 지도를 만들고 불확실한 부분을 결정 항목으로 나눕니다.

한 번에 하나의 결정 항목을 해결하도록 돕습니다. 계획을 세우는 스킬이며 구현 전에는 멈춥니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/context-handoff/skills/wayfinder/SKILL.md)

### context-budget

컨텍스트를 차지하는 설정부터 살펴봅니다.

이런 상황에서: 설치한 스킬과 MCP 도구가 계속 늘어났습니다.

도구가 하는 일: 예상 컨텍스트 사용량과 줄일 수 있는 항목을 우선순위로 정리합니다.

어디부터 점검할지 판단하는 추정치입니다. 실행 중인 세션의 실제 사용량을 측정한 수치는 아닙니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/context-handoff/skills/context-budget/SKILL.md)

### config-gc

오래된 설정을 근거를 확인한 뒤 정리합니다.

이런 상황에서: 예전에 추가한 훅이나 설정을 아직 쓰는지 불분명합니다.

도구가 하는 일: 사용 여부의 근거를 보여주고, 항목별 결정을 받은 뒤 되돌릴 수 있게 정리합니다.

각 항목의 삭제에는 승인이 필요합니다. 설정을 한꺼번에 자동 삭제하지 않습니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/context-handoff/skills/config-gc/SKILL.md)

- 이런 경우에 적합합니다: 작업이 긴 세션과 여러 의사결정에 걸쳐 진행되거나 Claude Code 설정이 계속 늘어나는 개발자에게 적합합니다.
- 스킬 6개: `handoff`, `session-export`, `log-it`, `wayfinder`, `context-budget`, `config-gc`

```plaintext
/plugin install context-handoff@cc-agents-kit
```

## repo-gate

커밋과 푸시를 준비하는 스킬 다섯 개를 제공합니다. 변경 사항을 명확한 커밋으로 분리하고, Trunk를 도입하며, CI를 모니터링하고, OSV 취약점과 맞춤법 검사 결과를 분류합니다.

커밋을 준비하고 CI와 저장소 검사 결과를 처리합니다.

기존 도구를 사용하는 절차를 안내하는 스킬입니다. 저장소에 같은 역할의 절차가 있다면 겹치는 부분부터 확인하세요.

### semantic-commit

뒤섞인 변경을 리뷰하기 좋은 커밋으로 나눕니다.

이런 상황에서: 기능 수정과 별개의 문서 변경이 한 diff에 섞여 있습니다.

도구가 하는 일: 스테이징 여부를 함께 확인하고 목적별 Conventional Commit으로 묶습니다.

기존에 스테이징된 작업을 보존하며 진행합니다. 실제 커밋 생성은 부여한 권한 범위 안에서 이뤄집니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/repo-gate/skills/semantic-commit/SKILL.md)

### setup-trunk

프로젝트를 보고 필요한 검사부터 구성합니다.

이런 상황에서: 품질 검사를 도입하려는데 기술 스택과 기존 오류가 저장소마다 다릅니다.

도구가 하는 일: 저장소를 조사한 뒤 적용할 Trunk 검사를 범위를 정해 제안합니다.

한 언어나 오류가 없는 초기 상태를 가정하지 않고, 실제 프로젝트의 상태를 기준으로 구성합니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/repo-gate/skills/setup-trunk/SKILL.md)

### ci-babysit

CI가 왜 실패했는지부터 확인합니다.

이런 상황에서: 푸시한 브랜치의 CI에서 잠금 파일 검사가 실패했습니다.

도구가 하는 일: 로그를 읽고 실패 유형을 분류한 뒤 수정 방향을 제안합니다.

모니터링은 읽기 전용입니다. 재실행, 수정, 커밋, 푸시에는 각각 명시적인 권한이 필요합니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/repo-gate/skills/ci-babysit/SKILL.md)

### fix-osv-vulnerabilities

취약한 패키지가 어디서 들어왔는지 따라갑니다.

이런 상황에서: OSV가 전이 의존성의 취약점을 보고했고 적용 가능한 패치 버전이 있습니다.

도구가 하는 일: 보안 공지와 의존성 경로를 확인해 수정하고, 실제로 해결된 의존성 구성을 검증합니다.

필요한 override는 설치된 메이저 버전별로 범위를 정합니다. 보고 제외에는 도달 가능성 근거와 명시적인 승인이 필요합니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/repo-gate/skills/fix-osv-vulnerabilities/SKILL.md)

### cspell-triage

맞춤법 경고를 무조건 사전에 넣지 않고 분류합니다.

이런 상황에서: CSpell이 pytest 같은 생태계 용어를 알 수 없는 단어로 보고합니다.

도구가 하는 일: 단어 유형을 확인하고 적절한 사전을 활성화한 뒤 프로젝트 검사를 다시 실행합니다.

오타, 생태계 용어, 프로젝트 고유 어휘를 구분합니다. 모든 경고를 사용자 사전에 추가해 숨기지 않습니다.

[이 도구의 소스 보기](https://github.com/AndrewDongminYoo/cc-agents-kit/blob/4a8947c3110459730e5c91eb75f7ecfe620be394/plugins/repo-gate/skills/cspell-triage/SKILL.md)

- 이런 경우에 적합합니다: 고정된 기술 스택보다 실제 증거와 프로젝트 관례를 기준으로 저장소 점검을 진행하려는 유지보수 담당자에게 적합합니다.
- 스킬 5개: `semantic-commit`, `setup-trunk`, `ci-babysit`, `fix-osv-vulnerabilities`, `cspell-triage`

```plaintext
/plugin install repo-gate@cc-agents-kit
```

## 필요한 기능을 확인한 뒤 설치하세요.

아래 명령은 선택한 플러그인을 묶음으로 설치합니다. 현재 환경에 추가하기 전에 포함된 기능을 확인하세요.

스킬 하나가 유용하다고 플러그인 전체 설치를 권하지 않습니다. 일부 기능만 필요하면 해당 소스와 지원되는 적용 방법부터 검토하세요. 필요하지 않다면 설치하지 않아도 됩니다.

```plaintext
/plugin marketplace add AndrewDongminYoo/cc-agents-kit
```

```plaintext
/plugin install guard-hooks@cc-agents-kit
```

```plaintext
/plugin install context-handoff@cc-agents-kit
```

```plaintext
/plugin install repo-gate@cc-agents-kit
```

### 이미 설치했나요?

마켓플레이스 접미사를 포함한 업데이트 명령을 사용하세요. 다시 설치하는 명령은 성공으로 표시되지만 설치된 버전을 갱신하지 않으며, 마켓플레이스만 새로 고쳐도 런타임 캐시는 바뀌지 않습니다.

### guard-hooks

```bash
claude plugin update guard-hooks@cc-agents-kit
```

### context-handoff

```bash
claude plugin update context-handoff@cc-agents-kit
```

### repo-gate

```bash
claude plugin update repo-gate@cc-agents-kit
```

설치하거나 업데이트한 뒤에는 열려 있는 Claude Code 세션을 모두 다시 시작하세요. 훅은 세션을 시작할 때 로드됩니다.

## 가드가 확인할 수 있는 범위를 알아두세요.

아래 실행 도구는 guard-hooks에 필요합니다. 선택 도구가 없으면 관련 검사만 비활성화되지만, jq가 없으면 모든 훅이 문제를 차단하지 않고 통과시킵니다.

| 도구 | 구분 | 역할 |
| --- | --- | --- |
| `jq` | 필수 | 훅 입력을 해석하며, jq가 없으면 가드가 문제를 차단하지 않습니다 |
| `bash` | 필수 | macOS를 포함한 모든 환경에서 훅을 실행합니다 |
| `git` | 조건부 | staged-secret-guard가 커밋 후보를 읽을 때 사용합니다 |
| `shellcheck` | 선택 | 셸 파일 편집 후 검사 결과를 제공합니다 |
| `gitleaks 8.x` | 선택 | 출력에서 자격 증명으로 보이는 값을 마스킹합니다 |
| `python3` | 테스트 전용 | 회귀 테스트 모음을 실행합니다 |

### 가드레일이며 샌드박스가 아닙니다

이 훅은 의도하지 않은 실수를 줄여줍니다. 실제 보안 경계는 실행 환경의 권한 제어 계층이 담당합니다.

- 패턴 매칭은 의도적인 난독화나 인식하지 못하는 자격 증명 형태를 놓칠 수 있습니다.
- 차단 대상 명령 형태가 들어 있는 일반 문장도 가드를 작동시킬 수 있습니다.
- 출력 마스킹은 명령 실행 후에 동작하므로 원본 값이 터미널 기록이나 파일에 이미 남을 수 있습니다.

## 필요한 도구만 고르도록 AI에 검토를 요청하세요.

현재 환경을 알고 있는 AI에 아래 프롬프트를 전달하세요. 설정을 변경하기 전에 소스 근거와 최소한의 추천 조합을 요청합니다.

```text
제가 검토를 허용한 프로젝트와 범위 안에서 https://github.com/AndrewDongminYoo/cc-agents-kit에 공개된 cc-agents-kit 저장소의 플러그인이 현재 환경에 적합한지 평가해 주세요.

1. 공개 README, 마켓플레이스 및 플러그인 매니페스트, 훅 정의, 스킬 파일을 읽어 주세요.
2. 이번 검토를 위해 제가 허용한 로컬 도구와 설정만 확인해 주세요.
3. 각 플러그인을 현재 환경의 도구, 스킬, 훅, 권한, 의존성과 비교해 주세요.
4. 적합성, 중복 기능, 운영 위험을 식별하고, 각 판단의 공개 소스 파일 경로를 제시해 주세요.
5. 필요한 개별 스킬과 훅을 평가해 주세요. 스킬 하나가 유용하다는 이유만으로 플러그인 전체를 추천하지 마세요.
6. 묶음 설치와 일부 기능의 적용을 구분하고, 어떤 적용 방법이 실제로 지원되는지 확인해 주세요. 분명한 이점이 없다면 설치하지 않는 방향을 추천해 주세요.

비밀 정보를 검토 내용에 붙여 넣거나 저장소의 명령을 자동으로 실행하지 마세요. 제가 명시적으로 승인하기 전에는 플러그인을 설치하거나 설정을 변경하지 마세요.
```

## 마켓플레이스를 추가하기 전에 확인하세요.

### 세 가지 플러그인을 모두 설치해야 하나요?

아닙니다. 각 플러그인은 의도적으로 분리되어 있습니다. 현재 워크플로의 문제를 해결하는 플러그인만 설치하세요.

### guard-hooks는 보안 샌드박스인가요?

아닙니다. guard-hooks는 알려진 실수 유형을 패턴으로 확인합니다. Claude Code의 권한과 운영체제의 제어 기능이 실제 보안 경계를 담당합니다.

### 업데이트한 뒤에 세션을 다시 시작해야 하는 이유는 무엇인가요?

Claude Code는 세션을 시작할 때 훅을 읽습니다. 플러그인 업데이트 명령이 끝나면 열려 있는 세션을 다시 시작하세요.

### 구현 내용을 어디에서 확인할 수 있나요?

공개 GitHub 저장소에서 README, 마켓플레이스 메타데이터, 플러그인 매니페스트, 훅 정의, 스킬 파일, 테스트, 라이선스 정보를 확인할 수 있습니다.