ループエンジニアリングの前に、会話でハーネスを育てる — 高速フォルダーサイズビューアーの制作記録

Posted at 2026-11-08

フォルダーのサイズの構成を保存しておき、折りたたみツリーと棒グラフで高速に見られる汎用の HTML がほしい、というのが最初の出発点でした。フォルダー全体の構成は、それほど大きく変わるものではありません。サイズを調べる多くのアプリは、開くたびに走査し直すので、大きなフォルダーでは表示まで待たされますが、そこまで最新である必要は感じませんでした。要件が小さく、既存のアプリにはない使い方なので、AI に作らせるのにいい題材です。

AI との会話は PowerShell スクリプトから始まっていますが、それはその HTML に読み込ませるデータを作るためです。さらに、HTML と走査するスクリプトを分けることで、OS が違ったときの差分がスクリプトの中に局所化され、扱いやすくなります。bash スクリプトに移植して、CLI しか使えない Linux でも可視化することができるようになりました。

実際に行った AI とのやり取りをそのまま辿りながら、小さなツールを好みのとおりに作っていく様子と、そこから読み取れる実践術を紹介します。評価(テスト)の基準は、最初に設計しなくても、人間の確認の一言や AI 自身の検査から会話の中で見つかり、ハーネスとして成果物に積み上がっていきます。ループエンジニアリングの構成要素は、会話をしながらある程度そろっていきます。最初からいきなりループの構成を作っても、評価の基準はまだ分かっていません。まず会話で仕様を伝えながらハーネスを育て、高い正確性が必要になったら、そのときにループにします。

図1: 会話でハーネスを育て、高い正確性が必要になったらループにする

全体の流れ

制作は、会話で作る2つの段階と、ループの構成にする段階に分かれています。前半は、HTML に読み込ませるデータを作る PowerShell スクリプトを作る段階です。後半は、その実行結果を見やすくする HTML を、Claude と一緒に作る段階です。スクリプトは後半でも改良しています。最後に、形になったものを、ループエンジニアリングの構成にしています。

図2: 制作の段階

スクリプトとビューアーに分けた理由

素朴に作ろうとすると、HTML の中にフォルダーの走査そのものを組み込みたくなります。ページを開いたら、その場でフォルダーを読みに行って表示する形です。しかし、ブラウザーは安全のため、ページがディスクを自由に読み書きすることを許していません。Chromium 系のブラウザーには、利用者が選んだフォルダーを読める File System Access API がありますが、使えるブラウザーが限られ、読むたびに利用者がフォルダーを選ぶ操作が必要で、システム関連のフォルダーは選べません(ドキュメント¹)。ブラウザーによって使えるかどうかが違い、できることも変わりやすい機能です。

対象がファイル単体だったり、プロジェクトのように毎回同じ場所を少しずつ変えていくものだったりすれば、そのファイルや、フォルダーを圧縮したファイルを AI に渡せば済みます。しかし今回知りたいのは、手元のディスクにある大きなフォルダーの中身の大きさそのものです。丸ごと圧縮して渡すわけにはいかないので、この方法は使えません。

そこで、走査はブラウザーの外で動くスクリプトに任せて結果をファイルに書き出し、HTML はそのファイルを読み込んで見せるだけのビューアーに徹する、という分担にしました。ブラウザーの制約を受けずにディスクを読めるのはブラウザーの外のプログラムで、結果を見やすく表示するのはブラウザーが得意なことだからです。また、スクリプトはコマンドラインだけで動くので、CLI しかない Windows サーバーでも走査でき(推測²)、結果のファイルだけを手元に持ってきてブラウザーで見られます。同じ形式で出力する Linux 版も作りました(実行して確認³)。

安全性

File System Access API を使えば、どのフォルダーを読ませるかを利用者が毎回選ぶという、ブラウザーの安全の仕組みに守られます。走査をブラウザーの外のスクリプトに移すと、この守りはなくなるので、代わりに安全であることを確かめる必要があります。その代わり、走査をスクリプトに切り出すと、気をつける範囲が、そのスクリプトが読み書きするものだけにはっきり限られます。走査スクリプト(フォルダーの中を順にたどって、ファイルのサイズを集計するスクリプト)の安全性は、ソースを読めば確かめられる2つの事実に支えられています(ソースを読んで確認⁴)。1つは、走査は読み取り専用で、調べている対象のフォルダーやファイルには書き込まないことです。書き込むのは出力ファイル1つだけで、その場所は実行の最後に画面に表示されます。もう1つは、ネットワークにアクセスするコマンドを使っていないことです。PowerShell 版のソースには Invoke-WebRequest、Invoke-RestMethod、Start-BitsTransfer、System.Net.WebClient といったものが、Linux 版のソースには curl や wget が、どこにも出てきません。この2つは、後で紹介するループエンジニアリングの構成では、変更のたびに検査で自動的に確かめられます。

使った環境

後半とループの構成には、Claude の Cowork を使いました。Cowork は、作業場所にファイルを置いて、AI と人間がそのファイルを共同で仕上げていく機能です。前半は ChatGPT を使った普通の会話でしたが、作られるものの出来がよくなかったため、切りのいいところで Claude に変えました。Claude には、AI との会話の方針とコーディングルールを、あらかじめ指示として設定しています。主な内容は次のとおりです。

成果物は、同じような状況にもそのまま使える一般的な形で書く
外部のツールの挙動について、ドキュメントで確認したのか、実際に動かして確認したのか、推測なのかを書き分ける
プログラミング言語ごとのコーディングルール(ファイル名の付け方、コメントの書き方など)

制作の記録

前半 — スクリプトを作る(ChatGPT)

人: Windows でフォルダーのサイズを分析するには

作り方を指定しない聞き方。

AI(回答の要約): 標準機能、WizTree などのダウンロード型ツール、スクリプトの3つの選択肢を示す。(推測⁵)

人: WizTree は安全ですか

示されたダウンロード型ツールの WizTree について、使う前に安全性を確認する質問。

人: 指定した2つのフォルダーの深さ2まで、リストは以下のように出力してください。

3つの選択肢のうち、スクリプトを選んで依頼。折りたたみ表示を前提にした、深さ2までのツリー形式での出力を要求。深さの制限は、後の段階で外した。

AI(回答の要約): 深さ2までのフォルダーを走査し、指定の形式でリストを出力する PowerShell スクリプトを示す。(推測⁵)

人: これは、ファイルや深さ3以上は走査しませんよね

示されたスクリプトの走査範囲を、具体的に名指しして確認した一文。

AI(回答の要約): 重複するフォルダーを削除する、別のスクリプトを示す。(推測⁵)

人: 実際に削除するときにオプションを指定するように変えて

その削除スクリプトについての要求。実際の削除にはオプション指定を必須にした。

環境(注記): PowerShell は BOM を付けてコピペする必要があった。Windows PowerShell 5.1 は、BOM のない UTF-8 のファイルを、システムの文字コード(日本語版 Windows では Shift_JIS)として読みます。そのため、日本語を含むスクリプトは BOM 付きの UTF-8 で保存する必要がありました(ドキュメント⁶)。

人: PowerShell版を、YAMLで出力できますか？

結果をファイルに保存することで、古い結果でもすぐに見返せるようにした。

ProjectFolder:  #// 1,234,567
    SubFolderA:  #// 800,000
    SubFolderB:  #// 434,567

AI(回答の要約): より速い方法として、ファイルを1回だけ走査し、サイズを親フォルダーへ積み上げていく方式に触れる。(推測⁵)

人: 積み上げる高速版にしてください

その積み上げる方式へ変更。

人: 進捗状況を表示してください。

走査中の進捗(件数・バイト数・経過時間)を画面に表示するよう要求。

人: PowerShell5.1でも動くようにしてください

動作環境を、より古いバージョンまで広げる互換性の要求。

前半の会話からは、次の実践術が読み取れます。それぞれの詳しい内容は、後の「実践術」の章で取り上げます。

やり方を指定せず、目的だけを伝える: 「Windows でフォルダーのサイズを分析するには」
提案されたものも作られたものも、使う前に安全性を確かめる: 「WizTree は安全ですか」
「動きます」で終わらせず、具体的な正解を出すように確認する: 「これは、ファイルや深さ3以上は走査しませんよね」
制限をかけて作らせ、試してから外す: 「指定した2つのフォルダーの深さ2まで、…」と、その後の制限の撤廃
取り返しのつかない操作は、オプションを付けたときだけ実行させる: 「実際に削除するときにオプションを指定するように変えて」

後半 — 可視化する(Claude の Cowork)

人: 添付の PowerShell スクリプトの実行結果の YAML を読み込んで、フォルダーツリーの折り畳みができるようになる HTML を作ってください。ただし、行の内容は、フォルダー名とサイズの値と「棒グラフ」を描いてください。棒グラフは、同じ親フォルダーの中での割合にしてください。

人: 名前またはサイズでソートできるようにしてください。

人: 展開できないフォルダーにマウスを合わせた時(ホバリング)でも行を少し明るくして

人: 最初に添付した PowerShell スクリプトをポップアップ表示するボタンを追加して

人: スクリプトのデフォルト値をハードコーディングしてください。そのデフォルト値は編集するので、値は何でもいいです

人: フォルダーのサイズをファイルに出力してください。

人: 最後に出力先のパスを表示してください。

出力が「どこかに書かれたはず」ではなく、実際にどこへ書かれたかを画面に出させる要求。

人: Linux 版も作ってください。

同じ形式で出力する、Linux 用のシェルスクリプトを作った。

人: Folder_size_tree.html が Mac Safari 文字化けします

文字コードの宣言がなかった。Chromium は中身から UTF-8 と推測して正しく表示したが、Safari では文字化けした。宣言を足し、宣言があることを確かめる検査も足した。

人: Mac zsh ではサイズ0 になります

macOS の find には、ファイルのサイズを出す GNU 版の -printf がない。そのエラーが捨てられていたので、サイズ 0 の結果が書き出されていた。macOS ではサイズを stat で読み、どの方法でも読めなければエラーで止まるようにした。

AI に作らせることの利点

AI に作らせるツールには、ダウンロードして使う既存のツールと比べて、2つの利点があります。既存のツールで発生する設定項目を探し回る手間がなくなることと、既存のツールがサポートしていないカスタマイズまでできることです。

設定項目を探さずに、好みに合わせる

名前順を、大文字・小文字を区別するものと、区別しないものの2種類にする
棒グラフを表示する
読み込んだ直後は、サイズの大きい順に並べる
走査中の進捗表示に、件数・バイト数・経過時間を出す
展開できないフォルダーにマウスを合わせたときも、行を少し明るくする
スクリプトの既定値を、自分の環境の値で埋め込む

既存のツールにないことまでできる

サーバーで走査し、結果のファイルを手元で見る
結果を残して、あとから見返す
出力の書式を、自分のコメント記法(#//)に合わせる
既存のツールが対応していない OS(Linux、macOS)でも使う

実践術

AI の使いこなし方で工夫する対象は、指示文から、渡す情報、実行環境、繰り返しの仕組みへと広がってきました(Web 記事⁷)。

手法	工夫する対象	人間がすること	この制作での例
プロンプトエンジニアリング	指示文	頼み方を工夫する	「Windows でフォルダーのサイズを分析するには」と、やり方を指定せずに聞く
コンテキストエンジニアリング	AI に渡す情報	判断に必要な情報を選んで渡す	作ったものをファイルとして AI に持たせる。ChatGPT から Claude へは、スクリプトと YAML を添付して引き継ぐ
ハーネスエンジニアリング	実行環境の仕組み	守らせる制約と、自動の検証を作る	削除はオプションを付けたときだけ行う / 出力先のパスを表示する
ループエンジニアリング	繰り返しの構造	評価の基準、終了条件、人間に戻す条件を、最初に設計する	構成としては、制作の最後に使った。会話に応用するなら、決まった観点での見直しを区切りごとに頼む

この記事で紹介する実践術は、プロンプト、コンテキスト、ハーネスにあたるものと、ループエンジニアリングの観点を会話で指示することです。

頼み方を工夫する(プロンプトエンジニアリング)

頼み方や問い返し方を工夫するものです。

やり方を指定せず、目的だけを伝える

前半: 「Windows でフォルダーのサイズを分析するには」

最初の一言は、あえて具体的な実装方法を指定しない聞き方にしています。AI は人間の指示を重く受け止めるので、「スクリプトを作って」と頼めば、ほかにもっとよい方法があっても、スクリプトの範囲で答えようとします。人間の思い込みが、そのまま AI にできることの範囲を狭めてしまうのです。目的だけを伝えれば、その制限がかかりません。今回は、標準機能、WizTree などのダウンロード型ツール、スクリプトという3つの選択肢が示され、比べたうえでスクリプトの道を選んでいます。

提案されたものも作られたものも、使う前に安全性を確かめる

前半: 「WizTree は安全ですか」

選択肢の一つとして示された WizTree について、使う前に安全性を尋ねています。ダウンロードしたツールをそのまま使うのは危険です。中身を確かめないまま、手元のディスクを読み回るプログラムを動かすことになるからです。同じことは、AI が作ったスクリプトにも当てはまります。動かす前に、何を読み書きし、どこかへ通信しないかを確かめます。このビューアーの走査スクリプトなら、走査対象に書き込まないこと、ネットワークを使わないこと、その他セキュリティ上の危険性がないことを確かめれば、安全と判断できます(「全体の流れ」の「安全性」)。削除のように取り返しのつかない操作があるスクリプトは、オプションを付けたときだけ実行するようにしています(「仕組みで守らせる」)。

「動きます」で終わらせず、具体的な正解を出すように確認する

前半: 「これは、ファイルや深さ3以上は走査しませんよね」

スクリプトが示された直後に、この一文を差し込んでいます。「ちゃんと動きますか」という抽象的な確認ではなく、「ファイルは数えていないか」「深さ2より深くは見ていないか」という仕様についての、具体的に反証可能な質問です。相手は「大丈夫です」だけでは答えられず、実際の走査範囲を名指しして答えるしかなくなります。

「できました」ではなく、証拠を出させる

補足: Claude Code の公式ドキュメントが勧める頼み方

AI が「すべてのテストが通りました」と言っても、それだけではほとんど何も分かりません。実行したコマンドとその出力、または画面のスクリーンショットを、証拠として出させます(ドキュメント⁸)。出力を読むほうが、人間が検査をやり直すより速く、自分が見ていなかった作業については、それが唯一の証拠になります。会話の中の検査は、行うかどうかを AI が決める非決定的なものなので、証拠で確かめることが特に効きます。実践術「出力先は、報告ではなく画面に出させる」は、この考え方を、作るプログラムの仕様に組み込んだものです。

必要な情報を渡す(コンテキストエンジニアリング)

この制作では、コンテキストのために人間が特別な工夫をする必要はありませんでした。作ったものをファイルとして AI に持たせる形が、それを肩代わりしています。

作ったものは、ファイルとして AI に持たせる

後半: 「添付の PowerShell スクリプトの実行結果の YAML を読み込んで、…」

前半(ChatGPT)も後半(Cowork)も、AI がスクリプトをファイルとして作り、会話で頼みながら直していく形でした。判断に必要な情報は、会話の記憶ではなく、そのファイルが持っています。前半から後半へは、使う AI が変わるので、スクリプトとその実行結果の YAML を添付して引き継いでいます。後半の Cowork では、作業場所のファイルを AI が書き換え、頼みごとのたびに読み直します。AI が一度に扱える会話の量(コンテキストウィンドウ)には上限があり、会話が長くなると古いやり取りは要約され、細かい内容は落ちていきます。ファイルは会話の長さに関係なく、細部まで残っています。実際に、会話の記憶が途中で尽きて要約されたあとも、ファイルをもとに作業を続けられました(動作で確認⁹)。会話の方針やコーディングルールも、あらかじめ指示として設定してあるので、毎回伝える必要はありません。

仕組みで守らせる(ハーネスエンジニアリング)

指示文で「気をつけて」とお願いするのではなく、守らせる仕組みとして、スクリプトの仕様や、残しておく検査に組み込ませたものです。

制限をかけて作らせ、試してから外す

前半: 「指定した2つのフォルダーの深さ2まで、…」

深さ2という制限は、処理が遅くなることへの懸念と、開発中はすぐに結果を見て試したいという、速いフィードバックへの要望から付けたものでした。

実際の一連の流れ: ① 深さ2までという制限付きで作らせる → ② 境界を言葉で確認させる → ③ 制限を外して試す。実際に制限を外して試したところ、それほど遅くはならなかったため、制限を撤廃しています。最初から無制限で作らせていたら、開発中の速いフィードバックは得られませんでしたし、制限をかけたままにしておく理由があるかどうかも、試さずには確かめられませんでした。

取り返しのつかない操作は、オプションを付けたときだけ実行させる

前半: 「実際に削除するときにオプションを指定するように変えて」

重複するフォルダーを削除する別のスクリプトについて、実際の削除はオプションを指定したときだけ行うように変えています。オプションを付けずに実行しても削除は起きないので、うっかり実行しても、取り返しのつかない結果にはなりません。

出力先は、報告ではなく画面に出させる

後半: 「最後に出力先のパスを表示してください。」

「ファイルに出力しました」という報告を信じるのではなく、プログラム自身に書き込んだ先のフルパスを表示させています。確かめる手順を、作っているプログラムの仕様そのものに組み込んだ例で、実行のたびに確認の材料が残ります。

コメントに書いたスクリプトの仕様として守らせる

後半: 記録には載せていないやり取りから

守るべきことは、AI が自動でスクリプトのコメントに書いていきます。たとえば、出力先の既定値を「走査対象のフォルダー」から「スクリプトがあるフォルダー」に直したときには、PowerShell 版のコメントに「(-Root で指定した走査対象のフォルダーではない)」と書かれました。Linux 版のヘルプには「隠しファイルも数える」と書かれています。これにより、守るべきことがスクリプトの仕様として記録され、次に AI がスクリプトを直すときにも読まれます。

ループの観点を会話に応用する(ループエンジニアリング)

ループエンジニアリングの構成にはせずに、その観点だけを会話に取り入れたものです。

区切りごとに、決まった観点で見直させる

補足: このビューアーの制作の会話では使っていない頼み方

決まった評価の基準で繰り返し見直す、というループエンジニアリングの観点を、会話に持ち込んだ頼み方です。成果物がひととおり形になるたびに、見直しの観点を並べた同じ文面で、見直しを頼みます。見直しの観点は汎用のもので、作業に固有の基準を最初に設計する必要はありません。見直しを始めるのも、提案を採用して終えるのも人間です。この頼み方には、要点が3つあります。1つ目は、観点を毎回同じ文面で渡すことです。その場の思いつきで見直すより、漏れが減ります。2つ目は、「こちらから指示したことに理由がない場合は指示を疑って」と書くことです。AI は人間の指示を重く受け止めるので、疑ってよいと明示しないと、人間の指示の誤りはそのまま残ります。3つ目は、「実際の編集は合意を得てから」と書くことです。AI は直す前に提案を一覧にして返すので、人間はそれを評価し、採用するものを選べます。一方で、ループエンジニアリングと比べると欠点もあります。会話では、見直しを頼むのも、頼むたびに同じ文面を渡すのも、人間の手作業です。ループエンジニアリングの構成なら、検査は反復のたびに自動で回ります。この頼み方は、ループの手動化に一部戻っている、とも言えます。

ループエンジニアリングは、設計が手動になる

ループエンジニアリングは、1ステップごとの作業から人間を外します。その代わりに、評価の基準、終了条件、人間に戻す条件を、最初に人間が設計しなければなりません。この最初の設計は、手動の作業です。

AI に作業させるときの実践術として、「何も知らない別の確認役を立てる」「直す往復に回数の上限を決める」「セキュリティは警告で終わらせず裏取りまでする」がよく挙げられます。分解すると、どれもこの最初の設計で人間が決めることにあたります。

実践術	ループの中での役割	実現する層
何も知らない別の確認役を立てる	評価役	コンテキスト(作業の経緯を渡さない)
直す往復に回数の上限を決める	終了条件	ループそのものの設計
セキュリティは警告で終わらせず裏取りまでする	検査の段階	ハーネス(警告ではなく、仕組みで止める)

Cowork のシステムプロンプトにも、「とくに影響の大きい作業については、作業を行った本人ではなく、その作業を見ていない別のエージェントが確認する」という一文があります(ドキュメント¹⁰)。ただしこれは AI が必要と判断したときに従う指示、つまりプロンプトの側にある一文で、最初に設計されて毎回必ず働く評価役(ハーネス)ではありません。

しかし、この制作で効いた検査は、最初に設計できたものではなく、作っている途中で見つかったものでした。

「これは、ファイルや深さ3以上は走査しませんよね」は、スクリプトを見てから出てきた確認です。
深さの制限を外す判断は、試して「それほど遅くない」と分かってから下しています。
隠しファイルの数え方や、名前の大文字・小文字の並びの違いは、Linux 版を作ってから見つかりました。

最初に評価の基準を決めるやり方では、こうした検査は入りません。

Cowork は、ハーネスを会話から育てる

Cowork では、ハーネスの作り方そのものが違います。

まず、汎用の検査は、指示しなくても AI が行います。この制作では、次の検査を一度も指示していません(動作で確認⁹)。

記事を送る前に、毎回、表示を確かめる: タグの対応を確認し、PC とスマートフォンの幅で表示を撮って確かめていた。
作ったスクリプトを、実際に動かす: Linux 版をテスト用のフォルダーで動かして合計を確かめ、静的解析(shellcheck)にもかけた。
画面の動作を、ブラウザーで確かめる: ビューアーの並べ替えを実際に動かし、並び順を確かめた。

システムプロンプトには「作業の最後の段階は、作業の確認」という指示がありますが(ドキュメント¹⁰)、何をどう確認するかは、AI がその都度決めています。人間が検査の項目を考えなくても、汎用の検査はすでに回っています。

そのうえで、作業に固有の検査は、最初に設計するのではなく、次の流れで育っていきます。

必要になった時点で、検査が会話の中で言葉になる: 「これは、ファイルや深さ3以上は走査しませんよね」のように、成果物を見てから、確かめたいことが出てくる。
AI が、それを成果物に書き込む: コードの動作、コメント、ヘルプ、出力として組み込む。
ハーネスが、成果物の中に積み上がる: 成果物のファイルは残り続け、反復のたびに読み直される。組み込まれたハーネスは、事前の設計なしに積み上がっていく。成果物のファイルが、コンテキストとハーネスを兼ねている。
積み上がったハーネスを、人間が読んで評価する: ハーネスは成果物の中に読める文章として残るので、AI が組み込んだ検査で足りているかを人間が判断できる。足りなければ、会話で追加する。

実際に、出力先の既定値を「走査対象のフォルダー」から「スクリプトがあるフォルダー」に直したやり取りは、PowerShell 版のコメント「(-Root で指定した走査対象のフォルダーではない)」として残っています(動作で確認⁹)。「深さ3以上は走査しませんよね」は Claude を使う前の前半のやり取りですが、Cowork でも同じように組み込まれるはずです(推測¹¹)。

組み込まれたハーネスには2種類あります。出力先のパスの表示、削除のオプションのように、毎回必ず効く「実行されるハーネス」と、コメントやヘルプのように、次の反復で読まれたときに効く「読まれるハーネス」です。ループエンジニアリングの検査は、基本的に前者です。Cowork では後者からも始められ、言葉で書き留めておいたものを、必要になったら前者に昇格させられます。隠しファイルも数えることは、Linux 版のヘルプに書いたあと、PowerShell 版では -Force という動作になりました。

形になったら、ループにする

ループエンジニアリングは、ハーネスを最初に設計し、人間を反復の外に出します。Cowork は、ハーネスを会話から育て、人間を反復の中に残したまま、検査内容の評価と追加、そして終わりの判断を任せます。

形になって高い正確性が必要になったら、会話から育てたハーネスを、ループエンジニアリングに組み替えます。会話の中で積み上がった制約や検査を、毎回必ず実行される検査とループの定義に置き直すのです。

プログラムに対する評価の基準は、3種類に分けられます。

基準の種類	例	誰が用意するか	人間の役割
汎用の基準	スクリプトのエラーが出ない、表示が崩れない、静的解析で警告が出ない	AI が、成果物の中身に関係なく、指示なしに設計して実行する	足りているかを評価する
テストの自動生成	存在しないフォルダーを指定するとエラーで止まる(異常系)、2つのスクリプトの結果が一致する	AI が、異常系などの汎用の観点を、この成果物に当てはめて作る	足りているかを評価する
会話から育った基準	深さ3以上は走査しない、走査対象には書き込まない、隠しファイルも数える	作っている途中で、人間の確認の一言から生まれ、ハーネスとして成果物に積み上がる	確認の一言で追加する

どの種類も、人間が一から設計するものではありません。「ループエンジニアリングの構成にして」と AI に指示すれば、AI が3種類の基準を組み合わせて、ループを組み立てます。ループエンジニアリングは、最初から組むものではなく、高い正確性が必要になったときに選べる選択肢です。

ループの構成にしてみる

実際に、このビューアーを「ループエンジニアリングの構成にして」と頼みました(実行して確認¹²)。AI が組み立てたのは、次のものです。

作ったもの	中身	4つの手法での位置
検査(39件)	汎用の基準が4件、テストの自動生成が13件、会話から育った検査が22件。PowerShell 版とシェルスクリプト版を実際に動かし、ビューアーはブラウザーで操作して確かめる	ハーネス
検査用のフォルダーと、期待する出力	隠しファイル、大文字の名前、空白を含む名前、空のフォルダーを含む	ハーネス(評価の基準)
CLAUDE.md	1回の反復の手順、終了条件、ハーネスの育て方、守ること	プロンプト、コンテキスト
Stop フック	検査が通るまで、AI が応答を終えられないようにする	ハーネス(ループを強制する)

最初に検査を通した時点で、PowerShell 版のバグが1つ見つかりました。存在しないフォルダーを指定すると、エラーを出しながら最後まで進み、出力ファイルを作っていないのに「Output written to: …」と表示していました。これはループにしたから見つかったというより、テストを自動生成するときに、存在しないフォルダーのような、会話では試していなかった異常系の入力でも実際に動かしたから見つかったものです。ループにしたことで変わるのは、その後です。見つかった点は検査として残り、反復のたびに確かめられるので、同じ漏れが戻ってきません。

安全性も、ここで決定的になります。検査には「走査対象のフォルダーには書き込まない」「ネットワークにアクセスするコマンドを使っていない」が含まれていて、Stop フックがスクリプトの変更のたびにこれを実行します。危険なコマンドが紛れ込んでいないことを、人間が毎回ソースを読み直して確かめる必要はなくなり、AI が確かめ忘れることもありません。

仕様書も一緒に作る

ループの構成にしたあとの会話から

ループの構成にしたあと「ビューアーの仕様はどこに書いてありますか」と尋ねたところ、独立した仕様書はありませんでした。仕様は、検査の名前、コードのコメント、会話の中に散らばっていたのです。そこで、仕様を1項目ずつ書き、各項目に、それを確かめる検査の名前か「未検査」を書き添えた仕様書を作りました。26項目のうち、15項目が未検査か、一部だけの検査でした。漏れが見えたので、AI にその検査を足させ、今はすべての項目に検査があります。ループの構成にしたあとも、人間は会話で頼めます。AI はコード、仕様書、検査を一緒に変え、人間は仕様書の差分で確かめます。人間が仕様書やコードを直接書き換えてもかまいません。どこから変えても、最後に検査が通り、仕様書と食い違っていなければ、ループの構成は保たれます。

仕様書の役割: 人間が評価する材料になる(コードを読まなくても、何が仕様で、どこまで検査で守られているかを読める) / AI のコンテキストになる(変更の前に AI が読み、仕様を変えたら仕様書も変える。読まれるハーネスとして残る) / 検査の漏れが見える(「未検査」の項目は、変更で壊れても検査では気づけない)

検査をテストプログラムに変えて、決定的にする

補足: 制作のあとの振り返りから

会話の段階でも、AI は指示されずに検査を作って動かしていました。たとえば Linux 版を作った直後には、隠しフォルダーや空白入りの名前を含む検査用のフォルダーを作り、存在しないフォルダーを指定してエラーで止まることも確かめています(動作で確認⁹)。ただし、こうした検査を行うかどうか、どれを行うかは AI がその都度決めていて、一度動かしたら捨てられていました。その結果、存在しないフォルダーの検査は Linux 版にだけ一度行われ、PowerShell 版には当てられないまま、バグが残りました。検査をテストプログラムに変えて残し、Stop フックで毎回実行するようにすると、検査は AI の判断に頼らない、決定的なものになります。

やり方: ① 会話の中で AI が行った検査も、捨てずにテストプログラムとして残させる → ② ループの構成にするときに、テストプログラムを Stop フックから毎回実行する → ③ 検査が通るまで AI は作業を終えられず、どの検査も毎回必ず当てられる。

Claude Cowork で回すか、Claude Code で回すか

同じループの構成でも、Claude(自動的に使われる Cowork)で回すか、手元のフォルダーで Claude Code を使って回すかで、効き方が変わります。

違いの根本は、指示が決定的かどうかです。Claude Code の公式ドキュメントは、指示を2種類に分けています(ドキュメント⁸)。1つは非決定的な指示で、プロンプト、CLAUDE.md、スキルがこれにあたります。モデルが読んで、どうするかを決めます。たいていは従いますが、従う保証はなく、やらないと決めることもあります。もう1つは決定的な指示で、フックなどがこれにあたります。モデルが何を決めたかに関係なく、毎回実行されます。ドキュメントには、CLAUDE.md に「終える前に必ず型チェックする」と書いても、たいていは効くが毎回ではない、という例も挙がっています。

会話の中で AI が行う検査は、非決定的な側です。この制作では毎回検査が行われましたが、それは AI がそう判断したからで、保証はありません。どの検査を行うかも、その都度 AI が選んでいます。Stop フックで検査を回すのは決定的な側で、検査が通るまで応答を終えられません。

ただし、決定的な側でも、すべてを確かめる保証にはなりません。確かめるのは書かれた検査だけで、仕様書に書かれていないことは確かめられません。Stop フックには、作業を挟まずに8回続けて止めると Claude Code に打ち切られる上限があり、今回のフックは、ドキュメントが勧める確認を入れて、作業を続けさせるのを1回に限っています。「検査を弱めて通さない」という決まりも、CLAUDE.md に書いた非決定的な指示です。だからこそ、どの方法を使う場合でも、AI に証拠を出させます(実践術「「できました」ではなく、証拠を出させる」)。

観点	Claude(Cowork)	Claude Code
CLAUDE.md	自動では読み込まれない。新しい会話では「読んで」と頼む(推測¹³)	フォルダーで起動すると、自動で読み込まれる(ドキュメント⁸)
Stop フック	効かない。ループは、AI が CLAUDE.md の指示に従って回すだけ(プロンプト)(推測¹³)	効く。検査が通るまで応答を終えられない(ハーネス)(ドキュメント⁸)
検査の実行	必要なツールがそろっていて、39件すべてを実行できた	手元の環境次第。Windows では bash と GNU find のために Git Bash か WSL が要る(実行して確認¹⁴)
本物のフォルダー	走査できない(手元のパソコンにつながっていない)	走査できる。実際の出力をビューアーで確かめられる
ファイルの置き場所	一時的な作業場所。会話が終わると消えるので、zip で受け取る	手元のフォルダーをその場で書き換える

Claude では、検査をそろえ、仕様書を整えるところまでが向いています。ループエンジニアリングの構成として完成するのは、フックが効く Claude Code で回したときです。

[ドキュメント] File System Access API について、MDN の Window.showDirectoryPicker() の説明による。この制作では試していない。 ↩
[推測] PowerShell 5.1 が入った Windows Server(Server Core を含む)なら、そのまま動くと考えている。Server Core に PowerShell が含まれることは、Microsoft のドキュメント What is the Server Core installation option in Windows Server? で確認した(2026年11月に参照)。スクリプトの動作は、Server Core 上で実際に実行すれば確かめられる。 ↩
[実行して確認] Linux 版(folder-size-tree.sh)は、クラウドの作業環境(bash 5.2、GNU find 4.9、mawk)で、小さなテスト用フォルダーと、2万5千ファイルのフォルダーを使って動かした。合計がファイルサイズの和と一致すること、出力の各行がビューアーで読めることを確かめた。GNU 以外の find(BusyBox など)では動かない。名前にタブや改行を含むものは正しく扱えない。 ↩
[ソースを読んで確認] PowerShell 版と Linux 版のソースを読んで確認した。読者も、ソースの中から本文に挙げたコマンド名を探せば確かめられる。 ↩
[推測] AI の回答そのものは記録に残っていない。直後の人の発言の言葉づかいから、回答の内容を推測した。 ↩ ↩² ↩³ ↩⁴
[ドキュメント] Microsoft Learn の about_Character_Encodingによる。 ↩
[Web 記事] LLM から Loop まで — AI エンジニアリングはなぜこう進化したのか、リベシティライブラリの記事による。後者は、さらに外側にグラフエンジニアリング(複数の AI の役割分担と連携の設計)を挙げている。 ↩
[ドキュメント] Claude Code の公式ドキュメント Best practices for Claude Code と Automate actions with hooks による(2026年11月に参照)。決定的な指示と非決定的な指示の区別、Stop フックの上限(8回)と stop_hook_active の確認は、これらのページの記述。CLAUDE.md の自動読み込みと、Stop フックで応答の終了を止める動作は、この制作では Claude Code で動かして確かめていない。Claude Code でフォルダーを開き、検査が失敗する変更を頼めば確かめられる。 ↩ ↩² ↩³ ↩⁴
[動作で確認] この制作の会話で起きたことによる。記事の表示の確認、Linux 版の動作確認と shellcheck、ビューアーの並べ替えの動作確認は、どれも指示されずに AI が行った。出力先の既定値の指摘は PowerShell 版のコメントとして残り、隠しファイルの扱いは Linux 版のヘルプから PowerShell 版の -Force へと組み込まれた。会話の記憶が途中で尽きて要約されたあとも、成果物のファイルをもとに作業を続けられた。 ↩ ↩² ↩³ ↩⁴
[ドキュメント] システムプロンプトの記述を読んで確認した(作業の最後の段階を確認にする指示と、別のエージェントによる確認の一文)。この制作では、サブエージェントによる確認は一度も呼び出していない。 ↩ ↩²
[推測] 「深さ3以上は走査しませんよね」は Claude を使う前のやり取り。Cowork で同じ確認をして、AI がスクリプトのコメントや動作に反映するかを見れば確かめられる。 ↩
[実行して確認] クラウドの作業環境(Linux、Node 22、Chromium、shellcheck、PowerShell 7.4.6)で、39件の検査を実行した。シェルスクリプトをわざと壊したときに、Stop フック用のスクリプトが失敗した検査の名前を出して、終了コード 2 で終わることも確かめた。さらに、壊したスクリプトのフォルダーで Claude Code 2.1.319 を動かし(ヘッドレス実行、許可の確認を省略)、Stop フックによって Claude が応答を終えずに作業を続け、スクリプトを直してすべての検査を通すことも確かめた(このときの検査は35件)。PowerShell 版は PowerShell 7 で動かしたもので、Windows PowerShell 5.1 での動作は確かめていない。 ↩
[推測] この制作の会話では、CLAUDE.md を読み込まず、Stop フックも働いていなかったことからの推測。新しい会話を始めたときや、フォルダーをつないだ状態では試していない。Cowork でこのフォルダーを開いて新しい会話を始め、CLAUDE.md の内容を尋ねる、または検査が失敗する変更を頼めば確かめられる。 ↩ ↩²
[実行して確認] Git for Windows 2.51.0 の find.exe に含まれる文字列から、GNU findutils 4.10.0 で、-printf を使えることを確かめた。Windows 上で実行したのではない。Git Bash で find --version を実行しても確かめられる。 ↩

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

ループ エンジニアリングの前に、会話でハーネスを育てる — 高速フォルダー サイズ ビューアーの制作記録