トークンコスト予測

PRECCはトークンコスト予測のオラクルを搭載しており、複数ステップの計画を実時間ではなくトークンで予算化できます。各ステップの前に予測を記録し、作業完了後に実績を記録すれば、データセットが組み込みの予測器を訓練し、時間とともに精度が向上します。

予測を記録する

計画ステップの一行説明を渡します。PRECCはそれを分類し(feat / fix / test / refactor / measurement / doc / chore / unknown)、トークン数を推定し、ループを閉じるために使うidを出力します。

$ precc predict "Implement read-deltas with mtime check"
id=42 category=feat predicted=5680 tokens (confidence=0.50, model=trained-v1)
Record actual when done: precc predict --record 42 <actual_tokens>

実績を記録する

ステップ完了後、セッションのフッターまたはテレメトリから実際のトークン数を確認し、idを使って書き戻します。

$ precc predict --record 42 6300
Recorded actual=6300 tokens for prediction id=42.

trained-v1 を訓練する

クローズ済みの予測が少なくとも10件あれば、log10(actual) を log10(説明文の長さ) と one-hot のカテゴリダミーに対して trained-v1 リッジ回帰でフィットします。フィッティングは閉形式(リッジ λ=1 の正規方程式に対するコレスキー分解)で、ミリ秒単位で完了します。

$ precc predict --train
Trained trained-v1 on 22 closed predictions (λ=1).
  Model file : ~/.local/share/precc/predict_model.json
  Confidence : 0.50
  Intercept  :  +1.0016
  log_desc   :  +1.2339
  Categories :
    unknown       +0.4811
    doc           +0.4474
    measurement   +0.3422
    test          +0.1071
    refactor      +0.0326
    feat          +0.0071
    fix           -0.1096
    chore         -0.3063

訓練後、新しい precc predict 呼び出しはモデルファイルを削除または置き換えるまで自動的に trained-v1 を使用します。古い予測は元の model_version を保持するため、予測器を時系列で比較できます。

予測器の精度を確認する

precc predict --eval は、平均絶対パーセント誤差(MAPE)を全体およびカテゴリ別に報告し、計算はクローズ済みの予測(予測値と実績値の両方を持つ行)のみを対象とします。

$ precc predict --eval
Predictions logged   : 30
With actuals (closed): 22
Mean predicted       :     1483 tokens
Mean actual          :    47238 tokens
MAPE (statistical)   :     76.4%

By category:
  category        n   predicted      actual    MAPE
  feat            6        4605        5250   26.2%
  unknown         4        1597       30526   52.6%
  test            4         924       38900   56.4%
  ...

最近の予測を一覧表示する

precc predict --list は最近の行を逆時系列で表示します。オープン行(実績なし)はクローズ可能な状態です。

$ precc predict --list --limit 5
id    ts                   category       predicted     actual  conf description
30    2026-05-09 09:40:51  feat                5348          -  0.50 Run the synthetic-fleet pilot...
29    2026-05-09 08:56:48  test                1050          -  0.60 Train predictor: trained-v1...
28    2026-05-09 07:44:18  test                 915     150000  0.60 Implement minimal task-12...

なぜ実時間ではなくトークンか

時間見積もりは事後に測定不可能で、マシンやセッションをまたいで合成できません。トークン数は決定的で比較可能であり、ループを閉じるたびにラベル付きデータセットが増え、予測器が改善されます。オラクルの本質は、見積もりを当て推量から測定に変えることです。

データの保存場所

すべての予測データはローカルマシンに保存されます。何もアップロードされません。

~/.local/share/precc/
├── metrics.db                — predictions table (oracle DB)
└── predict_model.json        — trained-v1 coefficients (after `--train`)

Keyboard shortcuts

PRECC User Guide