cavekit-methodology

Cavekit の方法論

中核となる原則：構築の前に仕様を定める

エージェントに構築方法を指示する前に、作りたいものを必ず定義してください。cavekit の段階を経てください。生の要件から実装へ直接進んではいけません。

Cavekit は、開発プロセスの中心にキットを置き、コードはキットから導き出すものであり、その逆ではないという、AI コーディングエージェントを使ったソフトウェア構築の方法論です。ゼロから始める場合も、既存システムを近代化する場合も、原則は同じです。

• 新規プロジェクト： 参考資料 → キット → コード
• 書き換え： 古いコード → キット → 新しいコード

どちらの場合も、キットはエージェントが継続的にアプリケーションを構築、検証、改善するために利用する、生きた契約となります。

キットが第一級の存在である理由

特性	利点
構造化されている	ナビゲーション可能なツリーとして整理されているため、エージェントは必要なものだけを読み込めます
人間が読みやすい	エンジニアはコードよりも高いレベルで要件を監査できます
技術スタックに依存しない	特定のフレームワークや言語に依存しません
個別に進化できる	実装に触れることなく、キットを改善できます
検証可能である	すべての要件に、エージェントが確認できる受け入れ基準が含まれます

重要な洞察： 強力な検証機能を備えた、よく記述されたキットがあれば、アプリケーションを再現可能にできます。どのエージェントでも、キットだけからアプリケーションを再構築できます。これは継続的な再生成と考えてください。

---

科学的方法との類似性

LLM は本質的に非決定的です。実験を行う場合と同様、個々の呼び出しごとに異なる結果が得られる可能性があります。しかし、明確な仮説、制御された条件、反復試行という適切な方法論を通じて、確率的なプロセスから信頼性と再現性のある結果を引き出します。

Cavekit は科学的方法をソフトウェア構築に適用します。仮説を立て、テストし、観察し、改善します。

レイヤー	類似するもの	役割
LLM の呼び出し	個々の実験	実行ごとに異なる結果が得られる可能性があり、単一の出力を決定的なものとはみなしません
キット	仮説	予測される動作、つまり観察できると期待することを定義します
検証ゲート	制御された条件	有効な結果とみなされる条件を制約し、再現性を確保します
収束ループ	反復試行	繰り返し処理を通じて、統計的な確信度を高めます
実装の追跡	実験ノート	試したこと、うまくいったこと、失敗したことを記録します
改訂	仮説の見直し	結果が予想に反する場合、理論を上流で更新します

その結果、確率的な生成の上に、規律ある反復可能なエンジニアリングプロセスが構築されます。

---

5 つの Hunt フェーズ

Hunt は 4 フェーズのライフサイクルです。Sketch、Map、Make、Check の各フェーズには、それを推進する専用のプロンプトがあります。

フェーズ	入力	出力	AI の役割	人間の役割
Draft	参考資料、ドメイン知識、既存システム	実装に依存しないキット	要件を抽出し、知識を構造化する	キットが意図を正確に捉えているか確認する
Architect	キット＋フレームワークの調査	フレームワーク固有の実装計画	アーキテクチャを設計し、作業を細分化し、手順を順序付ける	アーキテクチャの選択を承認する
Build	計画＋キット	動作するコード＋テスト＋追跡用ドキュメント	コードを記述し、テストを実行し、キットとの整合性を確認する	逸脱や障害要因に注意する
Inspect	失敗した検証、ギャップ、手動修正	改訂を通じて更新されたキット／計画	根本原因を特定し、修正を上流に反映する	結果を評価し、優先順位を設定する
Monitor	実行中のアプリケーション、Git の履歴	問題、異常、進捗レポート	リグレッションを検出し、指標を提示する	レポートを解釈し、次のステップを導く

フェーズの移行

次のフェーズに移る前に、各フェーズのゲート条件を満たす必要があります。

1. Draft → Architect： すべてのドメインに、テスト可能な受け入れ基準を備えたキットがあります。人間が完全性を確認しています。
2. Architect → Build： 計画でキットを参照し、実装の順序を定義し、テスト戦略を含めています。アーキテクチャ上の決定が検証済みです。
3. Build → Inspect： コードがビルドされ、現在のカバレッジレベルでテストに合格し、実装の進捗状況が最新です。
4. Inspect → Monitor： 収束が検出されています（反復ごとに変更が減少しています）。残りの変更は軽微です。
5. Monitor → Draft（サイクル）： ギャップが見つかった、または新しい要件が特定されました。キットを改訂し、サイクルを再開します。

人間がレビュアーおよび意思決定者として機能し、実際にコーディングを行わないのがInspectフェーズです。プロセスを監視し、必要に応じて変更を依頼し、キットとプロンプトを体系的に改善します。

Hunt フェーズの全リファレンスについては、references/hunt-phases.md を参照してください。

---

意思決定マトリックス：Cavekit を使用するタイミング

フル Cavekit

プロジェクトのスコープが大きい場合、要件が変化する場合、またはエージェントによる自律的な実行が必要な場合に使用します。

指標	しきい値
コードベースの規模	ソースファイルが50個以上
要件	変化する、複数のドメインにまたがる
エージェントの連携	マルチエージェントまたは複数プロンプトのパイプライン
環境	本番環境、セキュリティ重視、既存システム
チーム構成	複数チームまたはチーム間連携
実行モード	長時間にわたる自律的な作業（夜間、無人）

得られるもの： Hunt の全ライフサイクル、キット／計画／実装の進捗管理を含むコンテキストディレクトリ、プロンプトパイプライン、収束ループ、改訂、検証ゲート。

軽量 Cavekit

スコープが中程度の場合、つまりアドホックな進め方では複雑すぎるものの、フルパイプラインを導入するほどではない場合に使用します。

指標	しきい値
コードベースの規模	ファイル数が5～50個
要件	ほぼ明確で、対象が絞られている
エージェントの連携	単一のエージェント。サブエージェントを使用する場合もあります
実行モード	反復ループをときどき実行する対話形式

実施内容：

1. 要件をまとめた context/kits/cavekit-task.md を作成します
2. 実装の順序を定めた context/plans/plan-task.md を追加します
3. Hunt 全体は省略し、計画に沿って反復ループを実行します

これが「Cavekit の最低限」です。複数フェーズのフルパイプラインのようなオーバーヘッドをかけずに、メリットの大部分を得られます。

Cavekit を省略する

タスクがごく小規模な場合に使用します。

指標	しきい値
コードベースの規模	ファイル数が5個未満
タスクの種類	一度限りのツール、簡単なバグ修正、探索的なプロトタイプ
実装	外部参照を必要とせず、1回のエージェントセッションで無理なく完了できる

目安： タスク全体が余裕をもって1つのコンテキストウィンドウに収まるなら、フル Cavekit は価値よりもオーバーヘッドのほうが大きくなります。

拡張の進め方

プロジェクトが小規模でも、まずは軽量 Cavekit から始めます。スコープが拡大しても、拡張するための構造がすでに整っています。大規模なコードベースに後からキットを追加するより、最初から cavekit ディレクトリを拡張していくほうがはるかに簡単です。

---

CI パイプラインとの類似性

Cavekit はビルドパイプラインを模しています。各段階で入力を検証済みの出力に変換し、フィードバックループを通じて修正を上流へ反映します。

Traditional CI/CD:
  Code → Build → Test → Deploy

Cavekit AI Pipeline:
  Cavekit Change
    → Generate Plans (iteration loop)
    → Generate Implementation (iteration loop)
    → Validate (Tests + Review)
    → Human Audit (Monitor & Steer)
    → [Gap Found]
    → Revise
    → Cavekit Change (cycle repeats)

各段階は反復ループとして実行できます。出力が安定するまで、同じプロンプトを繰り返し実行します。この反復ループによって、非決定的な LLM の出力が、予測可能で検証済みのソフトウェアへと変換されます。

イテレーションループ

イテレーションループは、Cavekit における基本的な実行単位です。同じプロンプトを同じコードベースに対して複数回実行し、実行間の差分がほぼゼロになるまで繰り返します。

仕組み：

1. 現在のコードベースに対してプロンプトを実行します
2. エージェントが git の履歴と追跡ドキュメントを調べ、これまでに完了した作業を把握します
3. エージェントが変更を適用し、進捗をコミットします
4. ステップ 1 に戻ります

収束の兆候： 繰り返すごとに変更量が減っていき、差分が毎回小さくなり、最後には見た目上の変更だけが残ることです。目指すのは完全なゼロではなく、効果が徐々に小さくなる状態です。

ループが安定しない場合、問題は上流にあります。繰り返し回数ではなく、入力（仕様、検証、調整）を改善してください。

実行間で差分が小さくならない場合：

• キットの内容が曖昧で、エージェントが実行のたびに異なる解釈をしています
• 検証基準が緩すぎて、エージェントが正しくできたか確認できません
• 複数のエージェントが互いの作業を上書きしており、担当範囲が明確ではありません

---

サブスキル間の相互参照

Cavekit は連携して機能するテクニックで構成されています。この方法論スキルはインデックスであり、以下の各サブスキルはそれぞれ独立している一方、ほかのスキルも相互に参照します。

基礎スキル

スキル	目的	使用するタイミング
ck:cavekit-writing	テスト可能な受け入れ基準を備えた、実装に依存しないキットを作成します	ドラフトフェーズ — 常に最初のステップです
ck:context-architecture	段階的開示を前提にコンテキストを整理します	プロジェクトのセットアップ時および継続的なメンテナンス時
ck:impl-tracking	実装の進捗、行き詰まり、テストの健全性を追跡します	構築フェーズおよび検査フェーズ
ck:validation-first	エージェントが実行できる検証ゲートを設計します	すべてのフェーズ — 検証は継続的に行います

パイプラインスキル

スキル	目的	使用するタイミング
ck:prompt-pipeline	Hunt 用の番号付きプロンプトパイプラインを設計します	自動化のセットアップ時
ck:revision	バグをキットまでたどり、根本原因から修正します	検査フェーズ — 問題を見つけた後
cavekit:brownfield-adoption	既存のコードベースに Cavekit を導入します	レガシープロジェクトで Cavekit を開始するとき

高度なスキル

スキル	目的	使用するタイミング
ck:peer-review	2 つ目のエージェントを使って、最初のエージェントの成果を検証します	品質ゲート、アーキテクチャレビュー
cavekit:speculative-pipeline	並列化のためにパイプラインの各段階をずらして実行します	長いパイプラインを最適化するとき
ck:convergence-monitoring	収束と上限への到達を検出します	イテレーションループの監視
cavekit:documentation-inversion	ドキュメントをエージェントが利用できるスキルに変換します	ライブラリ／モジュールのドキュメント作成

既存のスキルとの連携

Cavekit は既存のスキルを置き換えるのではなく、既存のスキルと連携して機能します。

既存のスキル	Cavekit との連携
superpowers:brainstorming	要件を検討するため、cavekit の生成時に使用します
superpowers:writing-plans	構造化された計画を立てるため、計画の生成時に使用します
superpowers:test-driven-development	Cavekit 内での TDD：cavekit の受け入れ基準を失敗するテストにします
superpowers:verification-before-completion	各フェーズのゲート検証に使用します
superpowers:executing-plans	実装フェーズで使用します
superpowers:dispatching-parallel-agents	エージェントチームの調整に使用します

---

クイックスタート

新規プロジェクトの場合（グリーンフィールド）

1. コンテキストディレクトリをセットアップします：

   context/
   ├── refs/           # Source materials (PRDs, language specs, research)
   ├── kits/     # Implementation-agnostic kits
   ├── plans/          # Framework-specific implementation plans
   ├── impl/           # Living implementation tracking
   └── prompts/        # Hunt pipeline prompts
   

2. 参考資料をもとにキットを作成します（ck:cavekit-writing を参照）

3. キットから計画を生成します（ck:prompt-pipeline を参照）

4. 検証ゲートを設けて実装します（ck:validation-first を参照）

5. 実装ドキュメントで進捗を追跡します（ck:impl-tracking を参照）

6. 反復します — 問題が見つかったら、キットを修正します（ck:revision を参照）

既存のプロジェクトの場合（ブラウンフィールド）

1. コンテキストディレクトリを設定する（上記と同じ構成）
2. 既存のコードベースを参考資料として指定する
3. コードからキットを生成する（cavekit:brownfield-adoption を参照）
4. キットが動作と一致していることを検証する — 生成したキットに対してテストを実行します
5. 通常の Hunt に進む — 今後の変更はまずキットを通じて行います

---

まとめ

Cavekit はツールではなく、方法論です。基本的なサイクルはシンプルです。

1. 実現したいことを記述する（テスト可能な基準を含むキット）
2. エージェントに構築させる（計画 → 実装 → 検証）
3. コードではなくキットを修正する（改訂）
4. 収束するまで繰り返す（反復ループ）

エージェントは、制約をより正確に設定するほど、より高い能力を発揮します。明確なキット、自動検証、構造化された反復ループによって、エージェントは自律性を高めながら作業できます。これによってソフトウェアエンジニアが不要になるわけではありません。アーキテクチャに関する判断力、正確なキットを書く能力、「完了」がどのような状態かを見極める直感が、システム全体を機能させるための入力となります。Cavekit は力を増幅するものです。1 人のエンジニアの明晰な思考を、実装パイプライン全体に広げます。