グローバルコンテキストはAPCの外に置くべきである

APCはポータブルなコンテキスト層です。APXはローカルのランタイム層です。

これらを健全に保つために、一つのルールに従ってください。クローン直後でも維持されるべきものはAPCに置きます。特定のユーザー、マシン、またはプロセスに依存するものは、APCの外に置いてください。

プロジェクトが成長すると、誘惑も生まれます。設定を一つ追加したい、あるいはローカルパスを追加したいと思うかもしれません。厳格に運用しないと、リポジトリはマシンデータのゴミ溜めになってしまいます。これではリポジトリが脆弱になってしまいます。

APCはプロジェクトが所有する意味を保持します。それはリポジトリが携える共有の契約です。

適切なAPCの内容には以下が含まれます：

  • プロジェクトのアイデンティティ
  • エージェントのロール
  • 再利用可能なスキル
  • キュレーションされたプロジェクトメモリ
  • プロジェクトレベルのMCPヒント
  • AGENTS.md 内のリポジトリ全体の指示

チームメイトや新しいマシンは、チェックアウト直後にこれらの事実を読み取れるようにすべきです。

グローバルコンテキストは異なります。それはユーザーまたはワークステーションに属するものです。

グローバルコンテキストの例：

  • APIキー
  • エディタの設定
  • ローカルのエイリアス
  • マシン固有のツールパス
  • プライベートなランタイムメモリ
  • キャッシュ
  • セッションのトランスクリプト
  • メッセージログ

APXはこの状態をローカルに保ちます。ランタイムの状態は ~/.apx/ の下に保存されます。これにより、プロジェクトの共有が可能になります。

これらの層を混在させると、3つの問題が発生します：

  1. ポータビリティが損なわれる。ローカル設定に依存するリポジトリは信頼しにくくなります。
  2. レビューが煩雑になる。プルリクエストはワークステーション固有の持ち物ではなく、プロジェクトの決定事項を示すべきです。
  3. シークレットが漏洩する。ローカルの詳細情報を保存していると、誤ったファイルをコミットしやすくなります。

設定を追加する前に、こう自問してください： 他の貢献者が、クローンした直後にこれが必要になるか？

もし「はい」なら、APCを使用してください。

  • すべてのクローンに対してレビュー担当エージェントが必要か？ → APC。
  • 個人のAPIキーか？ → APCではない。
  • 権限に関するプロジェクトの決定事項か？ → APC。
  • ローカルのブラウザパスか？ → APCではない。
  • 共有のMCPヒントか？ → APC。
  • 実行キャッシュか？ → APCではない。

このルールによって、自動化が堅牢なものになります。APCはポータブルな意味を与え、APXはローカルな状態を与えます。

境界線を明確に保ってください。そうすることで、スタックのデバッグ、共有、ツール間の移行が容易になります。

リポジトリと共に移動するコンテキストにはAPCを使用してください。個人的なものや一時的なものであれば、ローカルに保持してください。

Source: https://dev.to/agentprojectcontext/global-context-belongs-outside-apc-4fg8

Optional learning community: https://t.me/GyaanSetuAi