가재코드(gjc) 실전 사용법: 설치와 네 가지 스킬 쓰는 법

가재코드(Gajae-Code)는 gjc 명령으로 실행하는 외부 코딩 에이전트 하네스입니다. 다른 에이전트에 끼워 넣는 플러그인이 아니라, 저장소나 worktree 를 골라 그 자리에서 따로 뜨는 실행기입니다. 이 글은 제품 소개가 아니라 사용법입니다. 설치를 끝내고 gjc 를 처음 띄운 사람이 무엇부터 확인해야 하는지, 그리고 번들된 네 가지 스킬을 각각 어떤 상황에서 부르는지를 정리했습니다.

베타라는 전제와 이 도구의 위치

먼저 밝힐 것이 있습니다. README 앞머리에 경고가 그대로 박혀 있습니다. "Gajae-Code is an experimental, beta-stage project. Expect rough edges and verify outputs before relying on it for important work." 실험 단계이고 거친 부분이 있으니 중요한 작업에 그대로 기대기 전에 결과를 검증하라는 뜻입니다. 저장소는 2026년 5월 26일에 생겼고, 이 글을 쓰는 2026년 8월 7일 기준 npm 최신 버전은 0.12.15 입니다. 버전대가 말해 주는 그대로 아직 굳은 물건이 아닙니다.

그러니 쓰는 방식도 거기에 맞춰야 합니다. 에이전트가 만든 diff 를 읽지 않고 커밋하거나, 확인 없이 배포 스크립트를 돌리는 식으로 쓰면 안 됩니다. 뒤에 나올 worktree 격리와 ultragoal 의 증거 기록이 실제로 값을 하는 이유도 여기 있습니다. 라이선스는 MIT 이고 본체는 TypeScript 로 쓰였습니다.

위치도 분명합니다. README 는 "It is intentionally not a hidden plugin for Codex CLI, Claude Code, OpenCode, or Claw Code" 라고 못 박습니다. 다른 에이전트의 런타임을 패치하지 않고, 고른 저장소나 worktree 에서 별도로 실행됩니다. 이미 쓰던 도구를 버릴 필요가 없다는 뜻입니다. 계획을 검토받거나, 증거를 남기거나, tmux 작업자를 붙이고 싶을 때 그 옆에 gjc 를 하나 더 띄우는 구조입니다. 기본 흐름은 이렇게 생겼습니다.

deep-interview -> ralplan -> ultragoal
                         └─ 병렬 tmux 작업자가 값을 할 때만 team 을 곁들임

가재코드 저장소 열기공식 사이트 둘러보기

설치와 첫 실행 확인

런타임은 Bun 입니다. npm 패키지 메타데이터의 engines 필드가 bun >=1.3.14 로 잡혀 있으니, Bun 이 없거나 오래됐다면 그것부터 처리해야 합니다. 설치는 한 줄입니다.

bun install -g gajae-code

gajae-code 는 스코프 없이 설치하려고 만든 얇은 래퍼이고, 실제 본체는 @gajae-code/coding-agent 입니다. 조직 스코프를 직접 쓰고 싶으면 bun install -g @gajae-code/coding-agent 로 받아도 됩니다. 미리 빌드된 단독 실행 바이너리는 Linux(x64, arm64), Windows(x64), macOS(arm64, x64)로 배포됩니다. 그 밖의 환경은 npm/Bun 경로나 소스 빌드로 갑니다.

macOS 는 Apple Silicon 과 Intel 양쪽 바이너리가 모두 나옵니다. 소스에서 받고 싶다면 설치 스크립트에 --source 를 넘기는 경로가 따로 있습니다.

curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/gajae-code/main/scripts/install.sh | sh -s -- --source

Windows 는 Bun 부터 깔고 시작합니다. 순서를 지키지 않으면 gjc 가 PATH 에서 안 잡힙니다.

powershell -c "irm bun.sh/install.ps1|iex"
bun --version
bun install -g gajae-code
gjc --version
gjc --smoke-test

bun install -g 은 런처를 %USERPROFILE%\\.bun\\bin 에 놓습니다. Bun 설치기가 PATH 에 자동으로 넣지만 변경은 설치 이후에 새로 연 터미널에만 반영되므로, "not recognized" 가 뜨면 PowerShell 을 다시 켜 보는 것이 먼저입니다. 플랫폼과 무관하게 gjc --version 과 gjc --smoke-test 두 개는 꼭 통과시키고 넘어가세요. 스모크 테스트는 네이티브 바인딩이 제대로 로드되는지를 봅니다. 여기서 실패하면 스킬이 안 돕니다.

처음 켠 뒤: 기본값 점검과 실행 옵션

설치 직후에 할 일은 번들된 기본 워크플로가 어떻게 생겼는지 읽어 보는 것입니다. 덮어쓰기 전에 확인하는 순서를 권합니다.

gjc skills list
gjc skills read ralplan
gjc setup defaults --check

gjc setup defaults 는 네 가지 기본 워크플로 스킬을 사용자 .gjc 디렉터리에 설치하며, 이미 있는 로컬 파일은 기본적으로 보존합니다. --check 가 빠진 파일이나 달라진 파일을 알려 주면 gjc skills read <이름> 으로 소스에 박힌 원본과 먼저 비교하세요. 로컬 기본 스킬 파일을 정말로 갈아엎을 생각일 때만 gjc setup defaults --force 를 씁니다. 기본 정의가 소스에 번들돼 있어서, 프로젝트에 .gjc 디렉터리가 없어도 워크플로 표면 자체는 사라지지 않습니다. 런타임 상태와 스펙, 계획, 목표, team 상태는 .gjc/ 아래에 쌓입니다.

실행 방식은 세 갈래입니다. 그냥 gjc 는 현재 체크아웃에서 바로 뜹니다. gjc --tmux 는 tmux 리더 세션을 씁니다. 오래 걸리는 검증이나 나중에 스크롤백을 다시 봐야 하는 작업에 맞습니다. 위험하거나 리뷰가 필요한 작업은 격리된 worktree 로 보냅니다.

gjc
gjc --tmux
gjc --tmux --worktree my-task-branch
cd ../my-task-worktree && gjc --tmux

--worktree 인자는 파일 경로가 아니라 브랜치 비슷한 이름입니다. 이 점을 헷갈리면 엉뚱한 디렉터리가 생깁니다. 이미 만들어 둔 worktree 디렉터리가 있다면 인자로 넘기지 말고 거기로 cd 한 다음 gjc --tmux 를 띄우면 됩니다. Nginx 액티브 헬스체크 모듈을 소스에서 패치해 설치하는 것처럼 빌드 산출물이 잔뜩 쌓이고 중간에 갈아엎을 일이 잦은 작업은 worktree 안에서 굴리는 편이 원본 체크아웃에 안전합니다.

Windows 네이티브에는 제약이 하나 있습니다. --tmux 의 세션·team 보장을 받으려면 PATH 에 tmux 호환 실행 파일이 있어야 합니다. README 는 WSL 의 진짜 tmux 를 권하고, 네이티브 psmux 는 tmux/pmux/psmux 명령을 제공하긴 하지만 GJC 소유권 태그와 team 보장 쪽은 아직 완전히 지원되는 경로가 아니라고 적어 두었습니다.

deep-interview 와 ralplan: 코드를 건드리기 전

세션 안에서 쓰는 공개 표면은 이 네 줄이 전부입니다.

/skill:deep-interview clarify ambiguous requirements
/skill:ralplan build and critique the implementation plan
gjc ultragoal create-goals --brief-file <approved-plan>
gjc ultragoal complete-goals

deep-interview 는 요구사항이 흐릴 때 씁니다. 소크라테스식으로 한 번에 한 질문만 던지고, 매 라운드 가장 약한 명료도 차원을 지목해 그쪽을 파고듭니다. 모호성 점수가 임계값 아래로 떨어지고 사용자가 실행 경로를 명시적으로 승인하기 전까지는 실행으로 넘어가지 않습니다. 결과 스펙은 .gjc/_session-{sessionid}/specs/ 아래에 남습니다. 시작 인자로 --quick, --standard, --deep 를 골라 깊이를 조절하고, 인터뷰 전에 조사 단계를 한 번 넣고 싶으면 --trace 를 붙입니다.

더 쓸모 있는 건 언제 부르지 말아야 하는지입니다. 스킬 정의에 아예 항목으로 적혀 있습니다.

• 파일 경로·함수 이름·수용 기준이 이미 잡힌 구체적 요청
• 범위가 작고 위험이 낮은 명확한 구현 건
• 선택지를 넓게 훑거나 브레인스토밍하려는 상황(이때는 ralplan)
• 한 줄 수정이나 빠른 버그픽스
• 이미 PRD 나 계획 파일이 있고 그것을 실행해 달라는 요청

ralplan 은 코드를 건드리기 전에 계획을 세우고 스스로 깎는 단계입니다. planner, architect, critic 세 역할이 합의에 이를 때까지 돌립니다. 여기가 planning 전용 구간이라는 계약이 코드 레벨에서 강제됩니다. 승인 전에는 제품 소스를 고치지 않고, 변경을 일으키는 셸도 돌리지 않으며, 커밋·푸시·PR 도 만들지 않습니다. 산출물은 .gjc/_session-{sessionid}/plans/ralplan/<run-id>/ 아래 단계별로 쌓이고 최종본이 pending-approval.md 로 복사됩니다.

플래그가 실제 판단에 영향을 줍니다. --interactive 는 초안 검토 프롬프트와 하나씩 조율하는 절차를 추가합니다. --deliberate 는 사전 부검(pre-mortem)과 확장된 테스트 계획을 강제하는데, 인증·보안, 마이그레이션, 파괴적 작업, 장애 대응, 규정·개인정보, 공개 API 파손 위험이 걸리면 자동으로 켜지기도 합니다. 예를 들어 EKS 에서 Vault Raft 클러스터가 깨져 Pod 와 PVC 를 지우고 다시 세우는 종류의 작업이라면, 손대기 전에 pre-mortem 한 번 돌리는 비용은 충분히 값을 합니다. 계획이 끝난 뒤 자동으로 다음 단계에 넘길지는 gjc.ralplan.autoHandoff 로 정하는데 기본값이 off 입니다. 넘기려면 명시적으로 켜야 합니다.

ultragoal 과 team: 증거를 남기고 필요할 때만 병렬로

ultragoal 은 승인된 계획을 목표로 바꿔서 실행·수정·검증·증거까지 추적합니다. 자주 쓰는 명령은 이 정도입니다.

gjc ultragoal status
gjc ultragoal create-goals --brief-file <path>
gjc ultragoal complete-goals
gjc ultragoal complete-goals --retry-failed
gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>"

구조를 알아 두면 디버깅이 쉬워집니다. 세션 디렉터리 아래에 brief.md, goals.json, ledger.jsonl 세 파일이 생깁니다. goals.json 이 목표 정체성과 상태의 기준이고, ledger.jsonl 이 체크포인트·영수증·블로커·검토 기록이 쌓이는 증거 스트림입니다. 완료 판정은 이 영속 파일들과 새로 찍힌 영수증만 보고 내리며, 세션 안의 인라인 목표 상태는 판정 근거로 쓰지 않습니다. 브리프 하나에 여러 스토리를 넣으려면 @goal: 구분선으로 나눕니다. 쿠버네티스 인증서 만료를 확인하고 kubeadm certs renew 로 갱신하는 작업처럼 노드마다 같은 절차를 반복하고 단계마다 확인 결과를 남겨야 하는 일이 이 모양에 잘 맞습니다.

team 은 마지막에 붙습니다. 현재 tmux 리더 창을 쪼개서 진짜 GJC 워커 세션을 띄우고, 상태 파일과 gjc team api 로 조율합니다.

gjc team "debug flaky integration tests"
gjc team 3:executor "analyze feature X and report flaws"

경계가 스킬 정의에 적혀 있습니다. 리더 스레드 하나가 독립된 하위 작업 몇 개로 갈라졌다가 바로 기다리면 되는 정도면 세션 안의 네이티브 서브에이전트로 충분합니다. gjc team 은 눈에 보이는 tmux 워커, 공유 작업 상태, 워커 메일박스, worktree, 명시적 생명주기 제어가 필요하거나, 한 번의 추론 흐름보다 오래 사는 실행이 필요할 때 씁니다. 반대로 tmux 밖 세션에서는 team 을 바로 쓸 수 있는 것처럼 다루지 않고, gjc team 이 없으면 조용히 대체하지 않고 하드 에러로 멈춥니다. 병렬이 값을 하지 않는 작업에 team 을 부르면 창만 늘고 얻는 게 없습니다.

설정, 알림, 상태가 깨졌을 때

재시도 예산은 ~/.gjc/config.yml 에 있습니다. 네트워크가 불안정한 환경이면 이 값부터 손보게 됩니다.

retry:
  requestMaxRetries: 4
  streamMaxRetries: 100
  maxRetries: 3
  maxDelayMs: 300000

requestMaxRetries 는 스트림이 열리기 전 단계에, streamMaxRetries 는 재생이 안전한 일시적 스트림 실패에만 적용됩니다. 인증 실패, 지원하지 않는 모델이나 제공자, 잘못된 요청, 컨텍스트 초과, 사용자 중단, 영구적인 할당량 실패는 재시도하지 않고 바로 떨어집니다. 어떤 모델과 키가 필요한지는 README 에 명시가 없고, 역할별 제공자 프로필 구성은 커뮤니티 문서 쪽으로 안내합니다. 그 문서의 프리셋도 번들 기본값이 아니라 사용자 수준 설정 지침으로 다루고, 모델 가용성과 인증은 각자 환경에서 직접 확인하라고 적혀 있습니다.

가재코드 README설치 절차와 네 가지 스킬 표의 원문

GJC 멀티벤더 설정 가이드역할별 제공자 프로필을 다룬 커뮤니티 문서

나머지 편의 기능은 짧게 정리합니다.

• 기동 시 레지스트리 확인 끄기: gjc config set startup.checkUpdate false
• 업데이트: gjc update 또는 bun install -g @gajae-code/coding-agent@latest
• 이미지 입력: gjc @screenshot.png "What should I change?", TUI 에서는 Ctrl+V(Windows 는 Alt+V) 또는 #paste-image
• 알림: 세션 안에서 /settings → Notifications, 헤드리스는 gjc notify setup|status|health|test|recovery
• 테마: /theme 에서 red-claw, blue-crab, claude-code, codex, opencode 중 선택

기동 시 버전 확인은 알림만 하고 스스로 설치하거나 교체하지 않습니다. 레지스트리는 npm 과 같은 방식으로 해석하되, 현재 작업 디렉터리의 .npmrc 는 일부러 무시합니다. 클론한 저장소가 확인 경로나 자격 증명을 바꿔치기하지 못하게 하려는 설계입니다. 상태가 꼬였을 때는 스킬별로 범위를 좁혀 지울 수 있습니다. gjc state clear --force --mode ralplan 처럼 --mode 에 ralplan, ultragoal, team 중 하나를 주고 --session-id 로 세션을 지정하면 그 세션의 해당 스킬 상태만 정리됩니다.

네 가지 스킬 밖에도 두 가지가 더 있습니다. gjc rlm 은 Jupyter 노트북 형태의 연구 세션으로, 공유 Python 커널 위에서 python·read·web_search 로 도구를 좁혀 놓고 돌아갑니다. 실행 기록은 .gjc/rlm/<session>/notebook.ipynb 에 모이고 종료할 때 report.md 를 만듭니다. computer-use 는 화면을 보고 마우스·키보드를 조작하는 실험 단계 기능이며 설정에서 켜야 붙습니다. 둘 다 기본 워크플로와는 성격이 다르니 별도로 봐야 합니다.

정리

• 베타입니다. 결과를 검증하지 않고 중요한 작업에 그대로 쓰지 마세요.
• 설치는 Bun 기반 bun install -g gajae-code, 확인은 gjc --version 과 gjc --smoke-test 두 개.
• 요구사항이 흐리면 deep-interview, 이미 구체적이면 건너뛰고 바로 ralplan 이나 실행으로.
• ralplan 은 승인 전까지 코드를 건드리지 않고, ultragoal 은 goals.json 과 ledger.jsonl 로 완료를 판정합니다.
• team 은 tmux 워커가 실제로 값을 할 때만. 위험한 작업은 gjc --tmux --worktree <이름> 으로 격리하세요.

출처: 저장소 README, 번들 스킬 정의 SKILL.md, npm 패키지 메타데이터, 공식 사이트