【ITニュース解説】Your Project Version and APC Version Answer Different Questions

ソフトウェア開発の現場では、日々新しい機能が追加されたり、既存の機能が改善されたりする。このような変更に伴い、プロジェクトには「バージョン番号」が付けられ、管理されるのが一般的である。しかし、このバージョン番号が示すものが一つだけとは限らない。特に、エージェント技術を利用するプロジェクトのように、単にプログラムのコードだけでなく、エージェントの振る舞いを定義するルールや設定情報（これを「コンテキスト」と呼ぶ）も扱う場合、二種類の異なるバージョンを区別して管理することが重要となる。

今回取り上げる話題は、「プロジェクト自身のバージョン」と「エージェントコンテキストのフォーマットバージョン」という二つのバージョンが、それぞれ異なる質問に答えるため、混同せずに扱うべきであるという点だ。

まず、「プロジェクト自身のバージョン」について説明する。これは、一般的なソフトウェアのバージョンアップと同じで、例えば「バージョン0.1.0」から「バージョン0.2.0」へと変わるような数字である。これは、プロジェクト全体が提供する機能やアプリケーションの現在の状態を示すものであり、新しい機能が追加されたり、バグが修正されたりすると更新される。ニュース記事では、これをversionフィールドとして記述している。このversionが答える質問は「このメタデータが記述しているのは、このプロジェクトのどのバージョンか？」というものである。

次に、「エージェントコンテキストのフォーマットバージョン」について説明する。これは、エージェントの設定やルール、その他の関連情報がどのような「形式」で記述されているかを示すバージョンである。例えば、エージェントに指示を出すためのファイルや、その構造自体に新しい機能が追加されたり、記述方法が変わったりする場合に、このバージョンが更新される。ニュース記事では、これをapcフィールドとして記述している。このapcが答える質問は「このプロジェクトが期待するAPCターゲットバージョンは何か？」というものである。APCとは「Agent Project Context」の略で、プロジェクトに付属し、リポジトリで管理されるポータブルなコンテキスト層のことだ。具体的には、エージェントに関する説明を記述するAGENTS.mdファイルや、バージョン情報などを格納する.apc/ディレクトリ内のファイルなどがこれにあたる。

なぜこれら二つのバージョンを明確に区別する必要があるのか。それは、プロジェクトが変更される際に、これら二つのバージョンが必ずしも同時に、同じように更新されるわけではないからだ。

例えば、チームがアプリケーションに新機能を実装し、プロジェクトのバージョンを0.1.0から0.2.0に上げたとする。このとき、アプリケーションのコードは変わったが、エージェントのファイル形式や、それらを記述するルール、メタデータのフォーマット自体は以前と同じAPC 0.1.0のままである可能性がある。この場合、プロジェクトのversionは0.2.0に上がっても、apcは0.1.0のままで構わない。これらは異なるものを追跡しているため、値が異なっていても問題ないのだ。

逆に、チームがエージェントコンテキストの記述形式を、より新しいAPCターゲットフォーマットに更新するとしよう。これは、単なる機能追加ではなく、「コンテキストの互換性」に関わる重要な決定である。もしこのとき、apcの値をプロジェクトのリリース番号（version）に合わせて自動的に更新してしまうと、実際のコンテキストフォーマットの変更という重要な意味合いが失われてしまう。これでは、通常の機能更新が、まるで設定形式を大きく変えるような大がかりな変更に見えてしまったり、あるいは実は重要な形式の変更があったのに、ただのバージョンアップとして見過ごされてしまったりする。そうした誤解や問題を防ぐために、この二つのバージョンは別々に管理する必要があるのだ。

APCの文脈では、APX (Agent Project eXecution) という実行環境やツール層が存在する。これはAPCが提供するコンテキストを読み込み、実際にエージェントを実行する役割を担う。プロジェクトの情報が機械が読み取れる形式で記述された.apc/project.jsonというファイルがあれば、リポジトリが特定個人の開発環境や設定に依存することなく、APCとAPXがスムーズに連携できる。

.apc/project.jsonファイルは、以下のような最小限の構造を持つ。

Copy
1{
2  "name": "My Project",
3  "version": "0.1.0",
4  "apc": "0.1.0",
5  "created": "2026-05-08T00:00:00Z"
6}

この中で、nameはプロジェクトを人間が識別しやすい名前で表す。createdは、このAPCメタデータが作成された日時を記録する。そして、先に述べたversionとapcの二つのバージョン値が含まれる。

これらの二つのバージョンが必要な理由は、主に以下の点にある。開発者がプルリクエストのレビューを行う際、その変更が単なるアプリケーションの機能追加なのか、エージェントコンテキストのフォーマット変更なのか、あるいはその両方なのかを正確に判断できるようになる。また、エージェントを扱うツールが、.apc/project.jsonを読み込むことで、そのプロジェクトがどのようなAPCの形式を期待しているかを事前に把握し、適切にコンテキストを解釈できるようになる。これにより、予期せぬエラーを防ぎ、ツールの互換性を保つことができる。さらに、個人の認証情報、プロバイダーアカウント、会話履歴、キャッシュ、ローカルセッションといったプライベートな運用状態が、プロジェクトの共有メタデータファイルに混入するのを防ぐ。これらの情報は実行環境やマシンに属するものであり、プロジェクト名や意図されたフォーマットといった、リポジトリで共有・コミットすべき情報とは明確に区別されるべきである。

過去の互換性についても考慮されている。APCの初期の実装では、フォーマットバージョンを示すキーとしてapcではなくapfが使われることがあった。現在のAPCの仕様では、互換性を維持するために、互換性のあるコンシューマ（読み取る側）は歴史的なキーであるapfも受け入れるべきだとされているが、新しいプロジェクトを作成する際にはapcを使用することが推奨されている。これは、古いプロジェクトからの移行ケースに対応するためであり、新しいファイルにapfとapcの両方を記述する必要はない。

.apc/project.jsonをレビューする際には、三つの具体的な質問を自問することが重要だ。一つ目に、versionはプロジェクトが意図するリリースバージョンと一致しているか。二つ目に、apcは、コンテキストファイルが実際に使用しているフォーマットバージョンと一致しているか。そして三つ目に、もし古いapfキーが存在する場合、これは古いプロジェクトからの移行ケースであるか。これらの確認作業は短時間で完了し、プロジェクトのリリース番号が誤ってコンテキストのプロトコル宣言と混同されるのを防ぐ上で非常に有効である。

まとめると、プロジェクトのバージョンとエージェントコンテキストのフォーマットバージョンを区別して管理することは、プロジェクトの変更履歴を明確にし、他の開発者やツールとの連携を円滑にする上で不可欠なプラクティスである。これらのバージョンを適切に設定し、定期的に確認することで、将来発生しうる互換性の問題や誤解を未然に防ぎ、プロジェクトの安定した運用に貢献できるのだ。