설치 안내

한국어 · English

Jaekit을 처음 설치하거나, 새 버전으로 업데이트하거나, 제거할 때 읽습니다. Jaekit은 터미널 프로그램 ha·spar와 에이전트 플러그인 Spec·Seal·Spar로 이루어집니다. 프로그램은 brew나 Release 파일로, 플러그인은 Codex나 Claude Code의 플러그인 명령으로 설치하며, 둘 다 있어야 동작합니다. 이 문서는 현재 배포판 v0.1.8 기준입니다. macOS·Linux의 arm64·amd64를 지원합니다. 아래 명령은 터미널에서 실행합니다. 설치 뒤 에이전트에게 보낼 말은 첫 사용 안내에 있습니다.

• 처음 설치할 때: 기본 설치
• brew를 쓰지 않을 때: Release 파일로 설치
• Windows에서 Linux 도구를 쓸 때: WSL2 준비 안내 — 실제 사용 미확인
• 참조 생산자와 예시를 쓸 때: 참조 검사 가져오기
• 새 버전으로 옮길 때: 업데이트
• 배포판마다 들어 있는 구성 요소와 적용 범위: 배포판과 개발 조합
• 그만 쓸 때: 제거
• 저장소 checkout 경로로 등록해 쓰던 것을 옮길 때: 로컬 경로 등록에서 옮기기
• Jaekit 자체를 고칠 때: 소스 빌드와 개발 등록

기본 설치#

Git과 Codex 또는 Claude Code가 필요합니다. brew로 설치하려면 Homebrew도 준비합니다. 작업할 프로젝트는 Git으로 변경 이력을 관리하는 폴더여야 합니다. Jaekit 저장소를 clone(내 컴퓨터로 복사)할 필요는 없습니다.

현재 공개 릴리스의 Seal Core ha는 Windows를 지원하지 않습니다. Windows 네이티브 후보 안내는 별도 후보 패키지를 다룹니다. Windows 11 x64·PowerShell 5.1/7의 실제 설치·Core 실행·호스트 동작은 아직 확인하지 않았으며, 교차 빌드와 로컬 검사는 그 근거를 대신하지 않습니다.

이는 네이티브 Windows 실행에 대한 설명입니다. WSL2의 Ubuntu 24.04 LTS x64에서 Linux 배포물을 사용하는 경로는 별도 안내에 정리했습니다. 실제 WSL2 설치·실행과 에이전트 사용은 아직 확인하지 않았으며, 일반 Linux 결과로 대신하지 않습니다.

ha 설치#

brew install jgoneit/tap/jaekit

블록을 하나씩 실행합니다. brew 설치가 끝나기 전에 다음 명령까지 붙여 넣으면 뒤의 줄을 읽어 버릴 수 있습니다. brew는 Release의 실행 파일을 받아 checksum(파일 내용 확인값)을 검사합니다. brew는 ha와 spar를 함께 설치합니다. Go를 설치하거나 소스를 빌드하지 않습니다. Homebrew가 없으면 Release 파일로 설치를 따릅니다.

버전 확인#

ha --version
which -a ha
spar --version
which -a spar

ha --version은 ha 0.1.8을 출력해야 합니다. spar --version도 같은 버전 spar 0.1.8을 보여야 합니다. which -a ha의 첫 줄이 실제로 실행되는 파일입니다(spar는 which -a spar의 첫 줄). PATH는 명령을 찾을 폴더의 순서입니다. 버전이 다르면 먼저 이 경로를 확인합니다. 예전에 go install로 만든 파일이 앞에 있다면 해당 파일을 지우거나 PATH 순서를 바꿉니다. 그 파일은 go env GOBIN이 가리키는 폴더, 비어 있으면 $(go env GOPATH)/bin에 있습니다.

명령을 못 찾고 which -a ha도 비어 있다면 설치가 끝났는지 확인하고, 설치한 폴더가 PATH에 있는지 봅니다. 에이전트도 ha를 찾을 수 있도록 설정한 뒤 Codex 또는 Claude Code를 새로 엽니다.

Codex#

먼저 ha 설치와 버전 확인을 마칩니다. 아래 설치 명령에는 터미널용 Codex(Codex CLI)가 필요합니다. 플러그인은 Codex CLI와 데스크톱 앱에서 사용할 수 있으며, Codex IDE 확장에서는 지원되지 않습니다.

codex plugin marketplace add jgoneit/jaekit@v0.1.8
codex plugin add spec@jaekit
codex plugin add seal@jaekit
codex plugin add spar@jaekit

@v0.1.8은 marketplace(플러그인 목록)를 해당 태그에 고정합니다. main이 바뀌어도 배포판의 spec 0.1.13·seal 0.1.23·spar 0.1.4을 받습니다.

Codex를 새로 열고 대화에 $를 입력해 Jaekit의 spec:spec 또는 seal:seal을 고릅니다. 호출 이름은 $spec:spec과 $seal:seal입니다. 첫 작업 맡기기를 따라 해 봅니다. 다른 플러그인과 혼동되면 문제 해결을 봅니다.

Claude Code#

먼저 ha 설치와 버전 확인을 마칩니다. 그다음 아래 명령으로 Claude Code에 플러그인을 설치합니다.

claude plugin marketplace add jgoneit/jaekit#v0.1.8
claude plugin install spec@jaekit
claude plugin install seal@jaekit
claude plugin install spar@jaekit
claude plugin list

#v0.1.8은 marketplace를 해당 태그에 고정합니다. 마지막 목록에서 spec@jaekit, seal@jaekit, spar@jaekit가 enabled인지 봅니다. 다른 플러그인과 혼동되면 문제 해결을 봅니다.

Claude Code를 새로 열고 대화에서 /spec:spec <요청>으로 목표를 정리한 뒤, 별도 메시지의 /seal:seal docs/specs/<goal>로 구현을 시작합니다. 플러그인의 스킬은 /플러그인-이름:스킬-이름으로 호출합니다. 목표 확인과 이어 가기는 사용 안내에 있습니다.

Spar#

Spar는 여러 리뷰어 CLI로 독립 검토 라운드를 돌립니다. Spar 안내를 보세요. v0.1.7부터 standard·strict 목표에는 Spar 실행 파일과 Spar 플러그인이 필요합니다. v0.1.7의 Seal은 새 목표를 run-rules/5로 시작하고, run-rules/5로 시작한 standard·strict 목표는 기록된 Spar gate가 있어야 완료됩니다. light 목표, Assurance: 줄이 없는 목표, run-rules/4 이하로 시작한 목표에는 Spar가 필요 없습니다. 검토 없이 끝내려면 등급을 light로 낮추는 목표 문서 수정을 사용자가 정합니다(검토 gate).

v0.1.7부터는 Homebrew formula와 Release 파일이 ha와 spar를 함께 설치하고 두 버전이 같습니다. v0.1.6 이하의 릴리스 파일, formula, marketplace 태그에는 Spar가 없습니다.

spar --version
which -a spar

spar --version은 ha --version과 같은 버전을 보여야 합니다. 위 Codex·Claude Code의 설치 명령은 Spar 플러그인도 설치합니다. spec·seal만 설치했다면 v0.1.8에 고정한 marketplace에서 다음으로 더합니다.

codex plugin add spar@jaekit
claude plugin install spar@jaekit

호스트를 새로 엽니다. 첫 라운드 전에 리뷰어 설정에 따라 가진 CLI만 리뷰어로 적고 spar config로 확인합니다. standard·strict 목표의 검토 라운드는 Seal이 Spar로 돌립니다. 그 밖에 계획이나 변경에 독립 검토가 필요하면 Codex에서는 $spar:spar, Claude Code에서는 /spar:spar를 씁니다.

Release 파일로 설치#

brew 대신 v0.1.8 Release의 파일 ha_0.1.8_<os>_<arch>.tar.gz로 설치할 수 있습니다. <os>는 darwin(macOS) 또는 linux, <arch>는 arm64(Apple Silicon 등) 또는 amd64(Intel 등)입니다.

아래 명령은 고치지 않고 그대로 붙여 넣습니다. OS와 CPU를 보고 자기 플랫폼 파일을 받아 checksum을 확인한 뒤 ha와 spar를 ~/.local/bin/ha와 ~/.local/bin/spar에 둡니다(spar는 v0.1.7 파일부터 들어 있습니다). 지원하지 않는 OS나 CPU에서는 아무것도 받거나 설치하지 않고 멈춥니다. 압축을 푼 파일에 spar가 없으면 아무것도 바꾸지 않고 메시지와 함께 멈춥니다.

(
  set -e
  case "$(uname -s)" in
    Darwin) os=darwin ;;
    Linux) os=linux ;;
    *) echo "지원하지 않는 OS입니다: $(uname -s)" >&2; exit 1 ;;
  esac
  case "$(uname -m)" in
    arm64 | aarch64) arch=arm64 ;;
    x86_64 | amd64) arch=amd64 ;;
    *) echo "지원하지 않는 CPU입니다: $(uname -m)" >&2; exit 1 ;;
  esac
  name="ha_0.1.8_${os}_${arch}"
  url="https://github.com/jgoneit/jaekit/releases/download/v0.1.8"
  tmp="$(mktemp -d)"
  binary_tmp=
  spar_tmp=
  trap 'rm -rf "$tmp"; if [ -n "$binary_tmp" ]; then rm -f "$binary_tmp"; fi; if [ -n "$spar_tmp" ]; then rm -f "$spar_tmp"; fi' EXIT
  cd "$tmp"
  curl -fsSLO "$url/$name.tar.gz"
  curl -fsSLO "$url/checksums.txt"
  grep " $name.tar.gz\$" checksums.txt > "$name.sha256"
  if command -v sha256sum >/dev/null 2>&1; then
    sha256sum -c "$name.sha256"
  else
    shasum -a 256 -c "$name.sha256"
  fi
  tar -xzf "$name.tar.gz"
  if [ ! -f "$name/spar" ] || [ -L "$name/spar" ]; then
    echo "The archive has no spar executable; nothing was replaced: $name.tar.gz" >&2
    exit 1
  fi
  mkdir "$tmp/public"
  cp -R "$name/tools" "$name/examples" "$name/guides" "$name/contracts" "$name/assets" "$tmp/public/"
  cp "$name/README.md" "$name/README.ko.md" "$name/LICENSE" "$tmp/public/"
  share="$HOME/.local/share/jaekit/0.1.8"
  if [ -e "$share" ] || [ -L "$share" ]; then
    if [ ! -d "$share" ] || [ -L "$share" ]; then
      echo "Release data path is not an ordinary directory: $share" >&2
      exit 1
    fi
    special="$(find "$share" ! -type f ! -type d -print)"
    if [ -n "$special" ]; then
      echo "Release data contains entries that are not ordinary files or directories; nothing was replaced:" >&2
      printf '%s\n' "$special" >&2
      exit 1
    fi
    if ! diff -qr "$tmp/public" "$share"; then
      echo "Existing v0.1.8 data differs; nothing was replaced: $share" >&2
      exit 1
    fi
  else
    mkdir -p "$HOME/.local/share/jaekit"
    mv "$tmp/public" "$share"
  fi
  bin="$HOME/.local/bin"
  mkdir -p "$bin"
  if [ -e "$bin/ha" ] || [ -L "$bin/ha" ]; then
    if [ ! -f "$bin/ha" ] || [ -L "$bin/ha" ]; then
      echo "Existing ha path is not an ordinary file; nothing was replaced: $bin/ha" >&2
      exit 1
    fi
  fi
  if [ -e "$bin/spar" ] || [ -L "$bin/spar" ]; then
    if [ ! -f "$bin/spar" ] || [ -L "$bin/spar" ]; then
      echo "Existing spar path is not an ordinary file; nothing was replaced: $bin/spar" >&2
      exit 1
    fi
  fi
  binary_tmp="$(mktemp "$bin/.ha.XXXXXX")"
  cp "$name/ha" "$binary_tmp"
  chmod 755 "$binary_tmp"
  spar_tmp="$(mktemp "$bin/.spar.XXXXXX")"
  cp "$name/spar" "$spar_tmp"
  chmod 755 "$spar_tmp"
  mv -f "$binary_tmp" "$bin/ha"
  binary_tmp=
  echo "설치했습니다: $HOME/.local/bin/ha ($name)"
  mv -f "$spar_tmp" "$bin/spar"
  spar_tmp=
  echo "설치했습니다: $HOME/.local/bin/spar ($name)"
)

두 실행 파일을 모두 설치 위치 옆에 준비한 뒤에 바꾸므로, 받기·복사·권한 설정이 실패하면 둘 다 그대로 남습니다. 다만 두 파일을 바꾸는 것은 따로 일어나서, 그 사이에 명령이 멈추면(강제 종료, 전원 차단 등) ha만 새 버전일 수 있습니다. 같은 명령을 다시 실행하면 둘이 맞춰집니다.

~/.local/bin이 PATH에 없으면 셸 설정(~/.zshrc 등)에 export PATH="$HOME/.local/bin:$PATH"를 더합니다. 브라우저로 직접 받은 파일을 macOS가 막으면 xattr -d com.apple.quarantine ~/.local/bin/ha로 풉니다. 그다음 버전 확인과 Codex 또는 Claude Code 설치로 갑니다.

배포판과 개발 조합#

배포판마다 들어 있는 기능은 다음과 같습니다.

• 현재 배포판 v0.1.8: v0.1.7의 범위에 더해 ha cost(목표 하나의 검증·검토 비용 요약), Seal이 미리 알 수 있는 결정을 첫 baseline 전에 한 메시지로 묻기, Spar 지적의 가장 작은 수정 방향, spar가 없으면 멈추는 직접 설치
• 소스 빌드: 개발용 식별자이며 배포 파일의 설치 근거가 아님

아래 태그 고정 설치 명령은 v0.1.8을 받습니다. Seal은 실제 사용할 Core의 지원 정보를 확인하고, 확인할 수 없거나 부족하면 기록 전에 멈춥니다. 버전 숫자만 맞추거나 구규칙으로 바꿔 진행하지 않습니다. 지원 조건은 Core 지원 정보 계약에 있습니다.

Spec은 Core 설치나 지원 조회 없이 문서를 작성합니다. Spec 0.1.13의 새 문서는 nested/1을 사용하므로 구현을 맡길 때는 그 형식을 지원하는 Core가 필요합니다. 기존 목표의 형식과 /1·/2·/3 기록, 사용량과 시간 한도는 업데이트로 바꾸지 않습니다. 실제 호스트 확인 범위는 v0.1.8 릴리스 노트에 따릅니다.

참조 검사 가져오기#

v0.1.8 배포 파일에는 tools/check-result-reference.py와 examples/check-result/가 들어 있습니다. 개발 checkout이나 Go 설치 없이 자기 프로젝트로 복사할 수 있습니다. 이 생산자는 Python 3 표준 라이브러리만 사용합니다. Python은 이 검사를 선택할 때만 필요하며 Spec·Seal의 필수 조건이 아닙니다. 다른 러너는 구현자가 선택합니다. pytest·Vitest·Playwright 자동 연동은 제공하지 않습니다.

프로젝트 루트에서 설치 방식에 맞는 한 블록만 실행해 자료 경로를 정합니다. Homebrew의 pkgshare 위치는 다음과 같습니다.

package_root="$(brew --prefix jaekit)/share/jaekit"

위의 직접 설치 명령은 checksum을 확인한 공개 자료를 다음 버전별 폴더에 보관합니다. 같은 버전의 자료가 이미 있으면 일반 파일과 폴더로만 이루어지고 내용이 같을 때만 재사용합니다. 내용이 다르거나 symlink 같은 다른 항목이 있으면 바이너리를 교체하기 전에 멈추고 그 경로를 알려 줍니다. 직접 설치했다면 다음을 씁니다.

package_root="$HOME/.local/share/jaekit/0.1.8"

이어 같은 터미널의 프로젝트 루트에서 다음을 실행합니다. 예시 파일이 이미 있으면 덮어쓰지 않고 멈춥니다.

(
  set -e
  for file in tools/check-result-reference.py checks/declaration.json checks/reference.json sample/input.txt; do
    if [ -e "$file" ] || [ -L "$file" ]; then
      echo "File already exists; choose other paths before copying: $file" >&2
      exit 1
    fi
  done
  mkdir -p tools checks sample
  cp "$package_root/tools/check-result-reference.py" tools/
  cp "$package_root/examples/check-result/declaration.json" checks/
  cp "$package_root/examples/check-result/reference.json" checks/
  cp "$package_root/examples/check-result/input.txt" sample/
)

합성 예시의 PLAN 연결과 관측 순서를 따라 초기 파일을 기준 상태로 보존하고 목표를 시작합니다. 명령은 python3 tools/check-result-reference.py checks/declaration.json checks/reference.json이며 ha check가 호출별 결과 보고 경로를 전달합니다. 초기 파일의 실제 요구 위반과 수정 뒤 통과를 구분하며, 환경 오류를 기대 실패로 삼지 않습니다. 선언·설정·생산자는 검사 전에 commit하고 모두 PLAN의 검사 경로에 포함합니다. 요구 대상과 경로는 프로젝트에 맞게 정합니다. 세부 형식은 결과 계약에 있습니다.

업데이트#

ha와 plugin을 함께 새 버전으로 옮깁니다. 설치할 때 쓴 도구로 올립니다. 아래는 v0.1.8로 옮기는 명령입니다. 명령 블록은 하나씩 붙여 넣습니다.

brew로 설치한 ha는 brew가 tap을 새로 받은 뒤 올립니다.

brew update

brew upgrade jgoneit/tap/jaekit

Release 파일로 설치한 ha는 Release 파일로 설치의 명령을 다시 붙여 넣습니다. 새 버전의 파일이 ~/.local/bin/ha를 덮어쓰고 ~/.local/bin/spar를 둡니다.

그다음 두 실행 파일의 버전과 실제로 실행되는 위치를 확인합니다. ha 0.1.8과 spar 0.1.8이 나오면 됩니다. 다른 버전이 나오면 which -a ha·which -a spar의 첫 줄이 실제로 실행되는 파일이므로 버전 확인대로 PATH를 봅니다.

ha --version
which -a ha
spar --version
which -a spar

(
  set -e
  current=0.1.8
  data_root="$HOME/.local/share/jaekit"
  if [ -d "$data_root" ] && [ ! -L "$data_root" ]; then
    find "$data_root" -mindepth 1 -maxdepth 1 -type d -exec sh -c '
      set -e
      current=$1
      shift
      for entry do
        [ -d "$entry" ] && [ ! -L "$entry" ] || continue
        version=${entry##*/}
        case "$version" in "" | *[!0-9.]*) continue ;; esac
        older=$(awk -v version="$version" -v current="$current" "
          BEGIN {
            if (version !~ /^[0-9]+[.][0-9]+[.][0-9]+$/) { print 0; exit }
            split(version, v, /[.]/)
            split(current, c, /[.]/)
            for (i = 1; i <= 3; i++) {
              if (v[i] + 0 != c[i] + 0) { print (v[i] + 0 < c[i] + 0); exit }
            }
            print 0
          }")
        case "$older" in
          1) rm -rf "$entry" ;;
          0) ;;
          *) echo "Could not compare version: $version" >&2; exit 1 ;;
        esac
      done
    ' sh "$current" {} +
  fi
)

plugin은 marketplace를 새 태그에 고정해 다시 등록합니다. 같은 이름의 marketplace는 둘을 함께 둘 수 없어서 먼저 지웁니다. 지우면 그 marketplace에서 설치한 spec·seal·spar도 함께 지워지므로 다시 설치합니다. 쓰는 host의 명령만 붙여 넣으면 됩니다.

Codex:

codex plugin marketplace remove jaekit
codex plugin marketplace add jgoneit/jaekit@v0.1.8
codex plugin add spec@jaekit
codex plugin add seal@jaekit
codex plugin add spar@jaekit

Claude Code:

claude plugin marketplace remove jaekit
claude plugin marketplace add jgoneit/jaekit#v0.1.8
claude plugin install spec@jaekit
claude plugin install seal@jaekit
claude plugin install spar@jaekit

host를 새로 열면 새 버전의 Spec·Seal·Spar가 실립니다.

제거#

ha와 plugin, jaekit marketplace를 지웁니다. 설치한 방법과 쓰는 host에 맞는 명령을 붙여 넣습니다.

brew로 설치한 ha:

brew uninstall jgoneit/tap/jaekit

tap도 더 쓰지 않으면 brew untap jgoneit/tap으로 지웁니다.

Release 파일로 설치한 ha:

rm ~/.local/bin/ha

v0.1.7부터 직접 설치한 spar도 지웁니다.

rm ~/.local/bin/spar

직접 설치가 공개 자료를 보관한 폴더도 지웁니다. 자기 프로젝트에 복사한 참조 검사 파일(tools/check-result-reference.py 등)과 목표 문서·기록은 남습니다. ~/.local/share/jaekit이 symlink이면 link만 지우고 가리키는 내용은 남깁니다.

rm -rf ~/.local/share/jaekit

Codex:

codex plugin remove spec@jaekit
codex plugin remove seal@jaekit
codex plugin remove spar@jaekit
codex plugin marketplace remove jaekit

Claude Code:

claude plugin uninstall spec@jaekit
claude plugin uninstall seal@jaekit
claude plugin uninstall spar@jaekit
claude plugin marketplace remove jaekit

설치·업데이트·제거는 작업한 프로젝트의 문서·기록·출력 원문을 지우지 않습니다. 목표 문서와 Seal이 만든 파일(docs/specs/<goal>/의 SPEC.md, PLAN.md, REVIEW.md, PROGRESS.md, runs.jsonl)의 Git 추적 여부는 프로젝트 정책에 따릅니다. 추적된 기록과 ignore한 비공개 기록 모두 그대로 남습니다. 검사 출력 원문은 git이 추적하지 않는, 그 작업 트리의 Git 디렉토리 아래 ha/runs/에 있습니다. 보통은 .git/ha/ 아래이고, .git이 파일인 linked worktree에서는 git rev-parse --absolute-git-dir이 알려 주는 디렉토리 아래에 있습니다.

선택 기능인 판단 이력은 같은 저장소의 모든 작업 트리가 공유하는 공통 Git 디렉토리(git rev-parse --git-common-dir)의 ha/history/ 아래에 실행 시작 기록별로 있습니다. 일반 checkout에서는 검사 출력 원문과 같은 .git/ha/ 아래입니다. linked worktree를 제거해도 이 이력은 남지만, 남은 이력이 목표 문서나 검사 출력 원문의 보존·복원을 보증하지는 않습니다. 새 clone이나 다른 기기에는 따라가지 않으며, Git 디렉토리 전체를 지우면 함께 사라지고 자동으로 복구되지 않습니다.

목표 문서와 기록도 지우기로 했다면 먼저 보관 필요 여부와 Git 추적 상태를 확인합니다. 추적 중인 목표는 그 저장소의 루트에서 git rm -r docs/specs/<goal>로 지운 뒤 commit합니다. 추적하지 않는 목표는 이 명령의 대상이 아니므로 프로젝트의 로컬 보관 정책에 따라 별도로 정리합니다. ignore한 문서를 강제로 Git에 추가하지 않습니다.

검사 출력 원문도 지우려면 Jaekit의 검사가 돌고 있지 않을 때(Seal이 작업 중이 아닐 때) 그 작업 트리에서 아래 명령을 붙여 넣습니다. 그 작업 트리에 있는 모든 목표의 검사 출력 원문이 지워집니다. 판단 이력, 다른 작업 트리의 출력과 목표 문서·실행 기록은 남습니다.

gitdir="$(git rev-parse --absolute-git-dir)" && rm -rf "$gitdir/ha/runs"

로컬 경로 등록에서 옮기기#

이미 저장소 checkout 경로로 jaekit marketplace를 등록했으면, 그 등록을 지우고 v0.1.8에 고정한 GitHub 저장소로 다시 등록합니다. 같은 이름의 marketplace는 둘을 함께 둘 수 없습니다. 지우면 그 marketplace에서 설치한 spec·seal·spar도 함께 지워지므로 다시 설치합니다.

Codex:

codex plugin marketplace remove jaekit
codex plugin marketplace add jgoneit/jaekit@v0.1.8
codex plugin add spec@jaekit
codex plugin add seal@jaekit
codex plugin add spar@jaekit

Claude Code:

claude plugin marketplace remove jaekit
claude plugin marketplace add jgoneit/jaekit#v0.1.8
claude plugin install spec@jaekit
claude plugin install seal@jaekit
claude plugin install spar@jaekit

예전에 go install로 만든 ha가 남아 있으면 버전 확인대로 정리합니다.