GitHub Issues 및 Projects 기반의 자동화된 Claude Code SDLC 드라이버, Fabrik

Fabrik은 GitHub Project 보드를 감시하고 구성 가능한 워크플로우 단계를 통해 Claude Code를 구동합니다. 이슈(Issues)가 작업 단위이며, 이슈 본문이 명세서(spec)이고, 댓글은 사용자 입력이며, 보드 컬럼들이 워크플로우를 정의합니다.

📖 문서, 가이드 및 예제 → fabrik.handarbeit.io

Go 1.26.1 이상, Claude Code CLI, 그리고 repo와 project 스코프가 포함된 GitHub 토큰이 필요합니다.

# 설치
go install github.com/handarbeit/fabrik@latest
# 스테이지 설정(stage configs), 플러그인 및 프로젝트 설정 템플릿 초기화
...

구성 요약:

.fabrik/config.yaml
— 비(非)비밀 프로젝트 설정 (git에 커밋)
.env
— 비밀 정보만 포함 (FABRIK_TOKEN/GITHUB_TOKEN; 반드시 gitignore 처리해야 함)- 우선순위: CLI 플래그 > 환경 변수(env var) > .env > config.yaml > 기본값(defaults)

--auto-upgrade를 사용하면 Fabrik이 시작 시와 유휴 상태일 때 자체적으로 업그레이드됩니다:

fabrik --auto-upgrade ...

시작 시 및 2회 유휴 폴링(idle polls) 후, Fabrik은 자동으로 자신을 업그레이드하고 재실행합니다:

릴리스 바이너리(Release binaries): GitHub Releases에서 새 버전을 확인하고 다운로드합니다.개발 빌드(Dev builds) (go build를 통해 소스에서 빌드): 실행 중인 바이너리보다 앞선 로컬 또는 원격 커밋을 감지하고 origin/main으로부터 제자리에서 재빌드합니다.

Fabrik이 업그레이드될 때, .fabrik/stages/*.yaml 파일도 내장된 기본값과 비교하여 새 바이너리에 추가된 필드가 누락된 스테이지 파일에 대한 시작 경고를 출력합니다. fabrik refresh-stages --apply를 실행하여 누락된 키를 추가한 다음, git diff로 검토하고 커밋하십시오. 자세한 내용은 사용자 가이드의 Stage YAML Drift Warning을 참조하십시오.

아직 바이너리를 설치하고 싶지 않으신가요? 대화형 Claude Code 세션에서 Fabrik PM 플러그인을 설치하여 여전히 Fabrik의 가치를 얻을 수 있습니다. 이 플러그인은 Claude에게 Fabrik이 관리하는 프로젝트에 대한 주변 인지(ambient awareness)를 제공하여, 편집기를 벗어나지 않고도 *

이 명령어들을 모든 Claude Code 세션에서 실행하세요:

/plugin marketplace add handarbeit/fabrik
/plugin install fabrik@fabrik
/reload-plugins

설치 후 다음 기능들을 얻게 됩니다:

— fabrik:fabrik skill이 감지되거나 Fabrik이 언급되면 자동 활성화됩니다. 보드, 단계(stages), 그리고 정체된 항목(stuck items)에 대한 주변 PM 인식(ambient PM awareness)을 제공합니다.
— Fabrik을 처음부터 설정하기 위한 일회성 온보딩 워크스루입니다 (fabrik:fabrik-setup skill).
— 보드 스냅샷: 각 파이프라인 단계에 무엇이 있는지, 어떤 작업자(workers)가 실행 중인지, 어떤 작업 트리(worktrees)에 커밋되지 않은 변경 사항이 있는지 확인합니다 (/fabrik:status command).

PM 플러그인은 엔진과 독립적입니다. Fabrik으로 관리되는 저장소에 대해 채팅하려면 자체적으로 설치하거나, 전체 경험을 위해 바이너리와 페어링하여 사용하세요. 자세한 내용 및 업그레이드 지침은 사용자 가이드의 'Install the Fabrik PM Plugin'을 참조하세요.

참고: 엔진의 단계(stage) skill들은 바이너리에 내장되어 있으며 fabrik init에 의해 자동으로 .fabrik/plugin/에 배포됩니다. 사용자가 직접 fabrik-workflows를 설치해서는 안 됩니다.

또 다른 선택적 Claude Code 플러그인으로, 엔지니어보다는 제품 관리자(Product Manager)나 비즈니스 오너에게 초점을 맞추었습니다. 터미널, git 또는 기술적인 배경 지식이 필요하지 않습니다. 이 플러그인은 프로젝트의 목표, 사용자, 범위(scope), 제약 조건(constraints), 그리고 어휘에 대해 인터뷰를 진행한 다음, 개별 기능 아이디어를 표준 GitHub Spec Kit 폴더(specs/NNN-feature-name/)로 변환하여 Fabrik이 빌드할 준비가 되도록 합니다.

/plugin marketplace add handarbeit/fabrik
/plugin install entwurf@fabrik

이는 fabrik init에 의해 설치되지 않습니다. 전체 skill 목록, 설치 옵션 및 출처(attribution)는 사용자 가이드의 Entwurf Plugin을 참조하세요.

GitHub 프로젝트 보드 (진실의 원천)
| GraphQL 폴링
Fabrik (Go CLI, 로컬에서 실행)
...

폴링(Poll): Fabrik은 단일 GitHub GraphQL 쿼리를 통해 전체 프로젝트 보드를 가져옵니다.
매치(Match): 각 이슈의 보드 상태는 단계 설정 파일(YAML file)과 매칭됩니다.
작업 트리(Worktree): 각 이슈에 대해 격리된 git 작업 트리가 생성됩니다 (fabrik/issue-N).

branch).Invoke(호출)— Claude Code는 스테이지의 프롬프트, 모델 및 도구 구성을 사용하여 작업 트리(worktree) 내에서 실행됩니다.Complete(완료)— Claude가 완료를 알리면, 해당 이슈에 stage:<name>:complete 레이블이 지정됩니다.

.Advance(진행)— yolo 모드에서는 이슈가 다음 스테이지로 자동 진행됩니다. 그렇지 않은 경우, 사람이 수동으로 이동시킵니다.

Big-board 효율성 개선 (v0.0.57): 대규모 프로젝트 보드에서, 가벼운 updatedAt 전용 프로브(probe)를 통해 GraphQL 비용이 약 5–10배 감소합니다. 이 프로브는 전체 심층 검색(deep-fetch)을 제어하며, 마지막 폴링 이후 변경된 항목만 전체 쿼리를 유발합니다. 터미널 항목(cleanup/Done 열에 있으며 stage:<name>:complete 레이블이 있고 활성 라이프사이클 레이블이 없는 이슈)은 프로브와 심층 검색 평가 모두에서 완전히 건너뜁니다.

콜드 스타트 최적화 (v0.0.58): 시작 시, 완료된 Done 항목들은 깊은 검색 없이 프로브 데이터로부터 터미널로 설정되어 콜드 스타트 GraphQL 비용을 약 80–90% 절감합니다. 이는 프로브 기반 폴링과 결합하여 단일 토큰 예산으로 두 개의 Fabrik 인스턴스를 실행하는 것을 실용적으로 만듭니다.

Anthropic 인증 네임스페이스 정리 (v0.0.77): 모든 워커 호출 환경은 기본적으로 Anthropic/Claude-Code 인증 네임스페이스에서 제거됩니다 (ANTHROPIC_* 와일드카드 및 열거된 CLAUDE_CODE_* 인증 선택기 목록). 따라서 엔진 환경에 있는 주변적인 ANTHROPIC_API_KEY는 더 이상 구독 결제에서 측정형 API 결제로 스테이지를 조용히 리디렉션할 수 없습니다. FABRIK_ANTHROPIC_API_KEY만이 API 결제를 위한 유일하게 지원되는 옵트인 방식이며, apiKeyHelper는 시작 시와 호출당 모두 전면 거부됩니다. 자세한 내용은 Anthropic Auth Namespace Scrub 및 apiKeyHelper의 사용자 가이드를 참조하십시오.

GitHub Enterprise Server 지원 (v0.0.78): Fabrik은 github.com 대신 GHES 인스턴스에 대해서도 실행될 수 있습니다. 이는 순수한 엔드포인트/호스트 구성이며 어댑터 계층이 필요 없습니다. --ghes-host / FABRIK_GHES_HOST (또는 .fabrik/config.yaml의 ghes_host)를 설정하면 Fabrik이 독립적으로 REST (/api/v3/...) 및 GraphQL (/api/graphql)을 파생합니다.

) endpoints, points bare-clone URLs and commit noreply emails at your host, 그리고 모든 스테이지 워커의 gh CLI 호출에 GH_HOST를 전파하여 동일한 인스턴스를 대상으로 하도록 합니다. GHES 구성이 없는 경우 동작은 변경되지 않습니다. 사용자 가이드의 GitHub Enterprise Server 지원을 참조하십시오.

Fabrik은 백그라운드 서브프로세스로 gh webhook forward를 생성함으로써 다음 폴링 주기(poll tick)를 기다리는 대신 거의 실시간으로 (약 2초 이내) GitHub 이벤트를 수신할 수 있습니다. --webhooks로 활성화하십시오. 기본 인메모리 보드 캐시가 활성화된 경우, 웹훅 스트림은 또한 조정 기반 상태 확인(reconcile-based health check)을 구동하여 (기본 3분마다) 전체 보드 폴링 빈도를 최대 60분에 한 번으로 줄입니다.

단일 사용자 제약 사항: GitHub는 리포지토리 또는 조직당 활성 gh webhook forward 구독을 하나만 허용합니다. 팀원 간에 조율하여 --webhooks를 사용하는 Fabrik 인스턴스가 하나만 실행되도록 하십시오. 다른 인스턴스는 이것 없이도 실행될 수 있으며 폴링을 통해 여전히 이슈를 처리할 것입니다. 전체 설정, 구성 및 문제 해결 세부 정보는 사용자 가이드의 §10을 참조하십시오.

GitHub App 인증: --webhooks는 GitHub App 인증과 결합될 수 없습니다. 다중 리포지토리 포함 앱 인증 설정은 대신 Hookdeck을 통해 거의 실시간 전송을 받을 수 있습니다 (--event-source hookdeck); 어느 쪽이든 폴링이 안전장치 역할을 합니다. Hookdeck을 통한 이벤트 기반 수집(Event-Driven Ingestion)을 참조하십시오.

strict 브랜치 보호가 적용된 리포지토리에서 여러 준비된 PR을 순차적으로 배포하면 O(N²)의 리베이스 및 재테스트 연쇄 반응이 발생합니다. 각 병합은 다른 모든 준비된 PR의

GitHub의 네이티브 병합 대기열(ADR-058) — 리포지토리에 활성화된 경우 자동으로 사용됩니다(Enterprise Cloud 또는 org 소유 공개 리포). 비활성화 스위치: --merge-queue off

.Fabrik의 내부 병합 트레인(ADR-059) — GitHub의 네이티브 대기열을 사용할 수 없는 개인 팀 및 개인 계정 리포지토리를 위한 계획 및 호스트에 구애받지 않는 대체 방안입니다. 이는 각 (repo, base) 파티션별로 시험 브랜치를 준비합니다. 하나의 리포지토리에서 여러 개의 동시 트레인을 실행할 수 있으며, base:<branch>가 다른 브랜치들을 대상으로 하는 항목들일 경우에 가능합니다. 이 방식은 파티션당 한 번의 통합 검증(Validate)을 실행하고 배치(batch)를 원자적으로 적용하며, 빨간색 배치는 절반 분할법(halving bisection)을 통해 격리되어 단 하나의 문제 발생 요소가 나머지 전체를 차단하지 않도록 합니다. 정확히 하나의 항목만 파티션에 대기열될 경우, Fabrik은 시험 과정을 건너뛰고 해당 항목의 PR이 베이스로부터 빠르게 전진(fast-forward)하고 병합 가능하며 CI가 녹색일 때 직접 적용합니다. 이는 --merge-train on, FABRIK_MERGE_TRAIN=on, 또는 .fabrik/config.yaml에서 merge_train: on을 통해 선택적으로 활성화할 수 있습니다.

네이티브 대기열 라우팅은 기본값으로 auto입니다(GitHub의 네이티브 대기열이 이미 활성화된 리포지토리에서만 작동). 병합 트레인은 기본값이 off입니다. 둘 다 명시적으로 켜지 않는 한 기존의 직렬 자동 병합 경로를 건드리지 않습니다. 설정 방법(필요한 Queued 보드 열 포함) 및 조정 가능한 노브는 사용자 가이드의 Merge Queue 및 Merge Train / Queued 섹션을 참조하십시오.

누군가 활성 단계의 이슈에 댓글을 달 때:

• Fabrik은 새로운 댓글마다 👀로 반응합니다(

모든 작성자의 댓글이 처리를 유발합니다. 여기에는 인간 동료, 코드 리뷰 봇(Copilot, Gemini) 및 기타 Fabrik 인스턴스가 포함됩니다. 건너뛰는 카테고리는 두 가지뿐입니다:

🏭 **Fabrik으로 시작하는 댓글 (Fabrik 자체 출력)

그리고 이미 🚀 로켓 반응을 가지고 있는 댓글 (이미 처리됨).

이를 통해 반복적인 개선이 가능합니다. 질문에 답변하거나, 피드백을 제공하거나, 작업을 안내하기 위해 댓글을 달면 Fabrik은 해당 입력을 이슈에 통합합니다.

post_to_pr: true가 설정된 단계(기본 검토(Review) 단계와 같음)는 연결된 PR에 상세한 출력을 게시하고 이슈에는 간략한 요약을 게시합니다. 또한, 검토(Review) 단계는 구성된 기본 브랜치로 리베이스(rebase)하고 리뷰 전에 병합 충돌을 해결하여 PR 브랜치를 깨끗하게 유지합니다.

검토(Review) 및 유효성 검사(Validate) 단계는 기본적으로 wait_for_reviews: true가 활성화되어 있습니다. 이 옵션이 설정되면 Fabrik은 3단계의 리뷰어 게이트를 사용합니다 (재호출은 무조건 발생하며, 다음 단계로 자동 진행하려면 여전히 자동 진행이 활성화되어야 합니다):

항상 게이트(Always-gate): 단계 완료 시, Fabrik은 fabrik:awaiting-review를 추가하고 게이트가 해제될 때까지 자동 진행을 보류합니다.게이트 평가(Gate evaluation): 각 후속 폴링마다 Fabrik은 두 가지 조건을 확인합니다. 요청된 리뷰어가 미결 상태가 아니어야 하며 그리고 최소한 하나의 리뷰가 제출되었어야 합니다 (이는 Copilot 및 Gemini와 같은 봇 리뷰어가 공식 리뷰어 목록에 나타나지 않고 웹훅을 통해 자체적으로 트리거하는 경우를 포착합니다). 조건이 충족되지 않고 주기적 시간 초과가 만료되면, 이슈는 fabrik:awaiting-input 상태로 일시 중지됩니다.

재호출(Re-invocation): 게이트가 해제되면, Fabrik은 해결되지 않은 인라인 PR 리뷰 스레드 댓글을 처리하고 그리고 상태가 DISMISSED / PENDING가 아닌 모든 리뷰의 최상위 본문을 다루기 위해 단계 에이전트를 재호출합니다. (CHANGES_REQUESTED, COMMENTED, 및 APPROVED 본문은 모두 잠재적으로 조치가 가능한 것으로 간주됩니다 — 이것이 Pruefer와 같은 봇 리뷰어가 전체 발견 세트를 COMMENTED로 제출할 수 있게 하는 것입니다.)

검토(review)되고 처리되어 조용히 방치되는 것을 막고, 다음 검토 라운드를 기다립니다. 인라인 댓글이 없는 진정으로 비어 있는 APPROVED 검토는 전송할 내용이 없으므로 재호출(re-invocation)은 건너뛰어지고 이슈는 정상적으로 진행됩니다.

각 재호출 주기 이후, Fabrik은 각 인라인 검토 스레드가 어떻게 처리되었는지 목록을 포함하는 PR 요약 댓글을 게시합니다.

설정:
--max-review-cycles/FABRIK_MAX_REVIEW_CYCLES (기본값 5)는 세션당 재호출 주기의 최대 횟수를 제한합니다.
--review-wait-timeout/FABRIK_REVIEW_WAIT_TIMEOUT (기본값 15분)은 일시 정지하기 전 주기별 대기 시간을 설정합니다. 환경 변수는 해당 CLI 플래그가 없을 때만 참조됩니다; 만약 --review-wait-timeout=0 또는 --max-review-cycles=0