Extensions — 33 hooks + 21 skills + 7 rules
코마드월드(~/.claude/) 위에 얹는 자가진화·안전·증명 레이어. Claude Code OAuth 사용자를 위한 로컬 전용 확장,
외부 서비스 의존성 없음. 복사 기반 설치, Python stdlib + bash 만 사용.
Python 3
bash
33 hooks
21 skills
7 rules
zero deps
설치
한 명령으로 hooks/skills/config 가 ~/.claude/ 에 복사됩니다. 기존 파일은 .bak-<UTC> 백업 후 덮어쓰기. 재실행 안전.
# Clone + install
git clone https://github.com/kinkos1234/comad-world-extensions \
~/Programmer/01-comad/comad-world-extensions
cd ~/Programmer/01-comad/comad-world-extensions
./install.sh
# 설치 후 두 가지 수동 작업:
# 1. ~/.claude/settings.json 의 hooks 블록에 9개 훅 등록
# (install.sh 종료 시 스니펫 출력)
# 2. ~/.claude/CLAUDE.md 에 T6 섹션 추가
전제 — comad-world 가 먼저 설치되어 있어야 합니다 (
~/.claude/ 디렉터리 구조 가정).
comad-world 가 없어도 hooks/skills 자체는 동작하지만 brain/ear 와의 연동 시나리오는 제한됩니다.
훅 33종
pre-tool-use 21개 + Stop 12개. 2026-09-03 개편(3개월 감사: 교정 178건)으로 하드 게이트 7종(agent-contract·deploy-approval·still-broken-edit·claim-done·discord-reply·numbered-requirements-echo·ui-render)은 exit 2 로 차단하고, 나머지는 경고·로그(exit 0). 일부는 환경변수 COMAD_*_BLOCK=1 로 exit 2 승격 가능.
pre-tool-use (21종)
| 훅 | 역할 | 트리거 | 승인 플래그 |
|---|---|---|---|
destroy-gate | Approval-Gated Destruction | rm -rf /, rm -rf ~/..., git push --force, DROP, truncate 등 | approve-destroy[.<hash>] |
no-env-commit | .env/credentials git add 차단 | .env, credentials.json, *.pem staging | approve-env-commit[.<hash>] |
qa-gate-before-push | .qa-evidence.json 있으면 verdict=PASS 강제 | git push | approve-push-qa-skip[.<hash>] |
usage-gate | OAuth 5h/7d 쿼터 방어 (현재 dormant) | 배경 Task 호출 | approve-usage-once |
proto-isolation-gate | 시안 작업이 프로덕션 파일을 건드리는 것 차단 (마커 있을 때만 동작) | .comad/proto/ACTIVE 마커 + 시안 폴더 밖 수정 | — |
push-structural-gate | push 직전 구조적 재발 체크 | git push | — |
task-quality-gate | UI 변경 push 시 시각 증거 강제 | UI 파일 변경 + git push | — |
i18n-leak-gate | i18n dict 의 모듈-init 캡처(early binding) 차단 — 언어전환 시 한글 잔존 | i18n dict 조기 바인딩 패턴 | — |
fixed-bg-zindex-gate | fixed inset-0 배경 도입 시 relative z-10 누락 경고 | 배경 레이어 CSS | warn |
cron-zero-minute-gate | 새 cron 의 정각(:00) 스케줄 경고 — 정각 발화 드롭 재발 방지 | cron/launchd 정의 추가 | warn |
launchd-nvm-path-gate | launchd 스크립트가 PATH 확장 없이 npm 전역 바이너리를 프로브하면 경고 | launchd 스크립트 작성 | warn |
block-text-overlay | 생성 이미지 위 글자 후처리(오버레이) 차단 | 이미지 텍스트 합성 명령 | — |
always-true-assertion-gate | 어떤 값이든 통과하는 죽은 단언 차단 — ? true : true, assert.ok(true) | 테스트·검사 스크립트 작성 | — |
push-checks-warn | push 되는 변경 파일에만 재발 감지 체크 8종 (CSP·프린지·등급 에셋·iframe 위임·hydration·합성 볼드·@media 순서·저장 실패) | git push | warn (destroy-gate 테스트 실패만 차단) |
client-clock-rev-gate | rev/version 을 클라이언트 시계로 매기는 것 경고 — 시계 빠른 기기의 낡은 값이 영구히 이긴다 | rev: Date.now() 류 | warn |
empty-coalesce-warn | 동기화 경로에서 «모름»을 빈 문자열로 눌러 담는 것 경고 — downstream 이 삭제로 읽는다 | sync·reconcile·worker 파일의 ?? '' | warn |
agent-contract-gate | Agent 스폰 계약 — name 없음·fork 외 model 없음·버전 핀 모델이면 차단, DELIVERABLE: 없으면 경고 | Agent 호출 | exit 2 |
deploy-approval-gate | 프로드 배포는 매번 사용자의 명시 지시 후 — 30분 내 승인 마커 없으면 차단, 마커는 1회용 | flyctl deploy·vercel --prod·prod 레포 git push | approvals/deploy-<repo> |
still-broken-edit-gate | «여전히» 3회째부터 가설 문서 없이는 코드를 만지지 못한다 — 같은 층 패치 반복 차단 | still-broken 카운트 ≥3 + Write/Edit | hypotheses*.md 작성 |
recurring-fix-needs-test | 30일 내 같은 scope 의 fix 2회째는 테스트 파일 변경을 동반해야 push | git push (fix 커밋) | exit 2 |
authz-path-enumeration | 권한 판정을 바꾸는 push 는 커밋 메시지에 닿는 경로(page·api·action·nav·proxy)를 열거해야 한다 | git push (권한 diff) | exit 2 |
Stop (12종)
| 훅 | 역할 | 로그 |
|---|---|---|
t6-capture | 세션 종료 시 현재 repo 의 최근 fix:/feat:/bugfix: 커밋 포착 | .comad/pending/*.json |
claim-done-gate | "모두 통과 / 92/92 PASS" 류 주장 + Bash 검증 없음 감지 | .comad/pending/claim-done.jsonl |
numeric-claim-gate | "완벽 / production-ready / 100%" 절대 주장 vs 실제 evidence 대조 | .comad/pending/numeric-claim.jsonl |
adversarial-review-gate | 분량 있는 코드 변경은 기본으로 적대적 리뷰를 요구 | .comad/pending/adversarial-review.jsonl |
harsh-critic-gate | 사용자 관점 안티패턴 탐지 | .comad/pending/harsh-critic.jsonl |
recurring-fix-detector | 같은 파일을 반복 수정하는 루프 신호 | .comad/pending/recurring-fix.jsonl |
visual-thrash-warn | 시각 재구성 스래싱 경고 (신호만, 항상 통과) | .comad/pending/visual-thrash.jsonl |
discord-reply-enforce | Discord 채널로 들어온 메시지에 reply 도구 호출 없이 턴을 끝내지 못한다 (하드 룰 #0) | exit 2 |
numbered-requirements-echo | 번호 요구 N개 → 항목별 상태(완료·미착수·보류…) N개 없이는 종료 금지 — 조용한 누락 차단 | exit 2 |
ui-render-before-stop | 이번 턴에 UI 파일을 고쳤으면 렌더 png 없이는 종료 금지 (예외 «렌더 생략 사유:») | exit 2 |
worker-recovery-gate | 스폰한 비동기 워커를 회수·재지시·ABANDON·TaskStop 중 하나로 처리했는지 (현재 기록만) | .comad/pending/worker-recovery.jsonl |
test-data-ledger-warn | 장부에 남은 미정리 테스트 데이터를 세션 끝에 알린다 (경고만) | .comad/test-data-ledger.md |
규칙 7종
훅이 기계적으로 막을 수 있는 것은 훅으로, 판정이 사람 몫인 것은 규칙으로 남긴다.
같은 실수가 2회 이상 관측된 메모리만 rules/ 로 승격되며, 승격은 evolve 파이프라인이 수행한다.
상시 차단이 어려운 판단(오탐이 잦아 가드가 죽는 영역)이 여기로 온다. 근거가 한 레포에만 있는 규칙(sync-integrity·authz-server-side-every-path)은 2026-09-03 부터 그 레포의 .claude/rules/ 로 이관했다.
| 규칙 | 무엇을 막나 |
|---|---|
guard-scope-discipline | 가드의 감시 범위가 넓어 오탐이 쌓이는 것 — 오탐이 반복되면 사람이 가드를 무시하고, 그 순간 가드가 죽는다 |
untrusted-content-egress | 외부에서 읽은 내용을 지시로 받아들이는 것 — 유입에서 유출로 이어지는 경로에 사람을 둔다 |
first-match-rule-ordering | 순차 first-match 체인에서 넓은 규칙이 위에 있어 좁은 규칙이 도달 불가가 되는 것 |
standalone-bundle-trace | 번들러 trace 밖 프로세스(spawn 워커·별도 프로세스)의 의존성 누락 — 로컬은 되는데 배포에서만 죽는 조합 |
frontend-overflow-and-modal-traps | 텍스트 잘림 3대 원인·모달 스크롤 보존·시트 안에서 스크롤을 어디에 거나 |
prototype-isolation | 확정되지 않은 시안이 프로덕션에 섞이는 것 — 마커가 있을 때만 도는 훅과 짝 |
secrets-never-in-responses | 응답 직렬화에 비밀번호 해시·토큰·쿠키·API 키를 싣는 것 — 가린(redact) 필드는 저장 왕복에서 «빈 값 = 변경 없음»으로 보존 |
스킬 21종
| 스킬 | 목적 | 핵심 바이너리 |
|---|---|---|
comad-learn | T6 pending JSON → feedback memory 승격 + validator 2종 | validate-pending.py, validate-feedback.py |
comad-memory | ~/.claude/projects/*/memory/*.md 의 SQLite FTS5 인덱스 + 검색 | sync.py, search.py, trace.py, refresh.py |
comad-qa-evidence | .qa-evidence.json 생성·검증 (L0~L5 QA levels) | init-qa-evidence.py, validate-qa-evidence.py |
comad-second-opinion | .second-opinion.md 생성 가이드 (codex CLI → subagent → self-adversarial 3-tier fallback) | validate-second-opinion.py |
comad-parallel | Codex CLI 병렬 외주 (Claude=PM, Codex×N=구현) + 5종 comad 통합 게이트 | parallel.sh, parallel-job.js (1500+ LOC) |
comad-ci-healer | GH Actions 실패 → 분류 → headless claude 수정 → PR 자동생성 (launchd 폴러, dry_run+allowlist 가드) | poll.py, classify.py, heal.sh, notify.sh, run.sh |
comad-pr-review | PR 4축(정확성·보안·성능·컨벤션) 자동 채점 → 인라인+요약 코멘트 (codex+claude, headSha dedup) | review.sh, post.sh, run.sh |
comad-sdd | Spec-Driven Development 닫힌 루프 — SPEC(완료기준 체크리스트)→PLAN(역할 taxonomy)→BUILD→VERIFY(AC별 evidence 대조, FAIL시 루프백)→CLOSE. show-me-the-prd 와 autoplan 사이 갭 | check-acceptance.sh |
comad-taste | Taste Layer — 디자인 생성 퀄리티 상향. "퀄리티≈레퍼런스×자기비평" 진단으로 design-dna 코퍼스(6아키타입) 주입 + generate→render→critique(6축+anti-slop)→regenerate 루프. swipe-harvester로 레퍼런스 자산화 | render.sh, swipe-search.mjs |
harness-report | Loopy-Era 5축 하네스 점수 + 비용/efficiency(notional, composite와 분리) 측정 → results.tsv 추세 + HTML 대시보드 | harness-report.py, collect-cost.py, dashboard.py |
comad-recall ⚠️ comad-brain | comad-brain(Neo4j) 출처-인덱스 리콜 — 주제의 실재 기사·기술계보. claim 은 미검증이라 헤지. recency 질문 +3.12 lift(블라인드 A/B 측정) | recall.sh |
comad-foresight ⚠️ comad-brain | brain hot클러스터 → 10렌즈(손자·탈레브·헤겔…) 전략 foresight + 주간 통합 인텔리전스 리포트. plain 대비 +1.375 lift. comad-eye 컨셉 승계 | cluster.sh, digest.sh, run.sh |
comad-parallel 심화 — 5종 통합 게이트
gptaku-plugins/pumasi v1.7.2 를 포팅 후 comad 시스템에 맞게 5종 게이트 신설. 모두 opt-in (env 로 활성화) 또는 default-on (handoff). 한 번의 parallel.sh run-all 로 results → qa-gate → second-opinion-gate → destroy-check → handoff → ear-notify 의 6-단계 파이프라인 자동 실행.
| 명령 | 기능 | 환경변수 | 산출물 |
|---|---|---|---|
parallel.sh handoff |
7-section 핸드오프 doc (Summary / Key Decisions / Traps / Working Agreements / Relevant Files / Open Work / Prompt for New Chat). Summary/Files/Open Work 자동 채움. | COMAD_AUTO_HANDOFF=0 으로 비활성 |
.comad/sessions/<ts>-parallel-<jobid>.md |
parallel.sh qa-gate |
done task cwd 의 .qa-evidence.json + verdict=PASS 검증. validate-qa-evidence.py 우선, jq fallback. |
COMAD_QA_EVIDENCE=1 |
members/<task>/qa-evidence.json |
parallel.sh second-opinion-gate |
.second-opinion.md frontmatter verdict (APPROVED/REQUEST_CHANGES/BLOCKS) 검증. 자동 실행 X — verify only. |
COMAD_SECOND_OPINION=1 |
members/<task>/second-opinion.json |
parallel.sh destroy-check |
Worker output 에서 13종 destructive 패턴 grep (rm -rf /|~|$HOME, git push --force, DROP DATABASE, mkfs.*, fork bomb 등). Codex 가 별도 프로세스라 사후 검사. |
COMAD_DESTROY_CHECK=1 |
members/<task>/destroy-check.json |
| (ear-notify, internal) | cmdRunAll 끝에 Discord webhook POST. 한 줄 요약 (job id + done/failed). 실패 silent. | COMAD_EAR_NOTIFY=1 + DISCORD_WEBHOOK_URL |
Discord 메시지 |
실행 흐름
# 한 번의 호출로 6단계 파이프라인 (default + 모든 게이트 활성화)
COMAD_QA_EVIDENCE=1 \
COMAD_SECOND_OPINION=1 \
COMAD_DESTROY_CHECK=1 \
COMAD_EAR_NOTIFY=1 DISCORD_WEBHOOK_URL=... \
parallel.sh run-all "프로젝트 컨텍스트"
# 흐름:
# 1. start → Codex worker N개 spawn
# 2. wait → 모두 종료까지 대기
# 3. results → 각 worker output.txt 출력
# 4. qa-gate → .qa-evidence.json verdict 검증 (env 활성 시)
# 5. second-opinion-gate → .second-opinion.md verdict (env 활성 시)
# 6. destroy-check → 13 패턴 사후 스캔 (env 활성 시)
# 7. handoff → 7섹션 doc 생성, 위 결과 모두 반영 (default ON)
# 8. ear-notify → Discord 한 줄 요약 POST (env 활성 시)
# 9. clean → job dir 삭제
handoff doc 의 인지적 섹션 — Key Decisions / Traps / Working Agreements 는
TODO(claude) stub 으로 남겨집니다.
Claude 가 후속 세션에서 수동으로 채워야 함. Summary / Relevant Files / Open Work 는 worker report.json 에서 자동 채움.
T6 자가진화 루프
"실수 → 자동 포착 → 분석 → 기억 → 반복 회피" 의 4-step 루프. 외부 서비스 없이 동작.
- Stop hook (자동) — 매 Claude 세션 종료 시
~/.claude/hooks/stop/t6-capture.sh가 현재 git repo 의 최근fix:/feat:/bugfix:커밋을~/.claude/.comad/pending/<hash>.json에 덤프. 사용자 개입 없음. - 분석 (사용자 호출) —
/comad-learn스킬이 pending JSON 들을 읽어 반복 패턴 추출. 판정 기준 통과 시memory/feedback_<topic>.md로 승격 (append-only). - HARD 훅 후보 (2회+ 반복) — 같은 topic 이 2회 이상 관찰되면 해당 메모리 파일에 "HARD 훅 후보" 섹션 추가 + 사용자 승인 요청. 승인 시
destroy-gate.sh패턴 리스트에 추가. - 처리 완료 — 처리한 pending 은
_processed/, 거부는_rejected/로 이동 (원본 삭제 금지).
parallel 과의 연계 —
parallel worker 가 산출 변경을 fix:/feat: prefix 로 git commit 하면, 다음 Claude 세션 종료에서 t6-capture 가 자동 포착 → /comad-learn 으로 학습 가능.
Worker instruction 에 "When done, create a git commit with prefix fix: or feat:" 명시 권장.
레포 / 라이선스
GitHub: kinkos1234/comad-world-extensions · 라이선스: MIT · 외부 서비스 의존성 0 (Python stdlib + bash 만 사용)
자매 레포 —
comad-world (8 핵심 모듈) +
comad-studio (5 시각/미디어 생성) 와 함께 한 시스템을 이룹니다.
설치 순서 권장: world → extensions → studio.