ai-codebase-deep-modules

深いモジュールと迅速なフィードバック

呼び出し側が有用な作業を行える契約の背後に、意味のある複雑さを隠します。 目的は、振る舞いを維持しながら認知コストと変更コストを下げることであり、 フォルダーを増やしたり、エクスポート数を規定したり、すべての関数を 抽象化したりすることではありません。エージェントの生産性は測定すべき仮説で あり、ツリー構造によって証明されるメリットではありません。

実際の変更経路を調べる

タスクを起点に、関連するエントリーポイントから、ドメインポリシー、 状態やデータの所有者、サイドエフェクト、呼び出し元、テストまでをたどります。 README のアーキテクチャ説明だけでなく、実際の依存関係を読みます。呼び出し側が 知る必要のある情報と、繰り返し発生する連携した編集を特定します。大きな ファイルでも一貫性がある場合があり、小さなラッパーでも複雑なプロトコルを 漏らすことがあります。コード行数をモジュールの深さと同一視しないでください。

維持すべき振る舞い、取り除く具体的な結合や重複、提案する最小の境界を明確に します。レビューでは、実行可能な指摘を提示します。実装を依頼された場合は、 一貫性のあるパッチとテストを作成します。必須の 9 セクション構成の アーキテクチャ計画で止めないでください。大きな設計上の判断が必要な場合に 限り、既存の計画用アセットを使用します。

所有権を中心に契約を設計する

操作、入出力の型、エラー、状態遷移、リソースの所有権、ライフタイム、権限、 並行処理やキャンセルのセマンティクスを定義します。不変条件は、それを所有する モジュールに保ちます。外部境界での検証と、すでに検証済みの内部値を分け、 あらゆる場所で防御的チェックを重複させないようにします。

内部実装の寄せ集めや万能マネージャーではなく、ドメイン操作を公開します。 公開エントリーポイントは有用な慣例になり得ますが、型、プラットフォーム アダプター、遅延読み込み、サーバーとクライアントの境界には、意図的に複数の 公開面を設けたほうが適している場合もあります。インポート時の副作用を変えたり、 サーバー専用コードをクライアントにバンドルしたりする巨大なルートバレルは 避けます。言語やフレームワークが実際に定める読み込み契約を維持します。

依存関係の方向を明示します。別のドメインが公開する契約を介した直接の非循環 依存のほうが、新しいイベントバスより単純な場合があります。依存関係や所有権の 問題が必要とする場合に依存性逆転を使い、時間的な疎結合が実際に役立つ場合に イベントを使います。イベントを使うと、配信、順序、冪等性、可観測性に関する 責務が生じます。結合がなくなるわけではありません。共有コードは本当に共有する ものだけにし、意見が分かれる型をすべて押し込む場所にしないでください。

境界を強制し、テストする

リンタールールを書く前に、境界の強制を 読みます。ルールでは、モジュールが自身の内部実装を使う場合と、外部の利用者が 境界を越える場合を区別する必要があります。サポートされているすべての表記や リゾルバーを通じて、許可されるインポートと禁止されるインポートをテストします。 ファイル名、all、grep は慣例やシグナルであり、普遍的なプライバシーや セキュリティの仕組みではありません。

意味のある失敗、空データや境界データ、状態や再起動、キャンセル、該当する場合は 並行処理のケースを含め、公開境界に対する振る舞いテストを作成します。重要な アルゴリズムの診断に役立つ場合は、対象を絞った内部テストも残します。実装内部の 呼び出し順序を模倣するモックは、契約の証明にはなりません。スタブが未実装を 返すことを確認するテストも、ドメインの振る舞いを実装するものではありません。

まず、関連するテスト、リンター、型チェックのうち最も速いものを実行し、その後、 リファクタリングで影響を受けた実際のビルドや統合経路を確認します。モックや ファイルの固定数ではなく、フィードバックコストと正しさを測ります。より詳しい チェックリストはテストとフィードバックを 読み、プロジェクトのツールとリスクに合わせて調整してください。

一貫性のある変更としてリファクタリングする

既存のモジュール例は、変更せずにインストールするための足場ではなく、参考として使用してください。インターフェース、実装、利用側、依存関係のルール、テストをまとめて更新してください。コンシューマーとの契約で必要とされていない限り、互換性エイリアス、不要なラッパー、推測に基づくエクスポート、二重実装を作成しないでください。破壊的なデータ／スキーマ移行には、引き続き明確なロールアウト／復旧計画が必要です。ソース互換性を削除しても、データを失ってよいことにはなりません。

古い scaffold_deep_module.py は削除されました。このスクリプトは、検証されていない名前をパスやソースに埋め込み、既存ファイルを作成済みとして報告しながらスキップし、有用なドメイン契約ではなくプレースホルダーの API やテストを生成していました。必要なファイルは、通常のレビュー済みパッチのワークフローで実際に作成してください。空のファイルを 4 つ作るために、代替 CLI は必要ありません。

根拠を提示する

境界部分、その境界が隠すもの、許容する依存関係、そして特定の変更負担を軽減する理由を説明してください。実際に実行したテストと、未解決の統合リスクを報告してください。1 つのインポート例が失敗しただけでアーキテクチャが強制されていると主張したり、比較タスクで測定せずにエージェントの速度が向上したと主張したりしないでください。プロジェクト固有の前提を明示し、クリーンアーキテクチャへの全面的な書き換えは避けてください。

参照先は、このインストール済みスキルからの相対パスであり、対象プロジェクトのフォルダーからの相対パスではありません。 執筆時の基準として、2026-09-13 に確認済みです：https://agentskills.io/specification。 現在の言語／リンターの情報源は、境界リファレンスに記録されています。