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

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

終わるころには次のものが手に入ります。

1. スクリプトインストーラーからインストールされた Apothem。
2. 各ハーネスを駆動する共有プロファイル（編集済み）。
3. マテリアライズされた 1 つのハーネスのネイティブ設定。
4. その構成が検証され、動作する初回実行が確認されたもの。

チュートリアルを通して、例のハーネスとして Claude Code を使います。インストーラーの デフォルトだからです。同じ手順は対応するどのハーネスにも当てはまります。 ハーネス一覧に来たら名前を変えてください。

まず必要なもの

• Unix ライクなシェル（macOS、Linux、または WSL）。PowerShell インストーラーが Windows をカバーします。このチュートリアルは bash の経路を示します。
• PATH 上の Python 3.10 以降。python3 --version で確認してください。
• エンジンがインタープリターからインポートする 2 つのランタイムライブラリ：click と rich。残りのスタック（pyyaml、jsonschema）はツリーに同梱（vendored）されているため、インポート可能である必要があるのはこの 2 つだけです。インストーラーはこれらをチェックし、欠けているものを示し、代わりにインストールするか尋ねるので、確認して続行できます。

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

ステップ 1 — Apothem のインストール

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

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 にコピーし、続行する前に 停止して 編集を求めます。これは意図的です。サンプルはプレースホルダーの識別情報を使っており、 どのハーネス設定も書き込む前にそれを自分のものにすべきだからです。ステップ 2 で 行います。

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

# Install a different harness as the default, and point at a project profile.
APOTHEM_HARNESS=cursor \
APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

認識される他の変数は APOTHEM_REPO と APOTHEM_REF（どのリモートをクローンし、 どの git ref をダウンロードするか。未定義の場合は署名された最新のバージョンタグを 解決して検証し、固定するにはタグを、動き続けるブランチには main を設定）、 APOTHEM_ALLOW_UNVERIFIED=1（タグ署名の検証失敗を警告へ格下げ）、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 — プロファイルを自分のものにする

~/.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 — ハーネス構成をマテリアライズする

インストーラーはステップ 1 ですでにデフォルトのハーネスをマテリアライズしています。これを明示的に 行うには——または 2 つ目のハーネスをマテリアライズするには——install を実行します。

apothem install --harness claude-code

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

apothem harnesses list

一部のハーネスはユーザースコープではなくプロジェクトスコープで、それらはアダプターが どこに書き込むかを知るために --project パスが必要です。

apothem install --harness cursor --project .

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

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

apothem verify --harness claude-code

verify は、ハーネスの期待される設定ファイルが存在し、プロファイルが宣言する内容と 一致していることをチェックします。クリーンな実行は、マテリアライズが成功したことを意味します。

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

apothem doctor

doctor は各アダプターのインストール状態を報告し、登録済みのいずれかのアダプターが 未インストールと報告した場合は非ゼロのコードで終了します。セットアップスクリプトでの 便利なゲートです。

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

作ったもの

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

次にどこへ

• 別のツールを追加する。 ハーネス一覧は、対応する各プラットフォーム とそのアダプター名をカバーしています。新しい --harness でステップ 3 を 繰り返してください。
• 1 つのタスクを深掘りする。 ハウツーガイドは、ルールの記述、 プランの作成、コンフォーミティゲートの実行のための、タスク中心のレシピです。
• 具体的な詳細を調べる。 リファレンスは、各アダプター、 プロファイルスキーマ、そして CLI のすべての面を文書化しています。
• セッションを越えて続く作業を計画する。 再開可能な計画 は、Apothem が長時間の作業をプロジェクトローカルの .apothem/plans/ スイートへ 外部化し、どのマシンでも新しいセッションがその場で再開できる仕組みを説明します。

次の推奨ステップ

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