sangrokjung/claude-forge

⚡ 처음이신가요? 60초 설치 가이드 →

English · 한국어 · 中文

Claude Code(AI 코딩 조수)에 전문 장비 풀세트를 한 번에 장착하는 프레임워크

이게 뭔가요? • 설치 • 구성 요소 • 사용법 • v3.0 변경사항 • English

🔁 v4.3.0 (2026년 9월, 최신): session-time-report가 Codex도 읽어요. 같은 훅, 같은 리포트인데 Claude Code 기록인지 Codex rollout 로그인지 알아서 구분해서 셉니다. Codex 배선은 ~/.codex/hooks.json에 두 줄 넣으면 돼요(방법).

⏱️ v4.2.0 (2026년 9월): session-time-report(22번째 훅)를 추가했어요. 세션이 닫힐 때 시간을 재두고, 다음에 세션을 열면 몇 시에 끝났는지, 실제로 얼마나 걸렸는지, 프롬프트와 도구를 얼마나 썼고 파일을 몇 개 고쳤는지 한 줄로 알려줘요. 며칠 뒤에 이어서 연 세션이라도 전체 경과가 아니라 이번에 앉아 있던 시간만 보여줍니다. 기록은 ~/.claude/work-log/에 남아요.

📉 v4.1.0 (2026년 8월): harness-diet(33번째 스킬) 추가. 항상 로딩되는 컨텍스트(CLAUDE.md + rules)를 실측하고, 거버넌스를 잃지 않으면서 예산 안으로 줄여줘요.

🛡️ v4.0.0 (2026년 8월): 가장 큰 변화는 **적대적 검증 루프(adversarial verification loop)**예요. 코드를 바꿀 때마다, 그 코드를 짜지 않았고 짠 사람의 생각 흐름도 모르는 독립 리뷰어(adversarial-reviewer)가 따로 검증해요. "작성자와 검증자는 다른 사람이어야 한다"(maker≠checker)는 원칙이고, 검증자가 APPROVE를 낼 때까지 반복해요. 이론이 아니라 실제로 v4.0을 만드는 동안 이 루프가 대표 유지자 본인의 PR(#58, #61)에서 진짜 결함 3건을 잡아냈어요. 자기 자신의 회귀를 통과시키던 CI 검사 하나, 그 검사를 고친 수정본에 똑같은 구멍이 한 단계 더 숨어 있던 것 하나, 그리고 1년 전 릴리스에 조용히 묶여있던 의존성 상한 하나였죠. 실제 검증 기록은 docs/VERIFICATION-LOOP.md에 있어요. 그 외에 신뢰성 패키지도 넣었어요. API 오류가 나면 세션을 스스로 재개하는 무인 자동 복구, /compact 이후에도 이어지는 세션 릴레이, 같은 파일을 계속 고치는 걸 감지하는 무한루프 가드, 옵트인 pre-commit 시크릿 가드가 들어있고, 배선 가이드는 docs/RELIABILITY.md에 있어요. 디버깅 에스컬레이션 체인(systematic-debugger → rca-debugger → escalation-fixer), 작업 난이도 자동 분류(/workflow-classify가 S/M/L/XL로 작업 크기를 매기고 문서화·검증 강도를 그에 맞춰요), 한국어 산문 품질 가드레일(사후 윤문이 아니라 처음 쓸 때부터 번역투·AI 관용구를 피해요. 아래 별도 섹션 참고)도 함께 담았어요. 에이전트 16개, 커맨드 35개, 스킬 32개, 훅 21개, 규칙 14개. 상세: MIGRATION.ko.md

🔧 v3.1.1 핫픽스 (2026년 8월): 플러그인 설치 시 아무것도 안 뜨던 문제를 고쳤어요(Hook load failed: expected record, received undefined). /plugin install claude-forge 후 ✘ failed to load가 뜨고 스킬·에이전트·커맨드가 하나도 안 보였다면 3.1.1로 올리시면 됩니다. 윈도우 install.ps1이 statusLine과 scripts/를 복사하지 않던 문제도 함께 해결했어요. 관련: #52 · #57 · #50

🎉 v3.1.0 공개 (2026년 6월): loop-forge(반복 작업을 재사용 가능한 자가검증 슬래시 명령으로 박제) 추가 + 이 README를 비개발자 눈높이로 전면 재작성(도표 3종 포함). v3.0.2(쉬운 설치 경로)·v3.0.1(Anthropic 2026 표준: 훅 21+ 이벤트 · 서브에이전트 v2 · 스킬/커맨드 하이브리드 · MCP 4개) 기반. 상세: MIGRATION.ko.md

🚀 한 줄 설치 (전체 설치, 권장):

curl -fsSL https://raw.githubusercontent.com/sangrokjung/claude-forge/main/install.sh | bash

또는 Claude Code 세션 안에서: /plugin marketplace add sangrokjung/claude-forge → /plugin install claude-forge (부분 지원).

이게 뭔가요?

Claude Code(AI 코딩 조수)를 혼자 쓰면 기본기만 할 줄 아는 신입 직원과 같아요. Claude Forge는 그 신입에게 장비 풀세트(전문 비서 16명, 단축버튼 35개, 안전장치 22개 등)를 한 번에 장착해 줘요.

마치 터미널(명령창)을 꾸며주는 oh-my-zsh처럼, Claude Forge는 AI 코딩 조수를 파워 유저 도구로 업그레이드해요.

한 번 설치하면 아래가 모두 자동 연결돼 바로 쓸 수 있어요:

뭐가 좋아요?

계획부터 PR까지 자동으로 이어져요

/plan 하나로 AI가 구현 계획을 세우고, /tdd(테스트 주도 개발)로 테스트를 먼저 작성하고, /code-review로 코드를 검토하고, /commit-push-pr로 PR(코드 병합 요청)까지 만들어 줘요. 각 단계가 서로 자동으로 연결돼 있어요.

6겹 보안 안전망이 항상 켜져 있어요

코드를 짤 때마다 API 키 노출 방지 → 위험한 원격 명령 차단 → 파괴적 SQL(데이터베이스 삭제 명령) 차단 → 취약점 자동 탐지 → API 속도 제한 → 고비용 도구 경고가 자동으로 작동해요. 따로 신경 쓰지 않아도 돼요.

반복 작업을 슬래시 명령으로 박제할 수 있어요

loop-forge(루프 단조) 스킬로 자주 반복하는 작업 흐름을 한 줄짜리 /명령어로 만들어 두면 다음엔 그냥 입력만 하면 돼요.

git pull 한 번이면 즉시 업데이트돼요

설치 방식이 심볼릭 링크(바로가기 연결) 기반이라, 새 버전이 나와도 git pull 한 줄로 끝이에요.

어떻게 설치해요?

설치 방법은 두 가지예요. 전체 기능이 필요하면 **방법 B(권장)**를 선택하세요.

방법 A: Claude Code 플러그인 (명령·스킬 일부만, 빠른 시작)

Claude Code 세션 안에서 두 줄 입력:

/plugin marketplace add sangrokjung/claude-forge
/plugin install claude-forge

업데이트: /plugin update claude-forge

⚠️ 주의: 이 방법은 커맨드(단축버튼)와 일부 스킬만 연결돼요. 전문 비서(에이전트), 안전점검(훅), 규칙, 외부 도구 연결(MCP)은 연결되지 않아요. Claude Code 로더의 현재 정책 때문이에요. 전체 기능을 원하면 방법 B를 쓰세요.

방법 B: install.sh 전체 설치 (권장)

# 1. 코드 가져오기 (서브모듈은 선택 — 상태바만 해당)
git clone --recurse-submodules https://github.com/sangrokjung/claude-forge.git
cd claude-forge

# 2. 설치 (~/.claude 폴더에 바로가기 연결 생성)
./install.sh

# 3. Claude Code 실행
claude

설치 스크립트가 자동으로 해주는 것들:

1. 필요한 도구 확인 (node.js, jq, git)
2. 바로가기(심볼릭 링크) 생성: ~/.claude/ 폴더에 전체 연결
3. 외부 도구(MCP 서버) 설치 선택
4. 셸 단축 명령 설정 (cc, ccr)

v2.1에서 올라오는 경우: ./install.sh --upgrade (기존 설정 백업 후 안전하게 이전)

# WSL 네이티브 경로에 클론해야 바로가기 방식 가능
cd ~ && git clone --recurse-submodules https://github.com/sangrokjung/claude-forge.git
cd claude-forge && ./install.sh

.\install.ps1

뭐가 들어있어요?

에이전트(agents): 분야별 전문 비서 16명

v4.0 신규: 검증·디버깅 에이전트 5명

훅(hooks): 자동 안전점검 22개

항상 켜져 있는 보안 6겹:

v4.0 신규: 신뢰성 훅 6개 (무인 세션 안전망)

배선 가이드 전문은 docs/RELIABILITY.md에 있어요. 별도로 옵트인 pre-commit 시크릿 가드(scripts/install-precommit.sh)도 v4.0에 추가됐는데, 이건 위 훅들과 달리 여러분이 지정한 git 저장소의 커밋을 보호하는 독립 설치형 스크립트예요.

[Claude Forge] 직전 세션 종료 21:34 KST
소요 2h 17m · 프롬프트 18 · 도구 143 · 변경 파일 9
로그: ~/.claude/work-log/session-time-<session_id>.json

MCP: 외부 도구 연결 4개 (기본)

어떻게 써요?

새 기능 개발: 계획부터 PR까지

/plan → /tdd → /code-review → /handoff-verify → /commit-push-pr → /sync

graph LR
    P["/plan<br/><small>구현 계획</small>"] --> T["/tdd<br/><small>테스트 주도 개발</small>"]
    T --> CR["/code-review<br/><small>코드 리뷰</small>"]
    CR --> HV["/handoff-verify<br/><small>Fresh 검증</small>"]
    HV --> CPR["/commit-push-pr<br/><small>커밋 & PR</small>"]
    CPR --> S["/sync<br/><small>문서 동기화</small>"]

    style P fill:#e94560,stroke:#fff,color:#fff
    style T fill:#0f3460,stroke:#fff,color:#fff
    style CR fill:#0f3460,stroke:#fff,color:#fff
    style HV fill:#533483,stroke:#fff,color:#fff
    style CPR fill:#16213e,stroke:#fff,color:#fff
    style S fill:#1a1a2e,stroke:#fff,color:#fff

버그 수정

/explore → /tdd → /verify-loop → /quick-commit → /sync

보안 감사

/security-review → /stride-analysis-patterns → /security-compliance

팀 협업: 멀티 에이전트

/orchestrate

graph LR
    L["팀 리더"]
    A1["에이전트 1<br/><small>프론트엔드</small>"]
    A2["에이전트 2<br/><small>백엔드</small>"]
    A3["에이전트 3<br/><small>테스팅</small>"]

    L <-->|조율| A1
    L <-->|조율| A2
    L <-->|조율| A3

    style L fill:#e94560,stroke:#fff,color:#fff
    style A1 fill:#0f3460,stroke:#fff,color:#fff
    style A2 fill:#0f3460,stroke:#fff,color:#fff
    style A3 fill:#0f3460,stroke:#fff,color:#fff

• 리더가 중심이 되어 여러 에이전트를 조율하는 허브 앤 스포크 방식이에요
• 각 에이전트가 맡은 파일을 독립적으로 처리해 머지 충돌이 없어요
• 단계별로 팀을 교체하는 페이즈 기반 운영도 가능해요

처음이신가요?

또는 /auto 로그인 페이지 만들기를 입력하면 계획부터 PR까지 알아서 진행해요.

v4.0 업데이트

한국어 산문 품질 가드레일, 자세히

비유: 좋은 번역가는 원문의 뜻을 한 글자도 바꾸지 않으면서 "원래 한국어로 쓴 글"처럼 옮겨요. Claude Forge가 만드는 한국어 산문도 똑같아요. 사실·수치·격식은 그대로 두고, AI가 남기는 기계적 말투만 처음부터 걷어내요.

Claude Forge를 쓰는 사람이 한국어로 마케팅 카피, 블로그, 이메일, 보고서, 커밋 메시지가 아닌 사람이 읽을 산문을 쓰게 하면, v4.0부터는 다음 장치가 함께 움직여요.

핵심은 "AI 탐지기를 속이기"가 아니라 "어색한 번역투를 자연스러운 한국어로 고치기"예요. 격식이 필요한 글(계약서, 법률 문서)은 그 격식 자체를 AI 티로 보지 않고 그대로 존중해요.

v3.1.0 업데이트 (역사)

v3.0 업데이트

자주 묻는 질문

---
name: my-agent
description: Use this agent when [트리거 조건]. Input: [입력]. Output: [출력].
tools: ["Read", "Grep", "Glob"]
model: sonnet
memory: project
color: blue
---

You are an expert [역할]. Your mission is to [목표].

## Process
1. [단계 1]
2. [단계 2]

# my-command.md

/my-command 실행 시 수행할 작업을 기술합니다.

#!/bin/bash
# hooks/my-guard.sh
# PreToolUse, PostToolUse 등 특정 이벤트(작동 시점)에서 실행됩니다.

전체 목록 (개발자용 상세)

graph TB
    subgraph REPO["claude-forge (git 리포)"]
        A["agents/ (11)"]
        C["commands/ (34)"]
        S["skills/ (26)"]
        H["hooks/ (15)"]
        R["rules/ (10)"]
        SC["scripts/"]
        CC["cc-chips/"]
        K["knowledge/"]
        REF["reference/"]
        SET["settings.json"]
    end

    INSTALL["./install.sh"]
    REPO --> INSTALL

    subgraph HOME["~/.claude/ (심볼릭 링크)"]
        HA["agents/"]
        HC["commands/"]
        HS["skills/"]
        HH["hooks/"]
        HR["rules/"]
        HSC["scripts/"]
        HCC["cc-chips/"]
        HSET["settings.json"]
    end

    INSTALL -->|symlink| HOME

    CLAUDE["claude (CLI)"]
    HOME --> CLAUDE

    style REPO fill:#1a1a2e,stroke:#e94560,color:#fff
    style HOME fill:#0f3460,stroke:#16213e,color:#fff
    style INSTALL fill:#e94560,stroke:#fff,color:#fff
    style CLAUDE fill:#533483,stroke:#fff,color:#fff

claude-forge/
  ├── .claude-plugin/            플러그인 매니페스트 (4.3.0)
  ├── .github/workflows/         CI 검증
  ├── agents/                    에이전트 정의 (16 .md, frontmatter v2)
  ├── cc-chips/                  상태바 서브모듈
  ├── cc-chips-custom/           커스텀 상태바 오버레이
  ├── commands/                  슬래시 커맨드 (35 .md, 8개는 skills/로 이동)
  ├── docs/                      스크린샷, 다이어그램, 정책 문서 (RELIABILITY.md·VERIFICATION-LOOP.md 포함)
  ├── hooks/                     이벤트 기반 스크립트 (22)
  │   └── examples/              21 lifecycle 이벤트 샘플 opt-in (9)
  ├── knowledge/                 지식 베이스
  ├── libs/                      훅이 공유하는 쉘 라이브러리 (hook-guard.sh)
  ├── reference/                 참조 문서 (+ agent-schema.json, ai-tell-taxonomy.md)
  ├── rules/                     자동 로드 규칙 파일 (14)
  ├── scripts/                   유틸리티 스크립트 (install-precommit.sh 포함)
  ├── setup/                     설치 가이드 + CLAUDE.md 템플릿
  ├── skills/                    다단계 스킬 워크플로우 (33, 하이브리드 정책)
  ├── install.sh                 macOS/Linux 설치 (--upgrade 지원)
  ├── install.ps1                Windows 설치 (--upgrade 지원)
  ├── mcp-servers.json           MCP 기본 설정 (4 minimal)
  ├── mcp-servers.optional.json  MCP 선택 서버
  ├── settings.json              Claude Code 설정 (2026 필드)
  ├── MIGRATION.md               v2.1 → v4.0 이전 가이드 (EN)
  ├── MIGRATION.ko.md            v2.1 → v4.0 이전 가이드 (KO)
  ├── CONTRIBUTING.md            기여 가이드
  ├── SECURITY.md                보안 정책
  └── LICENSE                    MIT 라이선스

# 로컬 오버라이드 파일 생성 (git-ignored, 개인 설정)
cp setup/settings.local.template.json ~/.claude/settings.local.json

# 개인 시크릿·환경설정 편집
vim ~/.claude/settings.local.json

기여하기

에이전트, 커맨드, 스킬, 훅 추가 방법은 CONTRIBUTING.md를 참조하세요.

Claude Forge를 사용하시나요? 배지를 달아주세요!

[![Built with Claude Forge](https://img.shields.io/badge/Built_with-Claude_Forge-orange?style=flat-square)](https://github.com/sangrokjung/claude-forge)

이 배지를 프로젝트 README에 추가하면 Claude Forge 사용을 알릴 수 있어요.

Contributors

라이선스

MIT. 자유롭게 사용, 포크, 확장하세요.

_{Made with ❤️ by QJC (Quantum Jump Club)}