はじめに
最近、物価高の影響もあり、各種AIサービスの有料プラン（ChatGPT PlusやClaude Proなど）を維持するのが家計に響くようになってきました。
限られた無料枠やAPIの試行回数の中で精度を出すには、
「いかに1回のプロンプトで完璧なコンテキスト（文脈）を渡せるか」 が重要です。
しかし、複数ファイルにまたがるコードを手作業でコピペし、
ツリー構造を書き、文字コードを気にするのは、
エンジニアにとって「地味で苦痛な作業」でした。
これを解決するために、Pythonツールチェーン uv を活用して、
一瞬でコンテキストを統合するCLIツール pyctxpack を作成して、PyPIに公開しました。
解決したかった「地味な面倒くささ」
AIにプロジェクトの全体像を理解させる際、以下のような「手作業」が発生していました。
-
treeコマンドの結果をコピーして貼り付ける。 - ファイル名をいちいちヘッダーとして書き、コードブロック（```）で囲む。
-
.gitignoreで除外しているはずのvenvやnode_modulesを手動で避けて選別する。 - Shift_JISなど、古い資産に混ざる文字コードを UTF-8 に変換して送る。
これらを自動化し、**「AIが最も読み解きやすい形」**に整形することを目指しました。
プロジェクトの構成
開発には、現在注目されている爆速パッケージマネージャー uv を採用しました。
pyctxpack/
├── src/
│ └── ctxpack/
│ ├── __init__.py
│ ├── cli.py # Typerによるコマンドライン定義
│ └── core.py # 統合・文字コード判定・トークン計算のコアロジック
├── tests/ # pytestによるテストコード
├── tools/
│ └── runtest/ # 動作確認用Runbookとデータ生成器
├── pyproject.toml # uvで管理された設定
└── README.md # 日英対応のドキュメント
技術的な仕組み
「技術的に複雑なことはしない」というのもこだわりの一つです。
標準的なライブラリの組み合わせで、最大の効果を出せるように設計しました。
処理のフロー
技術的なポイントとこだわり
1. uv によるモダンな開発環境と責務の分離
パッケージマネージャーには爆速の uv を採用しました。
機能ごとにモジュールを分割（cli.py, collector, reader, writer など）し、
1つのファイルに詰め込まずメンテナンス性を高めています。
2. 実用性に振ったファイル探索と処理
pathlib の活用:
rglob("*") を使用してサブディレクトリまでスマートに走査します。
OSを問わずパスが扱いやすくなり、sorted() でファイル順を固定することで
AIに渡す情報の再現性を高めています。
文字コード判定:
UTF-8 だけでなく UTF-16 や CP932(Shift_JIS) を順次トライし、バイナリファイルはスキップします。
.gitignore 対応:
pathspec を活用し、不要なファイルを除外する手間を省きます。
3. AI（LLM）への最適化
シンタックスハイライト対応:
拡張子から言語（python, typescript等）を判別し、Markdownのコードブロックに付与します。
読みやすい区切り線**:
--llm-format オプションにより、=== FILE: path === という強調されたセパレーターを選択でき、
AIがファイルの境界を一目で認識できるようにしています。
トークン数の事前把握:
実行時にトークン数を見積もる機能を搭載し、プロンプトが「重すぎないか」を事前に確認できます。
実際に使ってみた
使い方は非常にシンプルです。
uv run pyctxpack .
これだけで、「構造化されたソースコード一式」が手に入ります。
使ってみる
使ってみる方法は以下の方法があります。
いずれかご自身の環境に合わせて、使ってみてください。
uv tool install pyctxpack
pip install pyctxpack
おわりに
私自身、複雑なAIエージェントを組むのも良いですが、
まずは「AIに渡すデータを整える」という泥臭い部分を自動化するだけで、
日々の開発効率は大きく変わりつつあります。
有料プランを節約しつつ、AIの性能を最大限引き出すには、 「前処理」の自動化 が一番の近道かなっと思っています。
40代のエンジニアとして、AIを単なる「回答ツール」ではなく、
最適なコンテキストを与えて「最高のスパーリングパートナー」として使い倒していきたいです！