自分のPCで動く研究用AIエージェントのツールを作り、直していく

## 研究用ツールを利用者のPCで動かし、やらない事を決める 原則として利用者のマシン上で動作し、文書化された公開経路から導入でき、永続状態をファイルとバージョン管理に保存し、単一のプロジェクト作業領域で研究サイクル全体を支援するローカルファーストな研究環境を構築します。薄いランチャーや複数のインターフェースから利用できる場合でも、実装上の正本となるランタイムは1つに保ちます。 小規模なサービスが状態を永続化、復元、転送する一方で、プロンプトと専門スキルによって研究作業を導きます。拡大し続けるプラットフォームではなく焦点を絞った中核を重視し、提案によってランタイム、公開ツール、デプロイ対象が広がる場合は、対象外とする事項を明示します。 ## 記憶や古い計画より、今あるファイルと実際の動きを信じる 記憶や古い計画ではなく、現在のチェックアウトに実在するファイルから着手します。製品概要、文書索引、保守担当者向けアーキテクチャ、開発ガイド、対象サブシステムに必要な最小限の参照資料、実装、関連テストの順に確認します。 情報源が食い違う場合は、現在のランタイム動作と合格している契約テスト、リポジトリ全体のガイド、保守担当者向けの正本文書、補足的な貢献者向け注記の順に優先します。古いパス、機能の主張、ワークフローを残すのではなく、不正確な文書を同じ変更内で更新します。 計画された動作と実装済みの動作は別の主張として扱います。実装、構成、統合、文書、テストのすべてが裏付けるまでは、そのコンポーネントを利用可能と説明してはいけません。 ## 開発する人向けの決まりと、ツールの中で動くAIの決まりを分ける リポジトリ貢献者向けの指示と、製品内で動くエージェントを制御するプロンプトやスキルを区別します。実行時契約が特定の公開ツールや制限された実行経路を要求していても、リポジトリを編集する保守担当者に同じ制限を課すとは限りません。 プロンプト、スキル、コマンド、ツールの動作を変更する際は、必ずこの境界を保ちます。製品内の安全契約をリポジトリの貢献ルールとして読み替えず、保守担当者がより広いローカル開発ツールを利用できるという理由だけで実行時契約を弱めてはいけません。 ## 研究プロジェクトを、変更履歴つきの1つのフォルダにまとめる 各研究プロジェクトを、絶対パスで示される単一のプロジェクトルートを持つ、1つのバージョン管理リポジトリとして扱います。永続的な研究内容はすべてそのルート内に置き、プロジェクト履歴を無関係な場所へ分断せず、ブランチや隔離されたワークツリーで異なる手法の分岐を表現します。 概要、計画、状態、要約、成果物、ベースライン、実験、文献、引き継ぎ、原稿、記憶、非公開の実行時状態について、明示的な作業領域契約を維持します。実行時キャッシュやログはプロジェクト外に置けますが、研究証拠の唯一のコピーにしてはいけません。 プロジェクト配置を変更する場合は、配置モデル、永続化サービス、スナップショット、API利用側、ユーザーインターフェース、テスト、文書をまとめて更新します。他の利用側を古い構造のまま残し、1つだけを移行してはいけません。 ## 起動用のプログラムは簡単に保ち、再起動の前に今動いている設定を確かめる 研究ランタイムの正本を1つの実装層に保ち、パッケージ管理用ランチャーは、そのランタイムと事前構築済みインターフェース一式を呼び出す薄いアダプターにします。公開導入パッケージには起動に必要なファイルと構築済みクライアントを含め、利用者側の導入後ビルドに依存してサポート対象の経路を成立させてはいけません。 稼働中の環境をデバッグまたは再起動する前に、実行中のプロセス、有効な構成、既存の監督プロセスまたはランチャー、実際のランタイム実行ファイル、健全性確認先が示すホームパスを調べます。既定ディレクトリだけから、有効なホーム、構成、プロセス所有者を推測してはいけません。 パッケージマニフェスト、プロジェクトのメタデータ、公開文書、同梱物の想定を一致させます。パッケージングを完了扱いにする前に、プレビューまたはドライランで配布対象のファイル一式を確認しなければなりません。 ## AIが使う公開ツールを少なく保ち、増やす時は理由を示す 組み込みの公開ツール面は、永続的な記憶、バージョン管理された成果物、永続的なコマンド実行という少数の安定した責務に限定します。サブシステムごとに新しい公開名前空間を追加せず、バージョン管理の動作は成果物境界の内側に、シェル実行は実行境界の内側に保ちます。 プロンプトにワークフローの期待事項とファイルシステム契約を定義させ、スキルに専門的な実行動作を担わせます。状態サービスは薄く保ち、プロンプトとスキルの契約でワークフローを明確に表現できる場合は、大規模な中央ステージスケジューラーをハードコードしません。 新しい公開ツールの提案では、既存の責務に収められないことを示し、永続化と権限のモデルを定義し、すべてのクライアントを更新し、契約テストを追加しなければなりません。利便性だけでは十分ではありません。 ## 新しいつなぎ先は小さな登録表で足し、全部そろうまで完成と言わない 研究ランナー、通信チャネル、コネクターブリッジ、スキル探索、管理対象のローカルツール、任意のアダプターには、小規模なレジストリを使います。大きな分岐処理やサブシステム固有の条件分岐より、一貫した登録、取得、一覧化のインターフェースを優先します。 実行時アダプター、レジストリのメタデータ、構成の既定値、検証、サービスとコマンドラインの接続、利用者向け文書、テストがすべて揃うまでは、統合を実装済みと呼んではいけません。どれか1層でも欠けていれば、その統合は部分的です。 任意のアダプターは中核経路の外側に置き、存在しない場合を明示します。レジストリ項目は、依存関係の暗黙的な導入、外部サービスへの接続、ローカル構成の変更を行わずに、機能と互換性を示すものにします。 ## ブラウザーとターミナルの画面に、同じプロジェクトの状態と、機能を呼び出す窓口（API）を使わせる ブラウザーと端末のインターフェースには、同じサービスAPI、状態スナップショット、イベントモデルを利用させます。APIルートまたはイベントを変更する場合は、サービス、すべてのクライアント、ナビゲーションの前提、契約テストを同じ変更内で更新します。 インターフェース間で、プロジェクト単位の安定したルートと識別子を保ちます。ユーザーインターフェースの配置は異なっていても構いませんが、別個の状態解釈を作ったり、他の対応インターフェースが観測すべき遷移を隠したりしてはいけません。 主要な通信チャネルも、汎用的なチャネルおよびブリッジモデルの実装として扱います。重要なコネクターを、独自の永続化、エラー処理、ライフサイクル規則を持つ別ランタイムにしてはいけません。 ## 調べる段階から書く段階までを、一本道に決めつけずに分ける 探索、ベースライン作成、着想、実験、分析、執筆、最終化など、少数の正規な進行段階を定義します。重要な活動をすべて単一の直線的な段階とみなさず、意思決定は各段階を横断するものとして扱います。 受付時監査、図表準備、レビュー、反論対応は専門的な活動として存在できますが、現在のコードとプロンプト契約が実際にそう定めていない限り、既定の流れへ組み込んではいけません。名前付きの段階は、システムで有効なアンカー、状態遷移、利用者向け文書と一致させます。 段階の動作は、システムプロンプト、対象を絞ったプロンプト契約、プロンプト組み立て、段階スキルに置きます。段階の意味を、サービスの処理、インターフェースコード、その場限りの条件分岐へ分散させないでください。 ## 使う人向けの説明書と、開発する人向けの資料を分ける 利用者向けガイドと、保守担当者向けのアーキテクチャおよび開発資料を分けます。利用者向け文書では現在の動作を説明し、保守担当者向け文書では契約、拡張点、連動して変更すべき要件を説明します。 一時的な計画、作業用チェックリスト、非公開パス、内部専用の注記を利用者向け文書ツリーに置いてはいけません。リンクされる文書名を安定させ、存在しなくなったファイルへの参照を残さず、利用者に見える動作が変わった場合は保守対象のすべての翻訳を更新します。 変更が内部保守だけに影響する場合は、利用者向けの告知を作り出さず、保守担当者向けの正本資料を更新します。文書の範囲は動作の影響範囲に合わせます。 ## パスワードやPC固有の場所を共有ファイルに入れず、研究の記録を残す 作業端末固有の絶対パス、認証情報、トークン、ローカルキャッシュ、依存関係ディレクトリ、一時的なビルド生成物、テストキャッシュをコミットしてはいけません。生成済みのインターフェース一式を公開パッケージに含めるのは、パッケージング契約が明示的に要求する場合だけです。 永続的な実験記録、文献注記、ベースライン、成果物、原稿はプロジェクト境界の内側に置き、バージョン管理します。要約する前に元の証拠を保持し、再現可能な結果をインターフェース上だけの状態メッセージで置き換えてはいけません。 リリース前に、公開ファイルに秘密情報の漏えい、古い文書名、非公開の参照、生成ファイルのずれがないか確認します。テストが正常でも、機微情報や再現不能な内容の公表が許されるわけではありません。 ## 今のコードを先に調べ、小さく直す 新しい抽象化を提案する前に既存の実装を調べます。広範で複数目的のリファクタリングより、小さく一貫した変更を優先し、最初に必要最小限の関連資料を使い、コードとテストに照らして提案を検証します。 コードと文書が食い違う場合は、範囲を絞った1つの変更で両方を修正します。以前は存在したという理由で古い参照を残さず、有効なランタイム、プロセス、構成、ホームを特定するまでは、稼働中の研究サービスを再起動してはいけません。 診断と変更を分けます。共有状態を変更する前に、観測された兆候、期待する動作、影響を受ける利用側、最小限の修正内容を記録します。 ## 変えたコードと一緒にテストと説明書も直し、関係ない所は触らない 変更対象のサブシステムについて、直接影響を受けるすべての層を更新します。 - プロジェクト配置または永続状態：配置モデル、永続化サービス、スナップショット、API利用側、状態テスト - プロンプトまたは段階スキル：プロンプト正本、組み立て処理、スキル定義、同期対象のインストーラー、動作テスト、利用者向けガイド - 記憶、成果物、コマンド実行：実装、公開境界、サービステスト、契約文書 - 研究ランナー：アダプター、レジストリ、構成の既定値、検証、サービスとコマンドラインの接続、ガイド、テスト - チャネルまたはコネクターブリッジ：既定値、検証、チャネルとブリッジのコード、コネクターガイド、統合テスト - 管理対象のローカルツール：レジストリ、具体的なアダプター、状態と解決の動作、保守担当者向けガイド、テスト - 共有API面：ルーター、ハンドラー、ブラウザークライアント、端末クライアント、ナビゲーション、契約テスト - パッケージング：マニフェスト、プロジェクトのメタデータ、公開概要、必要な同梱物、パッケージ内容の検証 このマトリクスを無関係なサブシステムへ広げてはいけません。目的は、リポジトリ全体を書き換えることではなく、直接の影響範囲内で連動した完全性を得ることです。 ## 終える前に、案内どおりの入れ方で動くか確かめる 変更箇所に関係する単体、統合、契約、コンパイル、インターフェース構築、パッケージングの各検査を実行します。ランチャーまたはパッケージングの動作を変更した場合は、文書化された公開経路から起動し、サービスの直接起動は診断経路としてのみ確認します。 最終差分を確認し、無関係な編集、古い生成ファイル、翻訳文書の欠落、裏付けのない機能主張、クライアント更新の不足がないか調べます。ローカルのコンポーネントテストが成功したことと、サポート対象の導入経路およびインターフェース経路が動く証明とを区別します。 実際のチェックアウトを最終的な正本として扱います。参照先のファイルや動作が存在しなくなっている場合は、誤りを残さず、参照とその利用側を修正します。