retro

レトロスペクティブ

ユーザーがレトロスペクティブを依頼しています。今後の実行を改善するため、コーディングエージェントの環境に対する改善を提案します。

手順

1. writing-for-agents を指定して Skill ツールを呼び出し、文体ガイドを確認します。

2. ユーザーが指定したセッションの一次資料を読みます。これには、このマシン上のセッションログ（Claude Code の場合は ~/.claude/projects/、Codex の場合は ~/.codex/sessions/）を検索することが含まれる場合があります。ユーザーがセッションを指定していない場合は、現在のセッションを対象にします。

3. 次のカテゴリで改善候補を探します。

• ナビゲーション：エージェントは適切なファイルをどれだけ簡単に見つけられましたか？ファイル間に隠れた依存関係はありますか？ナビゲーションポインターがあれば、見つけやすくなりますか？使用する状況：情報を見つけるのにセッションが長時間かかった場合。
• 自動チェック：エージェントが起こしたエラーを検出できる自動チェックはありますか？リンティング、型チェック、テスト、ファイルシステムのリンターなどです。まずリポジトリ独自のチェックコマンドを確認します（package.json の lint／check／build スクリプト、コミット済みの .luarc.json、CI ワークフローなど）。すでに存在するチェックが接続されていない、またはひそかに壊れている場合は、それ自体が改善点であり、別の仕組みを作る必要はありません。Lua の場合、チェックには fivem-lls-addon を使った LuaLS を使用します。これはネイティブと CfxLua 構文を認識し、lua-language-server --check でヘッドレス実行できます。バッククォート形式のハッシュや += を拒否する標準の Lua リンターは、チェックとして壊れているのであり、構文をやめる理由にはなりません。ガードレール（リンティング／型チェック／テストのコマンドを実行する pre-commit フックも CI ジョブもない状態）がないリポジトリは、それ自体が改善点です。リンティングされていないリポジトリは、機会を逃し続けている状態であり、何もしなくてよいということではありません。使用する状況：自動チェックで検出できたはずのミスをエージェントが起こした場合、またはリポジトリにガードレールがまったくない場合。
• コーディング標準：レビュアーエージェントに、新しいルールを適用させるべきですか？既存のルールを削除、または明確化すべきですか？まず違反を分類します。機械的な違反（固定された構文パターン、禁止された API やネイティブ、インポート形式、ファイル配置のルール）には、決定論的なチェックを必ず用意します。リポジトリ独自のリンターにルールを追加する、新しい pre-commit フックを追加する、または新しい CI ジョブを追加するなど、リポジトリの言語と既存のガードレールに照らして最も低コストな方法を選びます。ルールを書くよりも、チェックを作ることを優先します。CODING_STANDARDS.md は、本当の意味で判断を要すること（ファイル間の一貫性、「周囲のスタイルに合わせる」といったこと、ガードレールでは代替できないこと）に限って使用します。使用する状況：レビュアーエージェントがミスを見逃した場合。
• グローバル AGENTS.md：リポジトリ内またはユーザーのグローバルスコープにある AGENTS.md が特に大きい場合、そこにある指示のうち、コーディング標準や自動チェックに移すべきものはありますか？使用する状況：AGENTS.md ファイルが特に大きい場合。
• ツールの効率：コストの高いツール呼び出しを効率化できましたか？特にトークン効率の悪いカスタムツール（CLI、MCP）はありますか？サブエージェントに、その役割に対して大きすぎる、または小さすぎるモデルが使われていませんか？使用する状況：エージェントがコストの高いツール呼び出しを行った場合。
• 何もしない指示：エージェントの動作を変えない指示が、ステアリングファイルに含まれていませんか？使用する状況：ステアリングファイルが大きく、扱いにくい場合。
• 情報アクセス：エージェントが利用できる情報を増やす方法はありますか？FXServer のコンソール出力をエージェントが読めるファイルに書き出す、データベースやサードパーティサービスへの読み取り専用アクセスを用意する、といった方法です。使用する状況：エージェントが必要とする重要な情報を利用できなかった場合。

4. これらの候補を、重大度の高い順にユーザーに提示します。

参考

実装とレビュー

すべての作業は、実装とレビューの2段階を経ることを覚えておいてください。実装エージェントは、最もコンテキスト圧力が高い立場です。調査、コードの作成、失敗のデバッグを担当します。

レビューエージェントは、コンテキスト圧力が最も低い立場です。差分を受け取るため、調査は必要ありません。多くの場合、コードの作成やデバッグも必要ありません。

つまり、コーディング規約を適用する役割は、実装エージェントではなくレビューエージェントが担うべきです。

ファイル

リポジトリ内のいくつかのファイルを利用できます。

• CLAUDE.md/AGENTS.md：これらのファイルは、このリポジトリで作業するすべてのエージェントのコンテキストウィンドウに読み込まれます。使用は極力控え、通常は他のファイルへのナビゲーション用ポインターだけを記載してください。
• CODING_STANDARDS.md：このファイルは実装時ではなく、レビュー時に読み込まれます。規約ファイルが1,000行を超える場合は、ドキュメントフォルダーへのナビゲーション用ポインターを追加してください。
• ドキュメント：他のファイルから参照される資料として使用してください。新しいドキュメントを書く前に、既存のドキュメントを確認してください。
• スキル：説明がエージェントのコンテキストウィンドウに読み込まれるため、ドキュメントにはスキルを使用してください。または、ユーザーが呼び出すコマンドに使用してください。writing-for-agents スキルのアドバイスに従ってください。
• .ox/config.md と ~/.config/ox/models.md：プロジェクトの情報（リソース、バージョン、フレームワーク）と、ox スキルが読み込む役割ごとのサブエージェントモデルが記載されています。これらの情報が古く、セッションに問題が起きた場合は、新しい指示を追加するのではなく、ユーザーに /setup-ox project または /setup-ox models を実行してもらってください。