cheez-read

cheez-read

バックエンドの検出

読み取りの形式に応じてバックエンドを選択します。基本的なハーネスツールよりも、コードインテリジェンス対応のバックエンドを優先してください。モデルの調整ではホストの Read／Glob が優先されますが、tilth と LSP は構造（アウトライン、アンカー、シンボルテーブル、トークン予算）を返すため、通常の読み取りでは得られません。

1. tilth MCP： ファイル／範囲の読み取り、リポジトリを考慮した一覧表示、構造アウトライン、トークン数の推定、編集アンカーに対応しています（リファクタリング前には tilth_read、tilth_list、tilth_deps を使用してください）。
2. LSP： シンボルテーブル、定義、ホバー、型に基づく読み取りに対応しています。
3. ネイティブの範囲指定読み取り／一覧表示（フォールバック）： 正確なファイル、表示範囲、ディレクトリ一覧、スナップショットタグ付きの読み取りに対応しています。ただし、形式に対応するコードインテリジェンスバックエンドがなく、ハーネスが最新の内容と行／スナップショットのコンテキストを提供する場合に限ります。

通常のシェルビューアー（cat、head、tail、ls、find）はソースコードのバックエンドではありません。コード以外のパスやデータ／ログの調査にのみ使用してください。

---

例

「src/auth.ts を表示して」

tilth_read(paths: ["src/auth.ts"])

小さなファイルは全内容とヘッダー（# src/auth.ts (258 lines, ~3.4k tokens) [full]）が返され、大きなファイルでは構造アウトラインが自動的に返されます。

「シンボル名で handleAuth 関数を読み取って」

tilth_read(paths: ["src/auth.ts#handleAuth"])

#symbol_name のサフィックスで、シンボルの行範囲が解決されます。名前はわかっていても行番号がわからない場合に使用してください。

「編集前に大きなファイルの簡略アウトラインを取得して」

tilth_read(paths: ["src/auth.ts"], mode: "stripped")

mode:stripped はプレーンなコメントとデバッグログを取り除いたファイル全体を返します。全内容を読む前に構造を確認する場合に便利です。簡略化された読み取りには編集タグが付かず、tilth_write に渡して書き戻すことはできません。

「編集アンカーを取得するため、src/auth.ts の44～89行を読み取って」

tilth_read(paths: ["src/auth.ts#44-89"])

[src/auth.ts#b2c4]
44:export function handleAuth(req, res, next) {
45:  const token = req.headers.authorization?.split(' ')[1];
...
89:}

[path#TAG] ヘッダーは、番号付きの行をファイルの現在の内容に結び付けます。b2c4 を cheez-write の tag にコピーし、その ops で44～89行を指定してください。

「src/handlers/ 以下にある TypeScript ファイルをすべて一覧表示して」

tilth_list(patterns: ["*.ts"], scope: "src/handlers/")

---

基本原則：もっと読むのではなく、賢く読む

読み取りバックエンドはファイルのサイズに応じて自動調整します。小さなファイル（約6000トークン未満）は全内容を返し、大きなファイルは構造アウトラインを返します。バイナリ／生成ファイルはスキップされます（tilth では必要に応じて処理されます）。大きなファイルは行範囲またはシンボルを指定して掘り下げ、バックエンドが対応している場合は、アンカー付きの内容を取得する前に簡略化モードや概要モードを使用してください。

---

対象範囲：コード読み取りバックエンドを使う場合と使わない場合

cheez-read の対象は、追跡対象で解析可能な言語で書かれたソースコードファイルです。シンボルナビゲーション、編集アンカー、または cheez-write による編集が後で必要になる可能性があるファイルが該当します。スマートアウトライン、編集モードのアンカー、セッション内の重複排除、.gitignore を考慮した一覧表示は、バックエンドが担います。

対象範囲と最新性

アクティブなリポジトリを対象とし、ディスク上の最新の内容を取得するバックエンドを使用してください。Tilth は必要に応じて作業ツリーを走査し、Tree-sitter でファイルを解析して、.gitignore を尊重します。ハーネスネイティブのバックエンドを代わりに使用するには、同等の最新性と範囲指定読み取りを提供する必要があります。

実際の運用では、次の点に注意してください。

• 古いインデックスではなく、現在保存されている内容を読み取るバックエンドを優先してください。
• バックエンドがその範囲を明示的にサポートしていない限り、リポジトリ対象のバックエンドを、隣接するワークツリー、システムパス、依存関係のキャッシュに使用しないでください。
• 複数のリポジトリを読み取る場合、呼び出し元のワークフロースキルは cheez-read に入る前に、リポジトリごとに振り分ける必要があります。

cheez-read より別のツールが適している場合については、references/routing.md を参照してください。

---

編集タグ

編集モード（簡略化なし）の読み取りでは、番号付きの N:content 行の上に [path#TAG] ヘッダーが出力されます。簡略化された読み取りにはタグヘッダーが付かず、書き込みに渡して書き戻すことはできません。現在のタグを取得するには、編集前の読み取りが必須です。4桁の16進数の TAG をそのまま cheez-write の tag にコピーしてください。これにより、編集内容が読み取った内容に結び付けられます。内容が変更された場合、書き込みは3方向マージされるか、安全に拒否され、確認なしに適用されることはありません。タグを作り出さないでください。

---

ディレクトリ一覧

ls、find、pwd、Glob の代わりに、リポジトリを認識する一覧表示バックエンドを使用してディレクトリを一覧表示します。tilth を使用する場合：

tilth_list(patterns: ["**/*.ts"], scope: "src/")

出力：

src/auth.ts  (~3.4k tokens)
src/routes.ts  (~2.1k tokens)
src/middleware.ts  (~1.8k tokens)

トークン数の推定値を参考に、全文を読むか概要を読むかを判断してください。tilth が利用できないものの、ハーネスがリポジトリを認識する最新の一覧を提供している場合は、代わりにネイティブの list/glob バックエンドを使用してください。

---

tilth_deps — 影響範囲の確認

tilth_deps(path: "src/auth.ts")

リファクタリング（名前変更、シグネチャ変更、削除）の前にのみ使用してください。 出力形式とファイル／シンボルの区別については、cheez-search の共通リファレンスを参照してください。 ../cheez-search/references/tilth-deps.md。

---

禁止事項

• コードを表示するために cat / head / tail / less / more / bat を使用しないでください — 最新性を認識する読み取りバックエンドを使用してください。ハッシュアンカーと概要／全文のトークン数の割り当ては、バックエンド経由でのみ機能します。
• コードファイルを列挙するために ls / tree / eza / find / fd を使用しないでください — リポジトリを認識する一覧表示バックエンドを使用してください。トークン数の推定と .gitignore のフィルタリングは、バックエンド経由でのみ機能します。
• ハーネスのネイティブな最新性認識バックエンドでない限り、コードパスに対してプレーンなホストの Read または Glob を 使用しないでください。それらを使うと、アンカーと構造的なコンテキストが無視されます。
• 先ほど表示されたファイルを 再度読み込まないでください — 以前の読み取り結果を参照してください。
• コードやテストの実行に 使用しないでください — プロジェクトのビルド／テストスキルを使用してください。
• コミットや公開に 使用しないでください — /plate を使用してください。
• [path#TAG] ヘッダーを 無視しないでください — 編集にはこのタグが必要です。