Skip to content
Apothem
ランブック

マシン間同期検証チェックリスト

完全な可搬性チェックを伴い、新しいホスト上で Claude Code アダプターが正しくインストール、検証、アンインストールされることを確認する検証手順。

適用範囲。 このチェックリストは、新しい二台目のホストで Claude Code アダプター のインストール/アンインストールのポータビリティ層を検証します。他のハーネスには、ホストごとの検証手順が site/content/docs/harnesses/<harness>.mdx に記載されています。

二つのパス、二つの役割。 このチェックリストを読む間は、両者を区別してください。$HOME/.apothem は エンジンホーム です。ソースツリーのクローン先であり、インストーラーが読み込む場所でもあります(APOTHEM_HOME で上書きできます)。~/.claude/ は Claude Code の設定ルート です。アダプターの出力先であり、マテリアライズされた settings.json とサポートサブツリーが配置される場所です。エンジンが ~/.claude/ にインストールされることは決してありません。別のハーネスを検証する際は、アダプター固有の出力パスに読み替えてください。

新しい二台目のホストでの、インストール/アンインストールのポータビリティ層のオペレーター主導の検証。 公開ティア(vX.Y.Z)は単一の Windows ホストで作成されました。ポータビリティの主張(CLAUDE.md の portability: universal)は、複数ホストの不変条件を裏付ける前に、二台目のホストでエンドツーエンドの実行を必要とします。このチェックリストが、正規の二台目ホストの検証手順(Claude Code アダプター)です。


1. 二台目のホストでの事前条件

検証を開始する前に、二台目のホストで次を実行します:

項目コマンド期待される結果
Git のインストールgit --versionGit 2.40+
Python 3.10+ が利用可能python3 --version(POSIX)または py -3 --version(Windows)3.10 / 3.11 / 3.12 / 3.13
GitHub 認証(任意、認証済みのクローンや API チェック用)gh auth status認証済みのワークフローを使う場合は、リポジトリの許可されたアカウントでログイン済みであること
シェルが利用可能bash --version(POSIX)または pwsh --version(Windows)Bash 4+ または PowerShell 7+
既存のエンジンホームがないことls "$HOME/.apothem" 2>&1"No such file or directory" — 存在する場合は、続行前にバックアップを取ってください

2. クローンとインストールの検証

二台目のホストで次を実行します:

# Clone the published repo to the engine home. This is NOT ~/.claude — that
# is the Claude Code configuration root the adapter writes into, and cloning
# a source tree on top of it would bury the harness's own config.
git clone https://github.com/ahmed-g-gad/apothem.git "$HOME/.apothem"
cd "$HOME/.apothem"

# (POSIX path) Run scripts/installer/install.sh dry-run first
bash scripts/installer/install.sh --dry-run                                    # exit 0; prints Dry-run complete — no changes were made.

# (POSIX path) Run scripts/installer/install.sh for real
bash scripts/installer/install.sh                                               # exit 0; idempotent

# (Windows path) PowerShell parallel
pwsh -File scripts/installer/install.ps1 -DryRun                                # exit 0; prints Dry-run complete - no changes were made.
pwsh -File scripts/installer/install.ps1                                        # exit 0

各コマンドの終了コードと標準出力のバナーを記録してください。<second-host>/.audit/cross-machine-clone-install.md に記録します。

3. 四要素の規律(src/apothem/rules/production-ready-prs.md に従う)

二台目のホストで、四つの不変条件をそれぞれ検証します:

3.1 既存の配置先の安全性

# Re-run installer at the same destination.
bash scripts/installer/install.sh                                               # POSIX
pwsh -File scripts/installer/install.ps1                                        # Windows

期待される結果: インストーラーは既存のエンジンホームを検出し、再インストールや複製を行う代わりに、その中でリリースタグをチェックアウトします。終了コードは 0 です。

3.2 前提条件のチェック

# Run from a copy outside any checkout, with git not on PATH.
d="$(mktemp -d)" && cp scripts/installer/install.sh "$d/" && PATH=<directory holding python3, click, rich and coreutils, but no git> /bin/sh "$d/install.sh"                            # POSIX (no git)

期待される結果: インストーラーは実行を拒否し、明示的な "git not found" の診断を出力して、終了コードは 0 以外になります。

3.3 冪等な再実行

# Run installer N times back-to-back.
for i in 1 2 3 4 5; do bash scripts/installer/install.sh; done                  # POSIX
1..5 | ForEach-Object { pwsh -File scripts/installer/install.ps1 }              # Windows

期待される結果: すべての呼び出しが終了コード 0 で終了し、最初の呼び出しの後に副作用がなく、重複したファイルも、シェルプロファイルの RC の重複もないこと。

3.4 環境変数による設定

# Install to a non-default engine home. APOTHEM_HOME is the destination
# override the installers actually read; see the installer-environment-variables
# reference for the full set.
APOTHEM_HOME=/tmp/alt-apothem bash scripts/installer/install.sh                 # POSIX
$env:APOTHEM_HOME='C:\tmp\alt-apothem'; pwsh -File scripts/installer/install.ps1   # Windows

期待される結果: インストーラーは環境変数を尊重します。既定の $HOME/.apothem は作成されず、代替の配置先には想定どおりのレイアウトが含まれます。

4. バリデーター群の検証(インストール後)

cd "$HOME/.apothem"
make validate                                                 # conformity gate --all --strict; exit 0
make headers-doctor                                           # file-header-grep → passed:true
make ai-surfaces-doctor                                       # multi-surface-coherence → passed:true
make plans-doctor                                             # no-global-plans + plans-discipline-language
make lint                                                     # ruff check + ruff format --check + mypy
make test                                                     # exit 0, no failures

期待される結果: すべてのゲートがグリーンであること。終了コードと要約行を記録します。

5. アンインストールの検証

# POSIX path — interactive uninstall
bash scripts/installer/uninstall.sh                           # answers: "y" to confirm
PYTHONPATH="$HOME/.apothem/src/apothem/_vendor:$HOME/.apothem/src" python3 -m apothem verify --harness claude-code    # reports the harness as not installed

# Re-install from the kept checkout, then uninstall non-interactively
bash scripts/installer/install.sh
bash scripts/installer/uninstall.sh --yes
PYTHONPATH="$HOME/.apothem/src/apothem/_vendor:$HOME/.apothem/src" python3 -m apothem verify --harness claude-code    # reports the harness as not installed

期待される結果: 対話式フローでプロンプトが表示されること。--yes を指定すると、バッチ実行ではプロンプトが省略されること。どちらのフローでも、Claude Code の設定ルートに Apothem がマテリアライズしたファイルが残らないこと。apothem シムが削除されること(~/.local/bin/apothem。%LOCALAPPDATA%\Microsoft\WindowsApps の apothem.cmd シムは、uninstall.ps1 によってのみ削除されます)。

6. 安全ガードの検証

アンインストーラーのガードは、センチネルファイルではなく、ソースツリーの形状チェックです。対象に src/apothem/ があり、かつ pyproject.toml または .claude-plugin/ のいずれかがある場合にのみ処理を進めます。これらのプローブは、スクリプトが読み取る変数 APOTHEM_HOME を使って実行してください。スクリプトが無視する変数に対して書かれたプローブは、ガードを検証せず、実際のインストールに対してアンインストーラーを実行してしまいます。

# Run uninstall against a directory that is not an apothem source tree.
mkdir -p /tmp/not-an-apothem-install
APOTHEM_HOME=/tmp/not-an-apothem-install bash scripts/installer/uninstall.sh --yes

期待される結果: アンインストーラーは実行を拒否し、No apothem source found at /tmp/not-an-apothem-install — nothing to uninstall を出力します。終了コードは 0 以外です。そのパスには触れていません。

# Run uninstall against $HOME and /.
APOTHEM_HOME=$HOME bash scripts/installer/uninstall.sh --yes 2>&1 | tail -3
APOTHEM_HOME=/ bash scripts/installer/uninstall.sh --yes 2>&1 | tail -3

期待される結果: APOTHEM_HOME=$HOME と APOTHEM_HOME=/ は、それぞれ No apothem source found at … の診断を出して拒否され、どちらもファイルシステムに触れないこと。空の APOTHEM_HOME は意図的に対象外としています。これは、実際のインストールが置かれうる ~/.apothem にフォールバックするためです。

# An explicit APOTHEM_SOURCE that is not a source tree is rejected separately.
APOTHEM_SOURCE=/tmp/not-an-apothem-install bash scripts/installer/uninstall.sh --yes

期待される結果: APOTHEM_SOURCE is not an apothem source tree: /tmp/not-an-apothem-install で拒否され、終了コードは 0 以外です。

7. 報告

二台目のホストでの実行後、結果を次の場所に記録してください:

  • <second-host>/.audit/cross-machine-clone-install.md(クローンとインストールのコマンドの結果)
  • <second-host>/.audit/cross-machine-validators.md(セクション 4 のバリデーターの結果)
  • <second-host>/.audit/cross-machine-uninstall.md(セクション 5–6 のアンインストールと安全性の結果)

検出事項をメンテナーに報告します:

  • ✅ 四要素の規律の不変条件がすべて成立し、すべてのバリデーターのゲートがグリーンで、すべてのアンインストールの安全ガードが安全でないターゲットを拒否した → 公開物の portability: universal の主張がエンドツーエンドで検証された
  • ❌ いずれかの失敗 → 失敗したセクションと取得した出力を添えて https://github.com/ahmed-g-gad/apothem/issues/new に issue を登録します。メンテナーが振り分けます。

8. 受け入れ基準

  • §1 の事前条件が満たされている
  • §2 のクローンとインストールが、POSIX と Windows の両方のシェルで成功すること
  • §3 の四要素の規律が成立すること(既存の配置先の安全性、前提条件のチェック、冪等性、環境変数による設定可能性)
  • §4 のすべてのバリデーターのゲートがグリーンであること
  • §5 の対話式のアンインストールが成功し、--yes がプロンプトなしで成功すること
  • §6 のすべての安全ガードの拒否が発火すること
  • §7 の結果が、文書化された監査パスに記録されていること

二台目のホストで上記のチェックボックスがすべてオンになったら、クロスマシン同期の検証は完了し、portability: universal の主張がエンドツーエンドで検証されたことになります。

On this page