入門: ゼロから動作するハーネスまで

このチュートリアルは、Apothem の最初のセットアップを最初から最後まで案内します。 何もインストールされていない状態から始め、実際のハーネス構成 — あなたが書いたプロファイルから生成され、検証され、動作が確認されたもの — で終わります。 所要時間は約 15 分を見込んでください。 以下のすべてのコマンドは実在し、コピー＆ペーストでそのまま実行できます。

終わるころには、次のことが完了しています。

1. スクリプトインストーラーからの Apothem のインストール。
2. すべてのハーネスを駆動する共有プロファイルの編集。
3. ハーネスのネイティブ設定のマテリアライズ。
4. その設定の検証と、動作する初回実行の確認。

全体を通して、例のハーネスとして Claude Code を使います。インストーラーのデフォルトだからです。 同じ手順は、サポートされているどのハーネスにも当てはまります — ハーネス一覧にたどり着いたら名前を差し替えてください。

最初に必要なものCopy Anchor Link

• Unix ライクなシェル（macOS、Linux、または WSL）。Windows は PowerShell インストーラーが対象とします。このチュートリアルでは bash の手順を示します。
• PATH 上の Python 3.10 以降。python3 --version で確認します。
• エンジンがインタープリターからインポートする 2 つのランタイムライブラリ、click と rich。スタックのほかの部分（pyyaml、jsonschema）はツリーにベンダリングされているため、インポートできる必要があるのはこの 2 つだけです。click または rich が見つからない場合、インストーラーは停止してインストールコマンドを表示します。ワンライナーのコマンドはスクリプトを bash にパイプで渡すため、プロンプトを表示できません。そのため、APOTHEM_AUTO_INSTALL_DEPS=1 を設定するか（例：curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash）、先に 2 つのパッケージをインストールしてください。

Apothem は公開パッケージではなく、バンドルされたソースツリーとして出荷されます — pip install のステップはありません。 インストーラーはツリーをクローンし、そこから直接エンジンを実行します。

ステップ 1 — Apothem をインストールするCopy Anchor Link

ネットワークインストーラーを実行します。

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

インストーラーは次の手順を実行します。

1. 前提条件のチェック。 インストーラーは実際の Python 3.10 以上のインタープリターを探し、2 つのランタイムライブラリ（click と rich）がインポート可能であることを確認します。いずれかが欠けている場合は、その名前を示して停止し、インストールコマンドを表示します。パイプ経由の実行はプロンプトを表示できないため、プロンプトなしでインストールするには APOTHEM_AUTO_INSTALL_DEPS=1 を設定してください。
2. ソースの配置。 同梱のツリーは ~/.apothem にクローンされます（APOTHEM_HOME 環境変数で上書きできます）。再実行すると、既存のクローンを複製するのではなく、そのクローンでリリースタグをチェックアウトします。
3. プロファイルのブートストラップ。 まだプロファイルがない場合、インストーラーはサンプルプロファイルを ~/.config/apothem/profile.yaml にコピーし、同じ実行の中でそのプロファイルから Claude Code をインストールして検証します。また、識別情報のフィールドがプレースホルダーであることを警告します。

環境変数でインストールを制御できます。 最もよく使う可能性が高いものは次のとおりです。

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

インストーラーがインストールするのは、ユーザースコープのハーネスだけです。 プロジェクトスコープのハーネスは、その後でプロジェクトを指定してインストールします。

apothem install --harness cursor --project /path/to/project

ほかに認識される変数は、APOTHEM_REPO と APOTHEM_REF です。これらは、どのリモートをクローンし、どの git ref をチェックアウトするかを指定します。未設定の場合は、最新の署名付きリリースタグを解決して検証します。タグを設定するとそのタグに固定され、移動するブランチには main を設定します（ブランチは署名付きタグではないため、APOTHEM_ALLOW_UNVERIFIED=1 も必要です）。APOTHEM_ALLOW_UNVERIFIED=1 は、タグ署名の検証失敗を警告に格下げし、main のようなタグ以外の ref を許可します。APOTHEM_SOURCE は、クローンの代わりに既存のローカルチェックアウトを使います。APOTHEM_SKIP_VERIFY=1 は、インストール後の検証をスキップします。この検証は実行しておきたいので、未設定のままにしてください。

インストーラーは完全な実行を終えると、エンジンの呼び出し方を示すバナーを出力します。 インストーラーは apothem の shim を PATH 上に配置する（POSIX: $HOME/.local/bin、Windows: %LOCALAPPDATA%\Microsoft\WindowsApps）ため、そのディレクトリが PATH に入っていれば、エンジンを直接実行できます。

apothem <command>

shim を配置できなかった場合 — またはそのディレクトリがまだ PATH 上にない場合 — バナーは shim を必要としない自己完結型のフォールバックを出力します。

PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>

このチュートリアルの残りでは apothem <command> と書きます。フォールバック形式を使っている場合は、インストーラーのバナーが出力した正確なプレフィックスを前に付けてください。

ステップ 2 — プロファイルを自分のものにするCopy Anchor Link

~/.config/apothem/profile.yaml にある共有プロファイルが、唯一の信頼できる情報源です。 すべてのハーネスアダプターがこれを読み取り、そこからそのハーネスのネイティブ設定を導出します。 一度編集すれば、インストールするすべてのハーネスが一貫した状態を保ちます。

エンジンのエディター、または任意のテキストエディターで開きます。

apothem profile edit

最小限の有効なプロファイルは次のようになります。

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

プレースホルダーの name をあなた自身の名前に置き換え、すべてのハーネスに適用させたいルールを追加します。 例の値は架空のままにしてください — プロファイルは共有しても安全であることを意図しています。

エンジンがあなたの編集を問題なく読み戻せることを確認します。

apothem profile show --json

YAML の形式が不正な場合は、ここでそれが分かります — 先に進む前に修正して再実行してください。

ステップ 3 — ハーネス構成をマテリアライズするCopy Anchor Link

ステップ 1 の実行でプロファイルが作成された場合、プレースホルダーの識別情報を使って Claude Code がすでにインストールされています。ステップ 2 でプロファイルを編集してから、次のコマンドで自分の識別情報を適用してください。

apothem update --harness claude-code

apothem install --harness claude-code

これはあなたのプロファイルを読み取り、Claude Code のネイティブ設定を書き込みます。 対象にできるすべてのハーネスを確認するには、次を実行します。

apothem harnesses list

一部のハーネスはユーザースコープではなくプロジェクトスコープであり、それらにはアダプターが書き込み先を判断できるように --project パスが必要です。

apothem install --harness cursor --project .

ステップ 4 — 検証して初回実行を確認するCopy Anchor Link

マテリアライズは話の半分にすぎません。 次に、構成が正しく配置されたことを確認します。

apothem verify --harness claude-code

verify は、ハーネスの管理対象の設定ファイルが存在し、パースできることをチェックします。 --profile PATH を追加すると、インストール済みのファイルがそのプロファイルから生成される内容からずれている場合にも失敗します。 クリーンな実行は、マテリアライズが成功したことを意味します。

登録済みのすべてのアダプターを対象とする、マシン全体のヘルスチェックを行うには、次を実行します。

apothem doctor

doctor はインストール済みのすべてのハーネスをチェックし（各ハーネスは検証に合格しなければならず、その登録済みのフックコマンドは起動しなければなりません）、いずれかのチェックが失敗した場合は非ゼロで終了します。 インストールしていないハーネスは一覧に表示されますが、それによって失敗にはならないため、セットアップスクリプトでの有用なゲートになります。

初回実行。 設定したばかりのハーネス — この例では Claude Code — を開き、任意のプロジェクトでセッションを開始します。 プロファイルに書いたルールと設定は、いまやそのツールの振る舞いの一部です。 これが動作する初回実行です。ステップ 2 で編集したプロファイルが、実際のセッションを形作っています。

作ったものCopy Anchor Link

空のマシンから始めて、Apothem をインストールし、共有プロファイルを作成し、そこからハーネスのネイティブ設定をマテリアライズし、結果を検証し、それが動作することを確認しました。 プロファイルは永続するアーティファクトです — 一度変更し、apothem update --harness <name> を再実行すれば、その変更を任意のハーネスへ送り出せます。

次に進む先Copy Anchor Link

• 別のツールを追加する。 ハーネス一覧は、サポートされているすべてのプラットフォームとそのアダプター名を扱っています。 新しい --harness でステップ 3 を繰り返してください。
• 1 つのタスクをより深く掘り下げる。 ハウツーレシピは、ハーネスの追加、プロファイルの編集、インストーラーの操作を扱います。 利用ガイドは、ルールの記述、プランの作成、コンフォーミティゲートの実行を扱います。
• 具体的な内容を調べる。 リファレンスは、各アーティファクトクラスとプロファイルスキーマを文書化しており、CLI リファレンスはすべてのコマンドを扱います。 各アダプターには、ハーネスの下に専用のページがあります。
• セッションより長く続く作業を計画する。 再開可能なプランニングでは、Apothem が長時間に及ぶ作業をプロジェクトローカルの .apothem/plans/ スイートへ外部化し、どのマシン上の新しいセッションでもその作業をその場で再開できるようにする方法を説明します。

推奨される次のステップCopy Anchor Link

さらにハーネスを追加する作業に進む前に、apothem doctor を実行してセットアップを確認してください — このコマンドは登録済みのすべてのアダプターの状態を報告するため、インストールしたばかりのハーネスは正常と表示され、残りは未インストールと表示されます。