Stanshy/AgentHub: Claude Code를 활용한 가상 개발 팀 구축 및 Harness Engineering 시스템

Claude Code를 사용하여 가상 개발 팀을 구축하고, Harness Engineering을 사용하여 AI가 규율 있게 작동하도록 만드세요.

AgentHub는 단순한 또 다른 AI 채팅 인터페이스가 아닙니다.

이것은 Claude Code를 사용하여 PM, Tech Lead, 프론트엔드 개발자 (frontend developer), 백엔드 개발자 (backend developer), 디자이너 (designer)를 포함한 가상 개발 팀을 구축하고, 실제 상사처럼 이들을 관리할 수 있게 해주는 Harness Engineering 시스템입니다.

당신은 명령을 내립니다. 에이전트 (Agents)는 실행합니다. 훅 (Hooks)은 품질을 강제합니다. 스킬 (Skills)은 프로세스를 표준화합니다. 파일워처 (FileWatcher)는 실시간으로 동기화합니다.

프롬프트 (prompt)에 기도를 할 필요도 없고, "AI가 규칙을 기억하기를 바라기"도 필요 없습니다. 규칙은 훅 (Hooks)에 존재합니다. 규칙을 어기는 에이전트 (Agents)는 차단됩니다. 매우 간단합니다.

• 모든 새로운 세션은 지난 세션에서 학습한 내용을 삭제합니다.
• AI에게 "강제 푸시 (force push) 하지 마"라고 말해도, 다음번에는 다시 잊어버립니다.
• 완벽한 프롬프트 (prompt)를 만드는 데 30분을 소비해도, AI는 처음 세 가지 규칙만 따릅니다.
• 여러 에이전트 (Agents)가 병렬로 작업할 때, 누가 무엇을 변경했는지 아무도 모릅니다.

AgentHub는 "AI가 충분히 똑똑하지 않다"는 문제를 해결하는 것이 아닙니다.
"규율 없는 똑똑한 AI" 문제를 해결합니다.

대부분의 AI 도구는 다음과 같은 논리를 따릅니다: 더 나은 프롬프트 (prompts) 작성 → AI가 준수하기를 기도하기.

AgentHub는 다른 논리를 따릅니다: 텍스트 기도를 아키텍처적 제약 조건 (architectural constraints)으로 대체하기.

기존 AI 도구	AgentHub
"테스트 실행하는 것을 기억해 주세요"	중단 훅 (Stop Hook): 에이전트 (Agent)가 작업을 마치기 전에 반드시 테스트를 통과해야 함
...

나쁜 워크플로 (workflow)를 가진 좋은 검증기 (validator)가, 검증기 없는 좋은 워크플로를 이깁니다.
이것은 슬로건이 아니라 수학입니다: 각 단계의 성공률이 80%인 5단계 과정 = 전체 성공률 33%. 재시도를 허용하는 검증기 (validator)를 추가하면 = 99%.

경주용 자동차에 훌륭한 엔진 그 이상이 필요한 것과 같습니다. 안전벨트, 가드레일, 그리고 피트 스톱 (pit stop) 프로세스가 필요합니다.

에이전트 (Agent)가 실행할 때 관련 가이드를 자동으로 로드하는 재사용 가능한 워크플로 (workflow) 템플릿입니다.

/sop-execute

— L2 실행 SOP: 필수 명세 (spec) 로딩 → 구현 (implement) → 수락 검증 (acceptance verification)

/sop-plan

— L1 계획 SOP: 컨텍스트 (context) 로딩 → 복잡도 분석 (complexity analysis) → 계획 모드 (Plan Mode) 결정 → 작업 분해 (task breakdown)

/sop-review

— L1 검토 SOP (SOP: Standard Operating Procedure): 표준 로드 (load standards) → 코드 리뷰 (code review) → 승인 또는 거절 (approve or reject)/sop-deploy

— 배포 SOP (Deploy SOP): 품질 체크리스트 (quality checklist) → 배포 전 단계 (pre-deploy) → Gate G5/task-dispatch

— Boss는 단 하나의 명령어로 작업을 생성하며, 이는 개발 계획 (dev plan)에 자동으로 기록됩니다/review

— 단계를 자동 감지하여 적절한 리뷰 유형을 선택합니다/pre-deploy

— 배포 전 자동 점검 (CI / 환경 변수 (environment variables) / Docker)/harness-audit

— 7가지 핵심 원칙을 기준으로 주기적인 상태 스캔 (health scan) 및 점수 산정

• ...총 24개의 내장 기술 (Skills)

사후 통보가 아닌 — 실시간 차단 (real-time blocking)입니다. 위험한 작업은 발생하는 즉시 중단됩니다.

PreToolUse: 명령 실행 전 점검 (kill-port / --no-verify / main 브랜치로의 강제 푸시 (force push main) / 잘못된 형식의 커밋 메시지 (malformed commit messages) 차단)
PostToolUse: 파일 수정 후 알림 (핵심 서비스가 변경될 경우, .knowledge/ 문서 동기화를 강제함)
Stop: 종료 전 검증 (테스트 및 타입 체크 (type checks)를 통과해야 하며, 그렇지 않으면 Agent는 종료할 수 없습니다. 또한 누락된 글로벌 기술 (global Skills)을 감지합니다)

Markdown 파일이 데이터베이스 역할을 합니다. .tasks/ 파일을 편집하면 GUI가 즉시 업데이트됩니다.

.tasks/T5.md 파일이 수정됨
→ chokidar가 변경 사항을 감지
→ markdown-parser가 파일을 파싱
...

G0 (요구사항 확인 (Requirements Confirmation)) → G1 (설계 리뷰 (Design Review)) → G2 (코드 리뷰 (Code Review)) → G3 (QA 승인 (QA Acceptance)) → G4 (문서 리뷰 (Documentation Review)) → G5 (배포 준비도 (Deploy Readiness)) → G6 (운영 환경 출시 (Production Release))

통과하지 못하면 진행할 수 없습니다. 의지에 의해 강제되는 것이 아니라 — 아키텍처 (architecture)에 의해 강제됩니다.

다크 테마가 적용된 Electron 데스크톱 앱입니다.

내장된 xterm.js 터미널을 통해 GUI 내부에서 Claude Code Agent와 직접 상호작용할 수 있습니다.

자동 상태 전환 기능이 포함된 5열 칸반 보드 (kanban board)입니다. 카드를 클릭하면 전체 작업 상세 내용을 볼 수 있습니다.

작업 완료율, 활성 스프린트 (Sprint), 최신 Gate 상태를 실시간으로 표시하는 원클릭 Harness 스캐폴딩 (scaffolding)입니다.

모든 Agent는 고유한 역할 정의 (role definition), 권한 범위 (permission scope), 보고 체계 (reporting chain)를 가집니다.

필터링, 통계 및 순위를 한눈에 확인할 수 있는 실시간 Hook 실행 이력입니다.

당신은 Boss(상사)입니다. 당신의 아래에는 다음과 같은 가상 소프트웨어 기업이 있습니다 — 9개 부서, 46명의 Agent (에이전트):

Boss (당신)
├── L1 Leadership (Boss에게 직접 보고)
│ ├── Product Manager (제품 관리자) — 제품 전략 및 로드맵
...

Product (제품)

Agent (에이전트)	Responsibilities (책임)
Product Manager (제품 관리자)	요구사항 관리, Sprint (스프린트) 계획, Gate review (게이트 리뷰)
...

Engineering (엔지니어링)

Agent (에이전트)	Responsibilities (책임)
Tech Lead (기술 리드)	기술적 결정, Code Review (코드 리뷰), architecture design (아키텍처 설계)
...

Design (디자인)

Agent (에이전트)	Responsibilities (책임)
Design Director (디자인 디렉터)	UI/UX 디자인, design system (디자인 시스템) 유지 관리
...

Marketing (마케팅)

Agent (에이전트)	Responsibilities (책임)
Marketing Lead (마케팅 리드)	마케팅 전략 및 조정
...

Testing (테스팅)

Agent (에이전트)	Responsibilities (책임)
QA Lead (QA 리드)	테스팅 전략 및 quality assurance (품질 보증)
...

Project Management (프로젝트 관리)

Agent (에이전트)	Responsibilities (책임)
Project Lead (프로젝트 리드)	프로젝트 일정 관리 및 milestones (마일스톤)
...

Studio Operations (스튜디오 운영)

Agent (에이전트)	Responsibilities (책임)
Operations Lead (운영 리드)	운영 조정
...

Bonus — Special Roles (보너스 — 특수 역할)

Agent (에이전트)	Responsibilities (책임)
Studio Coach (스튜디오 코치)	팀 코칭 및 프로세스 개선 제안
Joker (조커)	창의적 아이디어 구상 및 고정관념을 깨는 사고

모든 Agent (에이전트)는 고유의 역할 정의 파일(agents/definitions/)을 가지며, 권한 범위(permission scope)와 보고 체계 (reporting chain)를 가집니다. L2는 Boss에게 도달하기 위해 L1을 건너뛸 수 없으며, Boss 또한 L2에게 직접 명령하기 위해 L1을 건너뛸 수 없습니다. 실제 기업과 마찬가지입니다.

Layer (계층)	Technology (기술)
Desktop Framework (데스크톱 프레임워크)	Electron 35
...

AgentHub는 **Claude Code를 기반으로 구축된 관리 프레임워크 (management framework)**입니다. 모든 실제 Agent (에이전트) 작업은 Claude Code CLI를 통해 실행됩니다.

요구 사항	버전	비고
Node.js	>= 18	Electron 및 프론트엔드 빌드에 필요 (LTS 권장)
npm	>= 9	Node.js와 함께 설치되며, 패키지 관리 (package management)에 사용됨
Claude Code	최신 버전	Anthropic의 공식 CLI 도구이자 AgentHub의 AI 엔진. 반드시 먼저 설치 및 인증되어야 함.
Git	>= 2.30	버전 관리 (version control), 프로젝트 클로닝 및 에이전트 (Agent) 작업에 필요
Python	>= 3.8	node-pty 네이티브 모듈 컴파일에 필요 (Windows)
C++ Build Tools	—	node-pty 네이티브 모듈 컴파일에 필요 (아래 플랫폼 설정 참조)

Windows

# Windows 빌드 도구 설치 (관리자 권한 PowerShell)
npm install --global windows-build-tools
# 또는 Visual Studio Build Tools를 수동으로 설치 (

AgentHub의 이면에 있는 멘탈 모델(mental model) — 왜 프롬프트(prompts) 대신 훅(Hooks)을 사용하는지, 왜 SOP 문서보다 스킬(Skills)이 더 효과적인지, 왜 게이트(Gate) 체크포인트가 성공률을 33%에서 99%로 끌어올릴 수 있는지 — 를 이해하고 싶다면, 이 코스가 시작하기에 가장 좋은 곳입니다:

**Claude Code Mastery** — 자율적인 에이전트 팀(Agent teams) 구축을 위한 기초부터 완성까지의 가이드
**Read Online** — 간편한 브라우징을 위한 웹 버전

Claude Code의 기초부터 5단계 진화 모델(수동 운영(Manual Operation) → 프롬프트 엔지니어링(Prompt Engineering) → 하네스 엔지니어링(Harness Engineering) → 자율 에이전트(Autonomous Agents) → 에이전트 팀(Agent Teams))에 이르기까지 8개 모듈과 23개 챕터를 다룹니다. 모듈 6은 AgentHub에서 사용되는 하네스 엔지니어링(Harness Engineering) 아키텍처를 전문적으로 다룹니다.

AgentHub를 단독으로 사용할 수도 있고, 코스와 병행하여 모든 설계 결정 뒤에 숨겨진 "이유"를 이해할 수도 있습니다.

워크플로우가 나쁜 훌륭한 검증기(validator)가 검증기 없는 훌륭한 워크플로우보다 낫습니다.

**백과사전이 아닌 지도를 제공하라** — CLAUDE.md는 인덱스(index)이지 전체 사양서(specification)가 아닙.
**프롬프트가 아닌 도구로 강제하라** — 금지된 명령은 문서가 아닌 훅(Hooks)에 존재합니다.
**지식은 복리로 쌓인다** — 사후 분석(Postmortem) 노트는 자동으로 수집되어 프로젝트 전반에 피드백되고 새로운 프로젝트로 상속됩니다.
**프로세스는 반복 가능하다** — 스킬(Skills)은 모든 단계를 표준화하여 개인의 기억에 대한 의존성을 제거합니다.
**품질은 보장된다** — 게이트(Gate) 체크포인트와 훅(Hook) 가로채기(interception)가 이중 보호 계층을 제공합니다.

**프로젝트 관리 (Project Management)**

- 하위 프로젝트가 생성될 때 완전한 하네스(Harness) (CLAUDE.md + .knowledge/ + Skills + Hooks)를 자동으로 스캐폴딩(scaffolds)합니다.
- 4가지 프로젝트 템플릿을 지원합니다 (web-app / api-service / library / mobile-app).
- 프로젝트 카드는 실시간 작업 완료율, 활성 스프린트(Sprint), 최신 게이트(Gate) 상태를 표시합니다.

**세션 및 터미널 (Sessions & Terminal)**

- GUI 내부에서 Claude Code 세션을 직접 열 수 있도록 xterm.js 터미널이 내장되어 있습니다.
- 에이전트 정의 파일이 자동으로 로드되어, 각 세션에 관련 에이전트의 역할과 표준을 가져옵니다.
- 세션 기록 및 토큰 사용량 추적 기능을 제공합니다.

**작업 보드 (Task Board)**

- 5열 칸반 (Five-column kanban): Created → Assigned → In Progress → In Review → Done
- 에이전트(Agents)는 `/task-start`, `/task-done`, `/task-approve` 명령어를 통해 하위 프로젝트의 상태를 업데이트합니다.

**기술 (Skills)** - 작업 파일은 스프린트(Sprint) 하위 디렉터리 규칙을 따릅니다:
`.tasks/sprint-{N}/TN-xxx.md`

- 파일 변경 → chokidar가 감지 → markdown-parser가 파싱 → DB 동기화 → GUI 실시간 업데이트

**하네스 시스템 (Harness System)**

**24개의 기술 템플릿 (Skill templates)**: SOP 준수 (sop-plan / sop-execute / sop-review / sop-deploy), 스프린트 제안, 작업 배정, 코드 리뷰 (Code Review), 게이트 기록 (Gate records), 배포 전 점검 등

**6개의 훅 템플릿 (Hook templates)**: forbidden-commands (위험한 명령어 차단), git-commit-check (Conventional Commits 유효성 검사), stop-validator (중단 전 테스트 및 타입 체크 유효성 검사), g1/g4/g5 품질 게이트 (quality gate) 점검

- 기술(Skills)은 `scripts/install-skills.sh`를 통해 `~/.claude/commands/`에 전역적으로 설치되어 프로젝트별 중복 설치가 필요하지 않습니다.
- 훅(Hooks)은 프로젝트 생성 시 하위 프로젝트의 `.claude/` 디렉터리에 자동으로 배포됩니다.
- GUI를 통해 훅을 탐색, 추가 및 편집할 수 있으며, 전역(global) 및 프로젝트(project) 범위 모두를 지원합니다.

**게이트 품질 체크포인트 (Gate Quality Checkpoints)**

- G0–G6 총 7개의 체크포인트가 있으며, 개발 계획(dev-plan)의 섹션 10에 변경 사항이 생기면 GUI에 실시간으로 동기화됩니다.
- 파이프라인 뷰(Pipeline view)를 통해 각 체크포인트의 리뷰 상태를 확인할 수 있습니다.

**지식 베이스 (Knowledge Base)**

- 실시간 마크다운(Markdown) 미리보기를 통해 `.knowledge/` 디렉터리 트리를 탐색할 수 있습니다.
- 회사 표준(coding-standards, api-standards, testing-standards)이 중앙에서 관리됩니다.

**워크플로우 (Your workflow):** GUI에서 세션(Session)을 엽니다 → 에이전트(Agent)에게 명령을 내립니다 → 에이전트는 기술(Skills)의 안내를 받고 훅(Hooks)의 제약을 받으며 하위 프로젝트 내부에서 작업합니다 → 파일 변경 사항이 즉시 GUI로 동기화됩니다 → 사용자가 결과를 검토하고 게이트(Gates)를 승인합니다.

**자동화된 지휘 체계 (Automated Chain of Command)**: Boss가 하나의 지시를 내리면, PM이 이를 자동으로 세분화하여 TL과 DD에게 배정합니다 — 수동 전달 과정이 필요 없습니다. 
**병렬 세션 (Parallel Sessions)**: 자동 작업 할당 및 조율을 통해 여러 Agent 세션을 동시에 실행합니다. 
**런타임 가드레일 (Runtime Guardrails)**: TypeScript 엔진이 실시간으로 차단합니다 — 단순한 CLI 명령뿐만 아니라 코드 로직까지 포함합니다. 
**교차 프로젝트 지식 네트워크 (Cross-Project Knowledge Network)**: 프로젝트 A에서 발견된 함정(Pitfall)이 자동으로 모든 신규 프로젝트를 위한 보호 규칙이 됩니다. 

노트북을 열면 대시보드에 다음과 같은 상황이 표시됩니다 — 3개의 스프린트(Sprints) 진행 중, 12개의 작업이 서로 다른 Agent들에게 할당됨, Tech Lead가 방금 코드 리뷰(Code Review)를 마침, PM은 게이트(Gate) 리뷰를 준비 중, 그리고 한 Agent가 테스트를 건너뛰려 했으나 Stop Hook이 이를 차단하고 스스로 수정함. 

당신의 업무: 의사 결정, 결과물 검토, 방향 설정. 당신의 업무가 아닌 것: 프롬프트 기도(Prompt prayers) 작성, 수동 테스트 실행, 누군가 편법을 쓰는지 걱정하기. 

**이것이 AgentHub입니다.** 

- Agent 아키텍처 설계는 contains-studio/agents에서 영감을 받았습니다. 

MIT