---
title: トークンコストの考え方
description: 何がコストを決めるのか、実際にかかった額をどう確認するのか、事前に見積もるコマンド
seo:
  image: /ogp.png
---

NexusArchitectは、1回のコマンドで多数のサブエージェントを動かします。
そのため「どれくらいかかるのか」が気になりますが、**具体的な金額をここに書くことはできません**。
コードベースの規模・プロファイル・キャッシュの当たり方で大きく変わるからです。

代わりに、コストを決める要素と、自分の環境で測る方法を説明します。

## 何がコストを決めるのか

1. **実行するフェーズ数(プロファイル)**

    いちばん効きます。`mvp`は3フェーズ、`full`は23フェーズなので、単純にこの比で差が出ます。
    最初は`mvp`で試し、必要になってから範囲を広げるのが安く済みます。

2. **どのモデルが動くか(モデル階層化)**

    「できる中でいちばん安いモデルを使う」方針で組まれています。ファイルを読んで要約するだけの作業はhaiku、
    構造に沿った生成はsonnet、opusは判断が必要なところ(ミニプラン策定・Epic整合性判定)だけです。
    割り当ての一覧は[implement-backlogのページ](/skills/backlog/implement)にあります。

3. **コードベースの規模**

    architect側は既存コードを読み込むので、行数がそのまま入力トークンに乗ります。
    ただし全行を読むわけではなく、構造を調べるツールとサンプリングで一部だけを読みます。

4. **プロンプトキャッシュの当たり方**

    キャッシュから読まれた入力トークンは通常の0.1倍で課金されます。
    同じ文脈を保ったまま連続して作業するほど安くなり、途中で大きく作り直すと高くなります。

## 実際にかかった額を見る

プラグインには、トークン使用量を記録するフック(hook)が最初から組み込まれています。
設定は不要で、実行するだけで`work/token-usage.json`と`work/token-usage.jsonl`に記録が積まれます。

```
/architect:report-token-cost --once
```

合計、フェーズごと、モデルごとのコストが、入力/出力/キャッシュ読み/キャッシュ書きの内訳つきで表示されます。
日ごとの推移やセッションごとのコストも見られます。これは推定ではなく**実測値**です。

## 事前に見積もる

まだ動かしていない作業を見積もりたいときは、次のコマンドを使います。

```
/architect:estimate-token-cost <対象パス>
```

コードの行数からトークン量を概算し、フェーズごとのモデル階層で価格をつけて、
`typical` / `low` / `high`の3つの幅で報告します。結果は`reports/05_estimate/token-cost-estimate.md`に出力されます。

:::warning[見積もりの幅は広いものとして扱ってください]
見積もりに使われる係数は、実測で調整されていない初期値です。high と low で3倍ほど開くことがあります。
何回か実行して`work/token-usage.json`に実測値が溜まると、見積もりはその実測値を使って補正されるようになります。
:::

:::note[サブスクリプションで使っている場合]
`estimate-token-cost`は、課金方式を聞いてから報告の形を変えます。
API/Consoleの従量課金ならUSD建てで、Claudeのサブスクリプションならトークン消費量で報告し、
「金額ではなく利用上限を消費する」ことを明記します。
:::

## 安くするための手段

- **段階的に実行する** — 最初から`full`を通さず、`mvp`で判断できるところまで進める
- **対象範囲を狭める** — `--out`や対象パスの指定で、読み込むコードを絞る
- **文脈を保つ** — 同じ流れの中で作業を続けると、プロンプトキャッシュが効きます
- **止まる場所を意識する** — 途中で止まっても進捗は残るので、作業を分けても再実行のコストは増えません([中断と再開](/concepts/resume))