chisel

Chisel エージェントスキル

Chisel MCP サーバーを利用できます。Chisel は、トークンコストを最小限に抑え、安全性を最大限に高めるよう設計された、精密なファイルシステムツールを提供します。基本原則は次のとおりです。必要な部分だけでよい場合にファイル全体を読み取らず、部分的な変更だけでよい場合にファイル全体を書き換えないでください。

---

⚠️ shell_exec にはシェルインタープリターがありません。 パイプ（|）、&&、||、$()、およびすべてのシェルメタ文字は、リテラルとしてプロセスに渡され、解釈されることはありません。各 shell_exec 呼び出しでは、コマンドが正確に1つだけ実行されます。複数ステップの処理は、別々の呼び出しに分けて組み立ててください。

---

ツールの選択

Need to find something in a file or directory?
  └─ shell_exec (grep / find / sed / awk / stat / ls)

Need to edit an existing file?
  ├─ Small targeted change (< whole file)  → patch_apply
  │    └─ patch_apply fails twice on a small file?  → write_file (see below)
  └─ Overwrite entirely / file is tiny     → write_file

Need to add content to the end of a file?
  └─ append

Need to create a directory?
  └─ create_directory

Need to rename or relocate a file?
  └─ move_file

---

読み取り — 必要のないものは取得しない

まず、必要最小限の範囲を取得してください。最初の呼び出しでコンテキストが足りない場合にのみ、範囲を広げてください。

目的	呼び出し
シンボルが含まれる行を検索する	shell_exec grep ["-n", "symbol", "/root/file"]
複数ファイルからシンボルを検索する	shell_exec grep ["-rn", "symbol", "/root"]
Markdown ファイル内のすべての見出しを一覧表示する	shell_exec grep ["-n", "^#", "/root/file.md"]
見出しでセクションを抽出する	shell_exec sed ["-n", "/^## Section/,/^## /p", "/root/file.md"]
大きなファイルの40〜60行目を読む	shell_exec sed ["-n", "40,60p", "/root/file"]
小さなファイルの全行を行番号付きで表示する	shell_exec cat ["-n", "/root/file"]
出現回数を数える	shell_exec grep ["-c", "pattern", "/root/file"]
ファイルサイズ／行数を取得する	shell_exec wc ["-l", "/root/file"]
ディレクトリの内容を一覧表示する	shell_exec ls ["-la", "/root/dir"]
名前でファイルを検索する	shell_exec find ["/root", "-name", "*.rs"]
ファイルの種類／メタデータを調べる	shell_exec stat ["/root/file"]
ログの末尾を表示する	shell_exec tail ["-n", "50", "/root/app.log"]

約50行を超えるファイルに cat を実行しないでください。 sed -n 'M,Np' で範囲を絞るか、短いファイルでは cat -n を使って、パッチを適用する前に行番号を確認してください。

---

編集 — ファイル全体の書き換えより差分を優先

patch_apply — 主な編集ツール

変更する行だけを送信してください。ファイルはアトミックに書き込まれます。ハンクが一致しない場合は PatchFailed が返され、元のファイルは変更されません。

--- a/src/main.rs
+++ b/src/main.rs
@@ -12,7 +12,7 @@
 fn main() {
-    let port = 3000;
+    let port = 8080;
     start_server(port);
 }

有効なパッチのルール：

• コンテキスト行（接頭辞のない行）は、空白も含めてファイルと完全に一致する必要があります。
• @@ -L,N +L,N @@ の行番号は、現在のファイル状態に対して正確である必要があります。開始行と行数の両方が対象です。ヘッダーの行番号が間違っていると、内容の行が正しくても PatchFailed が発生します。ハンクヘッダーを書く前に、必ず grep -n または cat -n を実行して実際の行番号を確認してください。
• 新しいファイルを作成するには、ソースヘッダーとして --- /dev/null を使用してください。対象のファイルは存在していてはいけません。
• 1回の呼び出しに複数の @@ ハンクを含められます。すべてアトミックに適用されます。

PatchFailed が返された場合：

1. grep -n または sed -n 'L-3,L+3p' を使って、該当する行を正確に読み直します。
2. 実際の内容からパッチを作り直します。コンテキスト行とハンクヘッダーの両方を修正してください。
3. 約100行未満のファイルで PatchFailed が2回発生した場合： ハンクのデバッグを中止します。cat -n でファイル全体を読み、完全に修正してから、代わりに write_file を使用してください。

write_file — 全体の上書き

次の場合に使用します：

• 実質的な初期内容を含む新しいファイルを作成する場合。
• 変更範囲が大きく、差分がファイル全体よりも大きくなる場合。
• ファイルが短く（約30行未満）、全体を書き直すほうが簡潔な場合。
• 短いファイルに対して patch_apply が2回失敗した場合 — write_file は安全な復旧手段です。

append

ログのエントリー、設定への行の追加、または段階的に構築するファイルへの追記に使用します。ファイルはすでに存在している必要があります。

---

shell_exec sed -i によるインプレース変換

一括置換（シンボル名の変更、繰り返しパターンの修正）では、sed がファイルを直接変更するため、差分は不要です。

⚠️ sed -i の書式は macOS（BSD sed）と Linux（GNU sed）で異なります。以下の形式を厳密に使用し、別の形式を独自に試さないでください。

プラットフォーム	引数配列
Linux（GNU sed）	["-i", "s/Old/New/g", "/abs/path/file"]
macOS（BSD sed）	["-i", "", "s/Old/New/g", "/abs/path/file"]

macOS では、空文字列 "" はバックアップサフィックスの引数です（バックアップファイルを作成しないことを意味します）。Chisel はこれを別個の引数として BSD sed に正しく渡します。省略したり、-i.bak に置き換えたり、"-i''" のように -i と結合した1つの引数にしたりしないでください。 形式が異なると、内容の分かりにくい BSD sed の解析エラー（command a expects \…`）が発生し、無駄なやり取りにつながります。

使用中のプラットフォームが不明な場合は、 shell_exec stat ["/proc/version"]（Linux）または shell_exec uname ["-s"] を使って確認してください。また、単一ファイルの編集には、プラットフォームに依存しない patch_apply または write_file を優先してください。

# Linux
shell_exec sed ["-i", "s/OldName/NewName/g", "/root/src/lib.rs"]

# macOS — the "" is mandatory and is passed correctly; do not second-guess this
shell_exec sed ["-i", "", "s/OldName/NewName/g", "/root/src/lib.rs"]

インプレース編集に成功すると、空の標準出力とともに exit_code: 0 が返ります。終了コードが0以外の場合、または標準エラー出力がある場合は、式またはパスに誤りがあります。これらを修正し、-i の形式は変更しないでください。

---

ワークフローパターン

特定 → 該当箇所を読み取る → パッチを適用

トークン消費を抑える標準的な編集手順です。

1. grep -n "target_symbol" /root/file — 行番号を確認します。
2. sed -n "L-5,L+10p" /root/file — 該当箇所の前後を絞って読み取ります。
3. @@ -L,N +L,N @@ ヘッダーが正確に一致することを確認します。
4. patch_apply — その正確な内容に対する差分を送信します。

短いファイルのみ： ステップ1で cat -n /root/file を使うと、すべての行番号を一度に確認できます。ファイルが50行未満の場合、grep と sed の組み合わせより高速です。

不慣れなコードベースを調べる

1. ls -la /root — 最上位の構成を確認します。
2. find /root -name "*.rs" -not -path "*/target/*" — ソースファイルを列挙します。
3. grep -rn "struct MyStruct" /root/src — 定義箇所を特定します。
4. sed -n "L,L+30p" /root/src/file.rs — 構造体本体を読み取ります。

相対パスは自動的にルートを基準にします。 . はルート自体を、subdir/file は root/subdir/file を指します。 絶対パスも使用できます。上位ディレクトリへの移動（../escape）は常にブロックされます。

ボイラープレートを使って新しいファイルを作成する

write_file を使います。ファイルを作成した後の編集には、すべて patch_apply を使います。

多数のファイルにわたってシンボル名を変更する

推奨 — find -exec … {} + を1回呼び出す：

find -exec cmd {} + は、一致したすべてのパスを1回のコマンド呼び出しにまとめます。シェルもループも不要で、一致するファイルの数にかかわらず shell_exec の呼び出しは1回です。

# macOS (BSD sed)
shell_exec find ["/root/src", "-name", "*.rs", "-exec", "sed", "-i", "", "s/OldName/NewName/g", "{}", "+"]

# Linux (GNU sed)
shell_exec find ["/root/src", "-name", "*.rs", "-exec", "sed", "-i", "s/OldName/NewName/g", "{}", "+"]

{} プレースホルダーと + 終端子は、そのまま find に渡されます。シェルのメタ文字ではないため、エスケープは不要です。

代替手段 — ファイルごとに1回呼び出す（find -exec が使えない場合、またはファイルごとの処理が必要な場合のみ）：

1. grep -rl "OldName" /root/src — ファイル一覧を取得します。
2. 各ファイルに対して：
   • Linux： sed ["-i", "s/OldName/NewName/g", "/root/src/file.rs"]
   • macOS： sed ["-i", "", "s/OldName/NewName/g", "/root/src/file.rs"]

ディレクトリツリーを作成する

create_directory /root/src/handlers
write_file /root/src/handlers/mod.rs "..."
write_file /root/src/handlers/auth.rs "..."

---

エラー処理

エラー	意味	修正方法
PatchFailed	コンテキスト行またはハンクヘッダーが現在のファイルと一致しません	grep -n / cat -n で再読み込みし、ヘッダーの行番号とコンテキストの両方を修正して、パッチを再生成します。短いファイルで2回失敗した場合は、write_file を使います。
OutsideRoot	パスが設定されたルートの外に出ています	サーバーの起動時に指定したルート配下のパスのみを使います
NotFound	ファイルが存在しません	write_file で作成するか、find でパスを確認します
ReadOnly	サーバーが読み取り専用モードです	書き込みは無効です。読み取りと shell_exec のみ使用できます
CommandNotAllowed	コマンドが許可リストにありません	次のコマンドのみ使用してください：grep sed awk find cat head tail wc sort uniq cut tr diff file stat ls du

---

やってはいけないこと

アンチパターン	理由	代わりに行うこと
cat /root/large_file.rs	ほとんど使わない数千トークンが返されます	場所の特定には grep -n、範囲の切り出しには sed -n を使います。cat -n は 50 行未満のファイルに限って使います
500 行のファイルの 3 行を変更するために write_file を使う	ファイル全体をアップロードするため、幻覚によって無関係な行が破損するリスクがあります	対象箇所を絞ったハンクで patch_apply を使います
1 回の shell_exec でシェルのパイプラインを使う（cmd1 | cmd2）	シェルインタープリターはありません — |、&&、$() は演算子ではなく、文字列として扱われます	shell_exec を個別に呼び出し、ロジック内で組み合わせます
find / -name "*.env"	パスはルートに対して検証されるため、ブロックされるか、役に立つ結果が何も返りません	find の対象は常に /root/... に限定します
おおよそのコンテキスト行や誤った行番号でパッチを送信する	PatchFailed — コンテキストと @@ -L,N @@ の両方が正確である必要があります	まず grep -n または cat -n を実行し、実際の内容と照らして差分を作成します
一括置換でファイルごとに sed を 1 回ずつ呼び出す	1 回で済む処理に N 回のツール呼び出しが必要になります	find ["/root", "-name", "*.ext", "-exec", "sed", "-i", "", "s/x/y/g", "{}", "+"] — すべてのファイルを 1 回の sed 呼び出しにまとめます
macOS で "" を付けずに sed -i "s/x/y/" file を実行する	BSD sed では明示的なサフィックス引数が必要です。省略すると、引数が誤って解釈されても警告されません	macOS: ["-i", "", "s/x/y/g", "/abs/file"]。Linux: ["-i", "s/x/y/g", "/abs/file"]
["-i", ""] の代わりに -i.bak または -i'' を使う	Chisel は空文字列を正しく渡すため、回避策は不要です	2 引数形式の ["-i", ""] を使い、別の形式を考案しないでください
BSD sed の解析エラー後、別の -i 形式で再試行する	原因は式またはパスであり、-i "" 形式ではありません	sed の式またはパスを修正し、["-i", ""] はそのまま使ってください
小さなファイルで patch_apply が 2 回失敗した後も再試行を続ける	ターンを無駄にし、コンテキストのずれが問題を悪化させます	ファイルを cat -n で確認し、write_file で正しく書き直します