【ITニュース解説】Scratching My Own Itch

このニュース記事では、ある開発者が自身の経験から生まれた具体的な不満を解消するために、オリジナルのコマンドラインツールを開発した経緯とその過程で得た学びについて語っている。開発のきっかけとなったのは、AIチャットボット、特にChatGPTにコードに関する質問をする際に感じるフラストレーションだった。開発者は、自分のコードをAIに説明しようとするたび、必要なファイルを一つずつコピー＆ペーストし、AIが「インポートや親コンポーネントが必要だ」と要求するたびにさらにコードを追加するという、非効率なやり取りにうんざりしていた。AIにプロジェクトの全体像を理解させるまでに、かなりの時間と手間がかかっていたのである。

この課題を解決するため、筆者は「Repository Context Packager」というツールを開発した。このツールは、プロジェクトのコードベース全体を指定するだけで、それを一つの整形されたテキストファイルにパッケージ化し、AIチャットに容易に投入できるようにする。出力されるファイルには、プロジェクトのファイル構造を分かりやすいツリー形式で表示し、すべてのコードファイルは適切な構文ハイライトが施される。さらに、オプションとしてGit情報（最新のコミットハッシュ、現在のブランチ、各ファイルの最終更新者など）を含めることも可能だ。ファイル数や、AIが処理する情報量の目安となる「トークン数」の概算も提供されるため、AIとの会話をより計画的に進められるようになる。これにより、AIに断片的な情報を繰り返し提供するのではなく、一度にプロジェクト全体のコンテキストを効率的に与えることが可能になった。

開発にあたっては、TypeScriptとNode.jsが主要な技術として選ばれた。TypeScriptは、規模の大きいプロジェクトでJavaScriptを使用する際に発生しがちな型関連の問題を回避するために採用され、Node.jsはファイルシステムの操作やGitとの連携において最適な選択肢と判断された。ツールの基本的な操作は非常にシンプルで、コマンド一つで指定したディレクトリのコードがすべて整形されたテキストファイルに出力される。特定のファイルだけを対象にしたり、トークン見積もりを含めたりするフィルタリング機能も備えている。

開発過程では、いくつかの技術的な課題に直面した。コマンドラインインターフェース（CLI）の設計はその一つで、ユーザーが様々な方法（現在のディレクトリ、特定のファイル、複数のディレクトリ、これらを組み合わせた形など）でパスを指定する可能性を考慮し、すべてのパス指定パターンに対応させる必要があった。この問題は、入力されたパスを常に配列として扱うというシンプルなアプローチで解決された。

ファイルシステムを実際に操作する際にも、多くの現実的な問題に直面したという。例えば、バイナリファイル（画像ファイルなど）を読み込み対象から除外すること、ファイルの読み込み中にそのファイルが削除された場合に適切にエラーを処理すること、非常に大きなログファイルの内容を一部だけ読み込む（切り捨てる）こと、そしてnode_modulesのように数多くのファイルを含むディレクトリを.gitignoreの設定に基づいて無視することなどだ。これらの複雑なファイル操作は、globというライブラリを利用することで、自身でディレクトリ走査のコードを書く手間を省きながら効率的に処理された。

Gitとの連携も、単純なコマンド実行ではうまくいかないケースが多々あった。ツールがGitリポジトリではない場所で実行された場合、コミット履歴がないリポジトリの場合、あるいはWindowsとLinux/macOSのような異なるOS環境でのパスの扱い方の違いなど、様々な特殊な状況（エッジケース）に対応する必要があった。筆者は、ツールがどのような環境下でも安定して動作するよう、これらの堅牢性（ロバストネス）を高めるための努力に時間を費やした。

このプロジェクトを通じて、筆者は多岐にわたる学びを得た。CLIツールを開発する際には、プログラムの通常の出力と、警告や進捗メッセージのような付加的な情報をそれぞれ標準出力と標準エラー出力に分けて表示することの重要性、--helpや--versionといった標準的なオプションの実装、処理の成否を示す終了コードの適切な使用、そしてエラー発生時にユーザーが問題を解決できるよう具体的な指示を含むエラーメッセージを提供することなどが、ユーザーエクスペリエンスを高める上で不可欠であると学んだ。

大規模なファイル操作については、大量のファイルを一度に処理する際に、Node.jsのイベントループをブロックしないよう、必ず非同期処理（async/await）を利用することの重要性を再認識した。また、大量のファイルをメモリに保持することによるメモリ消費の増加、ファイルパーミッションの問題、そして異なるOS間でのパス処理の互換性を考慮する必要があることなど、実用的な知見を得た。

Gitについては、単なるバージョン管理ツールとしてだけでなく、プロジェクトの歴史やメタデータを格納するデータベースとしても利用できることを発見した。Gitコマンドをプログラムから実行することで、コミット履歴から作成者や日付といった有益な情報を抽出できることに気づかされた。

筆者は開発したツールを、実際に日々の業務で活用している。例えば、Reactのコンポーネントのデバッグ時には関連するコードツリー全体をAIに投入して質問したり、コードレビューの前に自分のコードをパッケージ化して内容を確認したり、新しいプロジェクトに参加した際にコードベース全体をAIに説明させてアーキテクチャを理解するのに役立てている。特に、コードベースのトークン数を知る機能は、AIとの会話の進め方を計画する上で非常に有効だと感じている。

今後の展望としては、出力形式をHTMLやJSONなど多様化すること、AIがより関連性の高いファイルを自動で選択するスマートセレクション機能、AIチャットのAPIに直接連携してコピー＆ペーストを不要にする機能、そしてブランチ間の変更点を比較分析しハイライト表示する機能などを構想している。

この経験から、他の開発者に向けても貴重なアドバイスを送っている。まずは「ごく単純なものから始める」こと。一度にすべてを完成させようとせず、基本的な機能から順に実装していくことが成功の秘訣だという。また、開発中のツールを常に自身のプロジェクトでテストすることで、多くの予期せぬ問題（エッジケース）を発見し解決できる。エラーメッセージもツールの重要な機能の一部であり、分かりやすいエラーメッセージはユーザーが問題を自力で解決する助けとなる。ドキュメント作成も必須であり、事前にREADMEを記述することでユーザー視点での設計を考える良い機会になる。最後に、どんなに優れたコードであっても、ユーザーがその使い方を理解できなければ価値がないため、ツールの使いやすさと普及が重要であると強調している。

このプロジェクトは、筆者にとって個人的な不満を解消するだけでなく、TypeScript、Node.jsのファイル操作、CLI設計といった習得したい技術を実践的に学ぶ貴重な機会となった。自ら開発したツールが日々の業務に組み込まれ、実際に時間を節約できることに大きな満足感を感じている。開発者向けのツールを構築することは、自分と同じ思考を持つユーザーのために作ることになるため、彼らが細部まで注意を払い、フィードバックをくれることで、自身のプログラミングスキルが向上する良い機会にもなる。筆者は、もしCLIツール開発に興味があるなら、個人的な不満を解決するような小さなものから始めることを勧め、オープンソースとして公開された自身のツールも、他の開発者が作った「個人的な不満を解決するツール」にも常に興味を抱いていると語っている。この経験が、プログラミングを始めた原点である「何かをより良くしたいと感じたら、それを自分で作れる」という喜びを改めて思い出させてくれたという。