spar

AIがコードを書く間も、学び続けよう。

完成した説得力のあるコードをレビューしても、ほとんど学べることはありません。それを判断する立場がないので、読んでうなずいて、次に進むだけです。

spar はその立場を取り戻します。エージェントが何かを書く前に、あなたは変更がどこに属するか、自分ならどうするか、どこで壊れるかを言います。それからエージェントが実装し、差分を見せ、あなたのモデルが間違っていたすべての箇所を書き留めます。

そうしたギャップは、自分で選ぶ必要のないカリキュラムとして積み重なります。最も頻繁に間違える概念が自然と上位に浮上し、摩擦もそこに付いてくるので、努力することを自分で決める必要はありません。

どのようなものか

› add an endpoint for cancelling an order

  spar: level 2 (skeleton), 2 open gaps on "transaction boundaries in an ORM"

  Before I write anything:
    1. Where does this belong, and why there?
    2. How would you approach it? (two sentences)
    3. Where will this go wrong?

› 1. Orders controller, calling into the service
  2. load the order, set status, save
  3. no idea

  [writes the controller, the DI wiring and the error handling,
   and leaves the one line that matters]

  // TODO(spar: decide the transaction boundary. Who opens it,
  //             and what happens if the refund call fails halfway?)

あなたはその5行を自分で書きます。それから spar done が、エージェントが書いたであろうものと比較し、各差分を3つのカテゴリに分類します：何かを誤解した、何かを打ち間違えた、またはあなたのバージョンの方が優れている。ギャップとして記録されるのは最初の2つだけです。

3週間後、無関係な作業の最中に：

spar: one gap has come due. Ask them to explain "transaction boundaries in an ORM"
in their own words at the next natural pause. Do not show them the answer first.

「わからない」と答えるのは、もちろん問題ありません。そのまま記録され、その概念に触れる次のタスクが、より多くを求めてくるという十分に強いシグナルになります。

Related MCP server: Learning Assistant MCP Server

インストール

npm i -g spar-agent
spar install                                       # finds your agents, backs up, merges
spar setup --project /path/to/repo --stack ".NET"

最後の行が重要です：名前を付けたディレクトリ以外では何も起こりません。 新しいインストールは完全に不活性です。プロジェクトを指定するまで、~/.spar すら作成しません。

spar install は、自分が書いていないファイルには注意を払います。既存のものにマージし、まずバックアップを取り、自分が置いたエントリだけを置き換えます。2回実行しても、2回目は何も変更しません。--dry-run で何をするかを確認できます。

現在地

spar stats        # in the terminal
spar dashboard    # one self-contained HTML file

CALIBRATION, share of predictions that held, by week
  2026-07-13  ███████▁▁▁   67%     4/6   clean   mean level 2.3
  2026-07-20  ████▁▁▁▁▁▁   44%     4/9   clean   mean level 2.3
  2026-08-03  ████████▁▁   83%    10/12  clean   mean level 0.8
  2026-08-17  ██████████  100%     9/9   clean   mean level 0.3

CURRICULUM, concepts by weakness. The top row is what to learn next.
  * idempotency in webhooks              3 open / 3   box 1.3
    transaction boundaries in an ORM     8 open / 8   box 2.0
    EF change tracking                   0 open / 3   box 5.0

重要な数字はキャリブレーション、つまり誤解を生まなかった予測の割合です。意図的にギャップ数ではありません。なぜなら、数は増える一方で、上達しているまさにその時に衰退として読まれてしまうからです。

架空の.NETオンボーディングの6週間分。ページはシステムのテーマに従います。

ダッシュボードはネットワークに一切触れない単一のファイルです。CDNも、Webフォントも、チャートライブラリもなく、チャートは手書きのSVGです。すべての数字がマークアップ内にあるため、スクリプトを無効にしても、厳格なCSPの背後でも、添付ファイルのプレビューでも、ページは同じように読めます。スクリプトはフォーカスバーに複数選択を追加するだけです。5年後も、ダブルクリックでオフラインで開くことができます。

その中にストリーク、ポイント、バッジは一切ありません。「わからない」が有用な答えであるツールでは、カウンターは偽りの能力を身につけさせるだけだからです。

絵で説明する

spar card --layout chain --title "Predict before you're told" \
  --subtitle "The gap between your guess and what was true is worth writing down." \
  --step "you:You predict" --step "agent:AI implements" --step "you:You compare"

カード1枚につき1つのアイデアを、~/.spar/cards/ に書きます。4つのレイアウトがほとんどの説明をカバーします：ステップの連鎖、ファンアウト、2者間のシーケンス、比較です。

制限は提案ではなく強制されます。5ステップ以上、3つの箇条書き以上、または4つ目の色の役割があると、コマンドはレンダリングを拒否します。これは意図的です。なぜなら、小さな絵の価値は小さく保たれたことにあるのであり、プロンプトにしか存在しないルールは漂流するからです。レンダリングされない場合、答えは2枚のカードです。

色は何が何であるかを示し、どのステップであるかは示さないので、--step "you:..." は、作成するすべてのカードで you を同じ色に保ちます。~/.spar/config.json の cards.theme で外観を選択します：neon（デフォルト、暗い背景に輪郭のあるボックス）または plain。

レベル

レベル2と3では、エージェントは常に失敗するテストを残し、spar はそれがなければ引き継ぎを拒否します。テストのないマーカーは、推測と、それを確認する手段のないものを渡すことになります。自分が正しかったかどうかを知る唯一の方法はエージェントに尋ねることですが、それはこのツール全体が断ち切ろうとしている依存関係です。テストこそが、20分間一人で作業しても、それでも分かることを可能にするものです。

プロジェクトに testCommand を設定すると、spar は引き継ぎ時にスイートも実行し、それが赤であることを期待します。なぜなら、空のスタブに対してすでにパスするテストは何も固定しないからです：

spar setup --project "$(pwd)" --test-command "npm test"

このチェックはデフォルトでオフです。他人のスイートを自動的に実行するのは侵襲的で、遅くなる可能性があります。

オフスイッチはなく、レベル0だけです。自分のギャップログがレベルを提案し、その理由を説明します。いつでも却下できます。却下はカウントされます。なぜなら、提案を常に修正している人は、しきい値が間違っていることを示しているからです。

チケットを段階的に処理する

spar plan --from docs/plan.md          # reads ## Task / ### Task headings
spar plan --step "..." --step "..."    # or name the steps yourself
spar plan                              # where am I
spar step done --session <id>

プランがアクティブな間、ステップがタスクです。ゲートは沈黙から推測するのではなく、ステップごとに1回発動し、各ステップはギャップログから独自のレベルを取得し、予測はセッションではなくステップに結び付けられるため、明日もそこに残ります。

その粒度こそが要点です。「どこでうまくいかなくなるか？」は「キャンセルエンドポイントを追加する」に関する実際の質問であり、「返金付きキャンセルを実装する」に関する推測です。推測はキャリブレーション数値の測定を無意味にします。

spar は計画を立てません。エージェントがチケットを読み、プランナーがそれを分割します。spar は各ステップのうちどれだけがあなたのものかを決定します。プランはプロジェクトの .spar/ に置かれ、spar は作成した瞬間に .gitignore に追加します。

各エージェントが得られるもの

MCPはフックが標準化されていない場所で標準化されているため、サーバーはアダプターなしですべてのMCPクライアントに到達します。唯一できないことはゲートです。MCPサーバーはツールを提供し、ホスト自身の書き込みを傍受することは決してないからです。この制限こそが、エージェントごとのフックアダプターを維持する全体的な論拠であり、自主的な層が良い試用にはなるが、代用としては不十分である理由です。

プラグインとしてインストールする

/plugin marketplace add Lander-Parren/spar

これにより2つのプラグインが提供されます。spar はこのリポジトリです。humanizer はオプションで、私のものではありません：blader/humanizer、MIT、Copyright (c) 2025 Siqi Chen、mainブランチを追跡するのではなく、特定のコミットに固定されています。

これは spar にコピーされるのではなく、spar と並んでリストされるため、独自のリポジトリから更新され、独自の作者を維持します。それがそこにある理由：spar はその生涯を通じて、まだ混乱している人に何かを説明することに費やしており、機械が書いたように読める説明は、彼らを失う最も速い方法です。spar 自身のスキルには、それをインストールしない人のための短いバージョンのルールが含まれています。

やらないこと

すべてはあなたのマシン上の ~/.spar/ に留まります。アカウントも、テレメトリも、ネットワーク呼び出しも、独自のAPIキーもありません。ログにはビジネスロジックではなく、概念と誤解が保持されるため、同僚にスクリーンショットを見せても安全です。

そして、常にフェイルオープンです。バイナリの欠落、設定の破損、自身のコードのバグ：ゲートは開き、あなたは続行します。学習ツールが、出荷できない理由になるべきではありません。

タスクごとに1回であり、ファイルごとではありません。1つの予測の背後にある15回の編集は、1つのゲートです。

書き込みツールだけでなくシェルコマンドも監視します。なぜなら、エージェントは専用の書き込みツールよりも cat > file <<EOF や perl -0pi に手を伸ばすことがはるかに多く、一部のセットアップはまさにそれを好むように指示するからです。シェルコマンドは、追跡対象プロジェクト内のどこかに実際に書き込む場合にのみ停止されます：リダイレクト、tee、インプレースの sed と perl、cp と mv の宛先、および書き込み用にファイルを開くインタープリターのワンライナー。読み取りとテスト実行はそのまま通過します。シェルは正規表現で解析できないため、これは意図的に保守的であり、通常の作業を停止するのではなく、風変わりな形式を見逃します。

タスクは、その中に動きがある限り存続し、30分間の沈黙（~/.spar/config.json の idleMinutes）で失効します。これは経過時間ではなくアイドル状態を測定するため、長く慎重なタスクが途中で中断されることはありません。タイマーが切れる前に新しいことを始める場合は、spar next --session <id> ですぐに再武装します。

バイアスは意図的です。フォローアップで再武装すると30秒かかり、spar rush へと促します。これはこれらのツールが死ぬ方法です。1つのタスクを逃すと、1つのギャップが発生し、その概念はまた巡ってきます。

1つのギャップがセッション開始時に、次の自然な休止のための質問として戻ってきます。キューも、中断もありません。うまく答えれば、ボックスを1つ上がります（1、3、7、16、35日）。うまく答えなければ、明日やり直しです。

無視できる別のアプリや受信トレイはありません。なぜなら、それはすでに作業していたセッションに届くからです。

リスクを冒さずに試す

example/ は依存関係のない小さなTypeScriptプロジェクトで、指し示すために作られています。

cd example
spar setup --project "$(pwd)" --stack "TypeScript"

それからエージェントに注文キャンセルを追加するように依頼し、ゲートがそれを止めるのを見てください。example/README.md に何を探すべきかが説明されています。

指示が置かれている場所

コマンドは事実を出力します。スキルはそれらをどうするかを示します。spar done は差分を出力します。誤解とみなされるものとタイプミスとみなされるものはスキルにあります。ゲートはタスクがゲートされていないことを報告し、コマンドを指名します。なぜ先に予測するのかはスキルにあります。

この分割は、手順がスキル対応のクライアントならどれでも読めて、リリースなしで変更できるようにするために存在します。スキルを読み込めないエージェントのために、spar guide <topic> は同じファイルから同じセクションを出力します：

spar guide                       # list the topics
spar guide the-closing-review

1つのソース、2つの配信方法。これにより、2つが乖離することはありません。テストは、フックが指すすべてのセクションが実際に存在することを検証するため、見出しの名前を変更すると、存在しないページに誰かを送るのではなく、ビルドが壊れます。

npm install
npm test              # spar's own suite
npm run build
npm run emit          # regenerate the checked-in hook configs
npm run validate:example   # drive every hook end to end against example/

配線の問題を検出するのは validate:example です。単体テストは部品を証明します。このスクリプトは、実際のフックペイロードが、使い捨てのホームで、ビルドされたバイナリに対して、期待される決定を生成することを証明します。

同じフック定義が3回チェックされています：Claude Codeのプラグインレイアウト、Agent Plugins名前空間、Cursorのもの。2つの標準は、クライアント固有のファイルがどこに属するかについて意見が異なるため、両方を満たす単一の場所はありません。3つすべては src/core/hookconfig.ts から npm run emit によって生成され、テストはそれらが乖離した瞬間に失敗します。

ライセンス

MIT