はじめに

最近、物価高の影響もあり、各種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を単なる「回答ツール」ではなく、
最適なコンテキストを与えて「最高のスパーリングパートナー」として使い倒していきたいです！