using-entire

Entire の使い方

コードを調査したり理解したりするときの基本方針は、記録された意図を読み、推測しないことです。

Entire のチェックポイントには、エージェント主導の変更それぞれの背景にあるプロンプト、トランスクリプト、判断が記録されています。コードが存在する理由や、モジュールがどのように進化したかを知る必要があるときは、まずチェックポイントの履歴を調べてください。履歴がない場合に限り、コード構造からの推測に頼り、その旨を明記してください。

このスキルが有効になる場合

次のようなタスクでは、このスキルを使用してください。

• 「X を調査して」「X を調べて」「X を探って」「X を掘り下げて」「X の仕組みを調べて」のような依頼
• 不慣れなモジュールやファイルの調査、理解
• 自分が書いていないコードのリファクタリング、拡張、デバッグの準備
• 「なぜこうなっているのか？」「意図は何だったのか？」への回答
• 変更を加える前の調査
• 履歴の情報が役立つコードベースの調査全般

調査や探索を求める依頼では、最初に行うのは search スキルを使った entire search です。最初にソースファイルを開いたり、grep を実行したりしないでください。記録された履歴には、何が試され、なぜそうしたのかが記されています。コードを読むのは、その後の確認のためです。

すでに十分な背景を把握している、単純で明確な編集（例：「5 行目にコメントを追加」）には、このスキルを使用しないでください。

最初のステップ：リポジトリの状態を確認する

個別の調査に入る前に、Entire が利用可能か、リポジトリにチェックポイントの履歴があるかを確認してください。

entire status

これにより、Entire が有効か、どの git フックがインストールされているか、メタデータブランチが初期化されているか、現在のブランチにアクティブなセッションがあるかを確認できます。

シナリオの振り分け

このスキルが有効になったら、ユーザーのニーズに最適なサブスキルを判断してください。

シナリオ	ユーザーによる典型的な表現	委任先
コードブロックの由来	「なぜこうなっているのか」／「何が起きているんだ」／「src/auth.ts:42 で何があったのか」／「なぜこれが変更されたのか教えて」	what-happened
トピックの調査、探索	「X を調査して」／「X を調べて」／「X を探って」／「X を掘り下げて」／「X について何がわかっている？」	まず search、必要に応じてこのスキルの調査フローへ
過去の作業を探す	「以前に誰かが X をやったことはある？」／「レート制限に関する過去の作業を検索して」／「以前の実装を見つけて」	search
タスクの手順を思い出す	「これを以前にやったことはある？」／「X をどうやったか思い出して」／「前回はどうやった？」	recall
機能の履歴をたどる	「 をたどって」／「X がどのように作られたか順に説明して」／「Y の変遷を見せて」	replay
リポジトリのトピックを教える	「 について教えて」／「このリポジトリで はどう動く？」／「X について解説して」	teach
本来の意図を理解する	「この関数を説明して」／「parseConfig を説明して」／「src/auth.ts の意図は何だった？」	explain
ディスパッチ／要約の生成	「最近の作業を要約して」／「ディスパッチを生成して」／「今週達成したことは？」	entire dispatch を直接実行
意図を踏まえたコードレビュー	「これらの変更をレビューして」／「このブランチをレビューして」／「マージ前に監査して」	review
別のエージェントへの引き継ぎ	「このセッションを引き継いで」／「別のエージェントで続けて」／「codex セッションを再開して」	session-handoff
セッションをスキルに変換	「これをスキルにして」／「このセッションからスキルを作って」	session-to-skill
セッションを他のリポジトリにリンク	「セッションを他のリポジトリにリンクして」／「セッションを foo リポジトリに追加して」	session-crosslink
一般的な探索	「このモジュールを理解したい」／「認証の仕組みを調べて」／「コードベースの理解を手伝って」	(自分で対応 — 以下を参照)

シナリオが明確にサブスキルに該当する場合は、そのスキルのワークフローに全面的に委任してください。ここに記載された手順を重複して実行しないでください。

一般的な調査の流れ

特定のサブスキルが当てはまらない場合（たとえば、ユーザーから「このモジュールを理解したい」や「認証の仕組みを調べたい」と依頼された場合）は、次の流れを使用します。

1. 対象領域の主要なファイルを特定します（エントリーポイント、主要な型、コア関数）。

2. 各主要ファイルにチェックポイントがあるか確認します。

git log --format='%H %s' -5 -- <file>

コミット本文にある Entire-Checkpoint: トレーラーを探します。

git log --format='%H %b' -5 -- <file> | grep -B1 'Entire-Checkpoint:'

3. チェックポイントのあるコミットの意図を読み取ります。トレーラーからチェックポイント ID を抽出し、非対話型で利用するために JSON 出力を使用します。

entire checkpoint explain --checkpoint <checkpoint-id> --json --no-pager

チェックポイント ID ではなくコミットハッシュしかない場合は、次を使用します。

entire checkpoint explain --commit <sha> --no-pager

4. 統合します。記録された意図（チェックポイント由来）と現在のコード構造を組み合わせて、包括的な理解をまとめます。

5. 調査結果を報告し、次の内容を明確に区別します。

   • チェックポイントのトランスクリプトに裏付けられた事実（「記録された意図」と表記）
   • コードのみから推測した観察（「コードからの推測」と表記）

AI エージェントの使用上の注意

エージェントのサブプロセスから Entire のコマンドを実行する場合：

• 対応しており、対話形式のプロンプトが表示される可能性のあるコマンドには、必ず --json を渡してください。--json を指定すると、非対話型の出力になります。
• サブプロセスのコンテキストでページャーが起動しないよう、必ず --no-pager を渡してください。
• entire checkpoint explain には、必ず --checkpoint <id> または --commit <sha> を指定してください。ロケーターを指定しないと、コマンドは対話型の選択画面に切り替わります。

チェックポイントが存在しない場合

対象のコードが Entire の導入前のもの、またはチェックポイントがない場合：

1. 「このコードには Entire のチェックポイント履歴がありません」と明示します。
2. 標準的なコード調査（ソースを読む、git log を確認する、呼び出し箇所を追跡する）を進めます。
3. すべての説明に「コードからの推測 — 記録された意図による裏付けなし」と明記します。
4. ユーザーがさらに詳しい履歴を求めている場合は、関連キーワードで search することを提案します。特定のファイルが直接対象になっていなくても、関連する作業についてチェックポイントが見つかる可能性があります。

透明性の原則

回答が次のどちらに基づいているかを、常に明確にします。

• チェックポイントで裏付けられた履歴 — 実際のセッショントランスクリプトを読み、開発者が明示した意図を把握している
• コードからの推測 — コード構造を分析し、意図として考えられる内容を推論している

推測した意図を、記録された事実であるかのように示してはいけません。このワークフローの中核的な価値は、その区別にあります。

参考資料

サブスキルで扱われている内容を超えて Entire の機能を詳しく知るには、次のリソースを参照してください。

• CLI のヘルプ：entire help を実行すると、使用可能なすべてのコマンドとフラグを確認できます
• ドキュメント：https://docs.entire.io/llms.txt — LLM やコーディングエージェントが直接利用できるように作られた、llms.txt 標準に準拠する AI 向けドキュメントのインデックスです