skeeper

Skeeper リファレンスガイド

skeeper CLI の包括的なリファレンスです。これは、仕様アーティファクトを追跡対象のロックファイルとともにサイドカー Git リポジトリへミラーする Go バイナリです。これにより、メインリポジトリの PR 差分をコードに集中させつつ、各コミットで、そのコミットとともにリリースされた仕様の状態を証明できます。

Skeeper とは

• ロックファイルに基づく信頼性。 skeeper.lock をメインリポジトリにコミットし、メインリポジトリの各コミットを、名前空間ごとの正確なサイドカーコミットにひも付けます。コンテンツダイジェスト、ファイル数、バイト数も記録します。
• 厳密に管理されたフック。 pre-commit と pre-merge-commit はステージ済みのコンテンツをミラーし、サイドカーをプッシュして、skeeper.lock を書き込み、Git がメインコミットを作成する前にステージします。pre-push はメインリポジトリがプッシュされる前にロックを検証します。
• 共有サイドカー内の名前空間。 各プロジェクトが名前空間プレフィックスを所有し、<namespace>/__branches__/<source-branch> 形式のブランチ対応 ref を使用するため、多数のプロジェクトが同じサイドカー Git リモートを衝突なく共有できます。
• Git に似た収束。 pull はリモートのドキュメントを取り込み、push はリモートにのみ存在するファイルを削除せずにローカルのドキュメントを公開し、sync は pull の後に push を実行します。
• デフォルトで安全。 ローカルに存在しないドキュメントも、明示的に破壊的な --prune フラグを渡さない限り、リモートのサイドカーから削除されません。
• 復旧手段はひとつ。 status --check は異常な状態を報告し、repair は安全な自動修復と復旧状況の報告を担います。
• 単一バイナリ、ローカル優先。 Skeeper は git を呼び出します（skeeper init が新しいサイドカーリポジトリを作成する場合のみ gh も呼び出します）。すべての操作は Git でデバッグできます。

基本モデル：4 つの不変条件

1. skeeper.lock が固定された状態です。 サイドカー URL、ソースブランチ、名前空間ブランチ、サイドカーのコミット SHA、コンテンツダイジェスト、ファイル数、バイト数を記録します。SHA を手動で編集しないでください。
2. 同期はメインコミットの前に行い、後には行いません。 失敗するとコミットも失敗します。非同期の再試行キューはありません。
3. オプトアウトしない限り、失敗時は安全側に倒して処理を中断します。 SKEEPER_SKIP=1 を指定すると、単一のバイパスが許可され、その内容は .git/skeeper/bypass.json に記録され、status、repair、pre-push で表示されます。skeeper sync または skeeper repair で解除されるまで、この状態は維持されます。git commit --no-verify は、Git がすべてのフックコードをスキップするためサポートされていません。
4. pre-push はリモートにコミットが届く前に検証します。 バイパスされたロック、または古いロックがあると、プッシュはブロックされます。

flowchart LR
    A[git commit] --> B[existing user hook content]
    B --> C[skeeper internal pre-commit]
    C --> D[collect owned staged specs]
    D --> E[fetch and rebase sidecar branch]
    E --> F[mirror namespace files into .skeeper/]
    F --> G[commit and push sidecar]
    G --> H[write and stage skeeper.lock]
    H --> I[main commit proceeds]
    I --> J[git push]
    J --> K[skeeper internal pre-push]

クイックスタート

# Inside any Git repository
skeeper init
$EDITOR src/auth/SPEC.md
git add src/auth/service.go src/auth/SPEC.md
git commit -m "auth: design OAuth provider flow"
# the hook syncs the sidecar and stages skeeper.lock; commit it normally
git push

作業ツリーにすでにサイドカー管理の対象とする仕様が含まれている場合は、セットアップ時に --track を渡すか、init の後に skeeper track <glob> --sync を実行してください。

コマンド一覧

コマンド	目的	読み取り専用？
skeeper init	.skeeper.yml、サイドカーリポジトリ、フック、管理対象の.gitignoreを対話形式で初期設定します	いいえ
skeeper status	同期状態、必要に応じたパスのずれ、フックの状態、バイパス状態、次のアクションを表示します	はい
skeeper status --check	CI に適した状態チェックです。対応が必要な場合はゼロ以外の終了コードで終了します	はい
skeeper pull	サイドカーの参照を取得し、ローカルのドキュメントを保持しながらリモートのドキュメントを展開します	いいえ
skeeper push	ローカルの仕様をサイドカーに公開し、skeeper.lockをステージします	いいえ
skeeper sync	リモートの仕様をプルし、ローカルの仕様をプッシュして、skeeper.lockをステージします	いいえ
skeeper restore <path...>	skeeper.lockに記録されたサイドカーのコミットから、選択したファイルを復元します	いいえ
skeeper restore --all	新しいクローンまたはチェックアウトに、ロックされた管理対象ファイルをすべて復元します	いいえ
skeeper track <glob>	.skeeper.ymlと.gitignoreに管理対象のグロブを追加し、必要に応じて既存の一致ファイルを同期します	いいえ
skeeper untrack <path-or-glob>...	サイドカーの同期後、メインリポジトリでの仕様の追跡を停止します	いいえ
skeeper repair	ローカルの Skeeper の状態を診断し、安全に修復します	いいえ
skeeper repair --check	読み取り専用の修復診断	はい
skeeper log <path>	単一の仕様ファイルについて、サイドカーの履歴を表示します	はい
skeeper version	ビルドメタデータを出力します	はい

CLI リファレンスに記載されているコマンドでは、--jsonを指定すると決定的な機械可読形式の出力が生成されます。計画を事前確認できる変更系コマンドでは、--dry-runを使用できます。--forceは、settings.guardrailsで宣言されている広範な計画へのガードレールを上書きします。

非公開のskeeper internal ...コマンドは、Git フックとマージドライバーの内部処理用です。Skeeper 自体をテストする場合を除き、ユーザーに推奨したり、手動で実行したりしないでください。

最新情報の保証

このディレクトリは、リポジトリに同梱される Skeeper の公式スキルとして扱ってください。CLI の仕様が変更された場合は、同じ変更でこのファイルとreferences/cli-reference.mdを更新してください。skeeper --helpと、各公開サブコマンドの--helpを照合して監査してください。古いドキュメント、以前の台帳、実装用ヘルパーからコマンドを推測しないでください。

hydrate、update、diff、reconcile、resolve、rescue、verify、fsck、hooks、merge-driver、adopt、patternなどの過去のコマンドは、公開ワークフローの案内として使用しません。ユーザーがこれらに言及した場合は、意図を現在の公開コマンドモデルであるstatus、pull、push、sync、restore、track、untrack、repairに置き換えてください。

フラグごとの詳細については、references/cli-reference.mdを参照してください。

設定の早見表

.skeeper.yml はリポジトリのルートに置き、コミットします。最低限必要な形式は次のとおりです。

sidecar: [email protected]:user/myproject-specs.git

namespaces:
  - name: project
    patterns:
      - "**/SPEC.md"
      - "docs/specs/**"
      - ".claude/plans/**"
      - "**/*.spec.md"
    exclude:
      - "docs/specs/private/**"

任意の運用時のデフォルト設定：

settings:
  guardrails:
    max_files: 100 # default 100
    max_bytes: 10485760 # default 10 MiB
  hooks:
    pre_push_timeout: 30s # default 30s
    allow_skip_env: SKEEPER_SKIP # default SKEEPER_SKIP

把握しておくべきルールは4つあります。

1. 不明なキーは拒否されます。 デコードは厳密に行われます。
2. 公開されている除外方法は exclude のみです。 patterns 内の否定グロブ（!docs/private/**）は拒否されます。
3. 所有権は一意でなければなりません。 2つの名前空間が同じファイルに一致すると、exclude の追加を求めるエラーでプランが失敗します。
4. __branches__ は予約済みです。 名前空間とブランチ対応の参照を区切るセグメントです。

すべてのフィールドとデフォルト値を含む完全なスキーマについては、references/config-reference.md をご覧ください。

よくあるワークフロー

新しいリポジトリを初期化する

skeeper init \
  --sidecar-name myproject-specs \
  --visibility private \
  --namespace project \
  --track "**/SPEC.md" \
  --track "docs/specs/**"
git add .skeeper.yml .gitignore
git commit -m "chore: bootstrap skeeper"

サイドカーがすでにあるリポジトリに参加する

skeeper init --sidecar [email protected]:user/shared-specs.git \
  --namespace project \
  --track "**/SPEC.md"
skeeper restore --all
skeeper repair

init はフックとマージドライバーの設定をインストールまたは更新します。restore --all は現在の skeeper.lock で固定されているファイルを実体化します。repair はクローンのセットアップ後に安全に実行でき、必要に応じてローカルのフック状態を更新します。

作業ツリー内の既存ファイルを追跡する

skeeper track "docs/adrs/**" --sync
git add .skeeper.yml .gitignore skeeper.lock
git commit -m "chore: track ADRs in skeeper"

カバレッジだけを更新し、一致するファイルは後で skeeper sync で公開する場合は、--sync を付けずに track を使用します。

2つのクローンからドキュメントをマージする

# clone A
skeeper sync
git commit -m "skeeper: sync docs"
git push

# clone B
git pull
skeeper sync
git commit -m "skeeper: sync docs"
git push

sync はデフォルトで両方の変更を保持します。サイドカーの状態を取得し、リモートにのみあるドキュメントをローカルに復元し、ローカルにのみあるドキュメントを公開して、skeeper.lock を更新します。

push の失敗またはバイパス後に復旧する

skeeper status --paths
skeeper repair --check
# fix network/auth/contention if reported, then:
skeeper repair
skeeper sync
skeeper status --check

repair --check は読み取り専用です。repair は、フックの不整合、安全に再開できる中断済みトランザクション、正常な同期後に残った古いバイパス記録、ローカルのサイドカーオブジェクトの欠落など、安全に対処できるローカルの問題を修正します。上書きや削除の判断が曖昧な場合は停止します。

ロックからファイルを復元する

skeeper restore docs/specs/auth.md
skeeper restore --all

restore はデフォルトで、ロックされたサイドカーのコミットを使用します。現在のロックではなく、サイドカーのリモートにある最新の状態を使いたい場合は pull を使用します。

skeeper.lock のマージ競合を解決する

git merge feature/auth-redesign
# if the automatic merge driver was not wired locally:
skeeper repair
skeeper sync
git add skeeper.lock
git commit

サイドカーの SHA 値を手動で編集することはサポートされていません。Skeeper を通じてロックを再生成してください。

CI との統合

同一リポジトリ用の GitHub Action は、リリース済みバイナリをラップします。

name: skeeper

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: compozy/[email protected]
        with:
          args: |
            status
            --check
            --json
          ssh-private-key: ${{ secrets.SKEEPER_SSH_PRIVATE_KEY }}

認証情報の優先順位：

1. ssh-private-key は一時キーを書き込み、GIT_SSH_COMMAND を設定します。クリーンアップ時にキーは消去されます。
2. token は、ジョブごとの GIT_CONFIG_GLOBAL に HTTPS の GitHub 認証情報を設定します。
3. どちらの入力も指定されていない場合は、ランナーの既存の Git／SSH 設定が使われます。

設定前に、::add-mask:: によってシークレットは必ずマスクされます。

Skeeper を使わない方がよい場合

• 仕様をすでにメインツリーでバージョン管理しており、コードと並べて PR の差分に表示したいリポジトリ。 Skeeper は、仕様がその差分に含まれないようにするためのものです。
• マージ前に仕様の内容そのものを PR でレビューする必要があるチーム。 Skeeper はメインのコミットが成功した後にミラーリングするため、仕様のレビューはサイドカーリポジトリで行うか、コミット前にメインツリーの作業コピーで行う必要があります。
• 安定したサイドカーホストがないリポジトリ。 Skeeper はコミット時に作業ツリーから到達できる Git リモートを必要とします。リモートに到達できない場合、誰かが SKEEPER_SKIP=1 を使わない限り、すべてのコミットが安全側に倒れて失敗します。
• ビルド成果物、生成コード、大きなバイナリの保存。 Skeeper は仕様形式のテキスト成果物を対象としています。意図どおりに保つため、ガードレールのデフォルトはプランあたり100ファイル、10 MiB に設定されています。

エージェント向けアンチパターン

1. skeeper が有効なリポジトリで、git commit --no-verify を絶対に使わないでください。 代わりに SKEEPER_SKIP=1 を使ってください。そうすることで、バイパスが監査可能になります。
2. skeeper.lock 内の SHA を手動で編集しないでください。 skeeper sync を使ってロックを再生成してください。
3. 一意の名前空間を設けずに、プロジェクト間でサイドカーのリモートを再利用しないでください。 Skeeper では曖昧さのないルーティングが必要です。ファイルごとに所有者を一意にしてください。
4. SKEEPER_SKIP=1 でバイパスした後、skeeper sync の実行を忘れないでください。 バイパスを解消するまで、status、repair、pre-push で引き続き表示されます。
5. patterns に否定グロブを指定しないでください。 代わりに exclude を使ってください。ローダーは否定グロブを明示的に拒否します。
6. マージコンフリクトを解決するために skeeper.lock を削除しないでください。 skeeper repair／skeeper sync で解決してください。
7. skeeper restore が最新の先端を追跡すると決めつけないでください。 ロックされたコミットから復元します。最新のリモートドキュメントには skeeper pull を使ってください。
8. リモートにのみ存在するサイドカーファイルを誤って削除しないでください。 ローカルのファイル一式を意図的に正とする場合に限り、skeeper push --prune を使ってください。
9. ユーザーワークフローのガイダンスで skeeper internal コマンドを使わないでください。 これらはフックおよびマージドライバーを動かすための内部処理です。

参考資料

• references/cli-reference.md — すべての公開コマンドとフラグです。
• references/config-reference.md — .skeeper.yml の完全なスキーマ、デフォルト値、検証ルールです。