Prorise-cool/Claude-Code-Multi-Agent

Claude-Code-Multi-Agent驱动的新一代AI编程助手生态系统，基于Claude Code构建的智能代理协调工作空间，实现从需求到交付的全流程自动化开发

Claude Code Multi‑Agent – Claude Code용 프로젝트 인식 개발 보조 도구

무엇인가요 – Anthropic의 Claude Code를 일반적인 채팅 보조 도구에서 "프로젝트 인식형" AI 개발자로 바꾸는 오픈소스 프레임워크입니다. 이는 Hooks 시스템을 통해 Claude Code 세션의 핵심 순간(세션 시작, 사용자 프롬프트 제출, 도구 사용 등)에 자동으로 실행됩니다. Hooks는 로컬에서 실행되는 Ollama 모델(예: gemma3:1b)에 접근하여 코드베이스 유형을 감지하고, 사용자 의도를 분석하며, 다양한 내장된 Skills(백엔드 전문가, 테스트 전문가, 보안 전문가 등) 중 하나를 추천하거나 실행합니다. 이 프레임워크는 또한 자동 문서화(DEVELOPMENT.md, KNOWLEDGE.md, CHANGELOG.md)를 강제하고 Git 워크플로우와 통합됩니다.

핵심 개념

개념	역할
Hooks	특정 이벤트(SessionStart, UserPromptSubmit, PreToolUse, PostToolUse 등)에서 실행되는 작은 Python 스크립트. Ollama와 통신하고, 문서를 관리하며, Skills를 로드하고, `exit_code`를 통해 작업 허용 또는 차단 가능.
Ollama	프로젝트 유형 감지, 의도 분석, 스킬 추천을 수행하는 로컬 LLM 엔진. 외부 API 호출이 전혀 필요 없음.
Skills	`SKILL.md` 파일(YAML 프론트마터 + 마크다운)로 정의되는 자가 포함형 "전문가 에이전트". 각 Skill은 백엔드, 프론트엔드, 테스트, 보안 등 도메인을 나타내며, `/backend‑specialist …`와 같은 슬래시 명령어로 호출 가능.
명령어	사전 정의된 다단계 워크플로우(`/kiro/spec`, `/agent‑workflow`, `/gh/commit`)로, 사양 생성, 전체 에이전트 실행, Git 커밋 생성을 자동화.
자동 문서 시스템	프로젝트 지식이 코드와 동기화되도록 세 가지 핵심 마크다운 파일을 강제로 업데이트.

기본 제공 기능

300개 이상의 Skills – 백엔드, 프론트엔드, 테스트, 보안, 아키텍처, DevOps 등 커버.
제로 설정 시작 – 리포지토리 클론 후 프로젝트 폴더를 넣고 환경 변수 몇 가지 설정만 하면, 적절한 Skills가 자동으로 로드되고 문서 파일이 생성됨.
로컬 전용 LLM – Ollama는 당신의 머신에서 실행되며, 프레임워크는 코드를 클라우드로 전송하지 않음.
Git 워크플로우 지원 – 리포지토리 감지, 브랜치 모델(GitHub Flow, Git-Flow) 제안, 커밋 메시지 생성 가능.
의도 기반 도구 선택 – 단순한 "Write" 도구로 충분한지, 아니면 더 복잡한 "Sequential Thinking" 워크플로우가 필요한지 시스템이 판단.

빠른 시작 (약 5분)

필수 사항 설치

# Ollama (Windows/macOS/Linux)
winget install Ollama.Ollama   # Windows
brew install ollama           # macOS
curl -fsSL https://ollama.com/install.sh | sh   # Linux

# 가벼운 모델 다운로드
ollama pull gemma3:1b   # 또는 llama3.2:3b와 같은 더 큰 모델

# uv (빠른 Python 패키지 매니저) 설치
curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS/Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows

리포지토리 클론 및 설정

git clone https://github.com/Prorise-cool/Claude-Code-Multi-Agent.git
cd Claude-Code-Multi-Agent
cp .env.example .env   # 선택 사항 – 기본값은 이미 작동함

코드 추가 – 기존 프로젝트를 복사하거나 리포지토리 내부에 작은 테스트 프로젝트 생성 (예: test-project/main.py).
Claude Code (데스크톱 앱 또는 VS Code 확장)을 열고 리포지토리 폴더를 열기.
확인 – Claude의 채팅에 아무거나 입력. 다음 메시지가 표시되어야 함:
- 프로젝트 유형: Python
- 50개의 Skills 로드됨
- DEVELOPMENT.md / KNOWLEDGE.md / CHANGELOG.md 생성됨

이 메시지가 나타나면 프레임워크가 활성화됨.

일반적인 워크플로우 예시

상황	프레임워크 사용 방법
RESTful API 설계 필요	`/backend-specialist 사용자 인증용 RESTful API 설계` 입력. Claude는 백엔드 전문가로서 리소스 이름, HTTP 메서드, 상태 코드 등을 보여줌.
복잡한 기능 요청	자연어로 요청 작성 (예: "사용자 로그인 기능 구현"). `UserPromptSubmit` 훅이 의도 분석, 도구(`Sequential Thinking`) 추천, 관련 Skills(`backend‑specialist`, `security‑specialist`) 제안, 단계별 계획 반환.
코드 변경 후	파일 편집 후 `PostToolUse` 훅이 `DEVELOPMENT.md`, `KNOWLEDGE.md`, `CHANGELOG.md` 업데이트를 강제하여 문서 동기화.
완전한 사양 필요	`/kiro/spec 사용자 인증 기능` 실행. 명령어가 EARS 형식의 요구사항, 아키텍처, 데이터 모델을 순차적으로 확인하고 `.kiro/specs/` 아래 사양 폴더 생성.
좋은 메시지로 커밋	`/gh/commit` 실행. 변경 사항 분석, Ollama에 요약된 커밋 메시지 생성 요청, `git commit` 실행.

시스템 확장하기

새로운 Skill 추가 – .claude/skills/ 아래에 SKILL.md 파일(YAML 프론트마터 + 마크다운)을 포함한 폴더 생성. 다음 세션 시작 시 자동 탐지됨.
사용자 정의 Hook 생성 – .claude/hooks/handlers/에 Python 스크립트 배치 후 .claude/settings.json에서 적절한 이벤트에 참조.
프롬프트 수정 – 모든 시스템 프롬프트는 .claude/hooks/prompts.json에 저장. 문장 수정, 변수({type}, {framework}) 추가 가능. 변경 사항 즉시 적용.

프로젝트 구조 (개요)

claude-code-multi-agent/
├─ .claude/
│  ├─ hooks/            # Hook 커널, 핸들러, 설정
│  ├─ commands/         # 다단계 워크플로우
│  └─ skills/           # 전문가 에이전트 (backend‑specialist, …)
├─ project_document/    # 자동 유지 관리 문서 (DEVELOPMENT.md, …)
├─ .env.example         # 환경 변수 예시 (OLLAMA_MODEL, TTS 설정)
├─ pyproject.toml       # uv 종속성 파일
└─ README.md            # (이 파일)

누구에게 적합한가?

개인 개발자 – 긴 프롬프트를 작성하지 않고도 Claude Code가 자신의 리포지토리를 "이해"하도록 하고 싶은 사람.
작은 팀 – 재현 가능하고 버전 관리 가능한 온프레미스 AI 보조 도구를 찾는 사람.
교육자 / 트레이너 – 자체 호스팅 LLM을 사용해 AI 강화 개발 워크플로우를 보여주고 싶은 사람.

라이선스 및 기여

라이선스: MIT (README의 배지 참조).
기여: 풀 리퀘스트로 환영. 리포지토리에는 CONTRIBUTING 스타일 가이드, 테스트 명령어(uv run pytest), 개발 진입점(uv run python -m claude_hooks.dev) 포함.

결론

Claude Code Multi‑Agent는 실제로 실행 가능한 프레임워크로, 로컬 Ollama 모델과 깔끔한 Python Hook 아키텍처로 관리되며, Claude Code에 프로젝트 인식 능력, 스킬 기반 전문가 에이전트, 강제 문서화를 추가합니다. 거의 수동 설정 없이 AI 강화 개발 환경을 즉시 사용할 수 있습니다.