project-context-ingestion

プロジェクトコンテキストの把握

ソースマッピング：Kotlin_Spring_Developer_Pipeline.md（SK-01）から派生した Tier 1 の重要スキルです。

ミッション

コード、修正、テスト、アーキテクチャに関する提案を行う前に、リポジトリの正確なメンタルモデルを構築します。 このスキルを、ほかのすべての Kotlin + Spring スキルのデフォルトの最初の手順として扱います。

最初に確認する項目

• settings.gradle.kts、ルートの build.gradle.kts、モジュールのビルドファイル、gradle.properties、gradle/libs.versions.toml、および存在する場合は Gradle ラッパーのプロパティを読みます。
• application.yml、application.yaml、application.properties、およびプロファイル固有のバリアントを読みます。
• トップレベルのパッケージまたはモジュールの構成と、代表的なコントローラー、サービス、リポジトリ、設定、テストの各クラスを読みます。
• 存在する場合は、ランタイムとデリバリーに関するファイルを読みます：Dockerfile、docker-compose*.yml、Kubernetes または Helm のマニフェスト、CI ワークフロー、.env.example、デプロイスクリプト。
• 新しいアノテーション、ライブラリ、Spring API を推奨する前に、依存関係とプラグインの宣言を確認します。

プロジェクトマップの作成

• Kotlin のバージョン、Spring Boot のバージョン、Spring Framework の世代、Gradle のバージョン、JDK またはツールチェーンのバージョン、および提案を制約する主要なライブラリを記録します。
• プロジェクトが MVC と WebFlux のどちらを使うか、JPA、JDBC、jOOQ、MyBatis、R2DBC のどれを使うか、サービスが同期型かコルーチンベースか、どのテストスタックが使われているかを記録します。
• kotlin("plugin.spring")、kotlin("plugin.jpa")、kotlin("plugin.serialization")、KAPT、KSP などのコンパイラープラグインが有効かどうかを記録します。
• リポジトリがシングルモジュール、マルチモジュール、モジュラーモノリス、リポジトリごとにサービスが分かれている構成のどれかを記録します。
• パッケージの境界と、web -> service -> persistence やヘキサゴナルアダプターなど、明確なアーキテクチャ上のルールを記録します。
• 有効な設定プレフィックス、プロファイル、シークレットの読み込みパターン、条件付き Bean の使用状況を記録します。

作業手順

1. ビルドファイルと設定ファイルから始めます。ビジネスコードから始めてはいけません。
2. 互換性の制約を推測します。これらを、その後のすべての提案における厳守すべき境界として扱います。
3. モジュールとその責務を把握します。HTTP、永続化、メッセージング、セキュリティ、テストがどこにあるかを確認します。
4. フレームワークのモードを特定します：MVC と WebFlux、ブロッキングとリアクティブな永続化、サーブレットと Netty、同期型とコルーチン型のスタイル。
5. Kotlin と Spring に関する注意すべき兆候を特定します：
   • AOP アノテーションが存在するのに plugin.spring がない
   • JPA エンティティが存在するのに plugin.jpa がない
   • Spring Boot BOM と競合する可能性のある手動の依存関係バージョン指定
   • 同じリクエストフロー内でブロッキングスタックとリアクティブスタックが混在している
   • 設定の重複またはプロファイルごとの断片化
6. 現在のタスクに関係する内容だけを要約します。ファイル一覧をすべて列挙してはいけません。
7. リポジトリが不完全な場合は、証拠が不足していることを明示し、前提を限定したうえで作業を続けます。

提出する内容

次のセクションを含む、簡潔なプロジェクト概要を返します：

• Stack：フレームワークのモード、永続化のモード、テストスタック、ビルドスタック。
• Compatibility constraints：正確なバージョン、または明示的に不明である旨。
• Architecture map：モジュールまたはパッケージと責務の境界。
• Operational config：プロファイル、プロパティのバインディング方式、ランタイムとシークレットの規約。
• Risk markers：一般的な提案が当てはまらない可能性のある、プロジェクト固有の注意点。
• Next commands or files：次に実行または確認する価値が最も高い項目。

判断ルール

• 記憶にある慣習よりも、リポジトリから得られる事実を優先します。
• 複数のモジュールでバージョンやスタックのスタイルが一致しない場合は、それを明示的に指摘し、無理に統一してはいけません。
• ビルドファイルとランタイムコードが異なるアプローチを示している場合は、単なる詳細ではなくリスクとして扱います。
• タスクの範囲が狭くても、コードを編集する前に必要最小限のビルドと設定のコンテキストを確認します。
• 後から別のスキルが呼び出された場合は、すべてを最初から読み直すのではなく、抽出した制約をそのスキルに引き継ぎます。

高度なコンテキストシグナル

• アプリケーションモジュールとライブラリモジュールを区別します。リポジトリ内の共有ライブラリでは、Spring Boot プラグイン、bootJar、またはランタイム専用の依存関係を意図的に使用しない場合があります。
• ビルドロジックが規約プラグイン、buildSrc、またはインクルードされた build-logic ビルドのどこにあるかを確認します。これらの場所で、モジュールのビルドファイルから読み取れる内容が上書きされていることがよくあります。
• javax.* と jakarta.* のどちらのインポートが使われているかを検出し、コードベースの正しい移行時期を判断します。これによって、妥当な Spring、Hibernate、バリデーションに関するアドバイスが変わります。
• OpenAPI codegen、QueryDSL、jOOQ、protobuf、MapStruct などの生成ソースをプロジェクトが使用しているか検出します。生成コードによって、安全に編集できる場所が変わります。
• spring.jpa.open-in-view、spring.main.lazy-initialization、spring.aot.enabled、またはネイティブイメージ関連の設定が有効か検出します。これらの設定によって、安全に提案できる内容が変わります。
• Config Server、Vault、Helm テンプレートを使った設定、環境変数の置換など、システムがプラットフォーム機能に依存しているか検出します。ローカルファイルだけでは、実行時の全体像がわからない場合があります。
• 可観測性、トレース、相関関係が主要な規約として扱われているか検出します。これはコントローラー、クライアント、インシデントに関するアドバイスに影響します。
• サービスが独自のスキーマを管理しているか、データベースを共有しているか、アウトボックスや CDC を介して連携しているかを検出します。これによって、マイグレーションやトランザクションに関する指針が変わります。

エキスパート向けヒューリスティクス

• リポジトリで JPA と R2DBC、または MVC と WebFlux が混在している場合、それがモジュールごとの意図的な境界なのか、意図しないハイブリッドなのかを判断します。この2つではアドバイスが大きく異なります。
• リポジトリでブロッキング方式の永続化の上に Kotlin コルーチンを使用している場合、永続化レイヤーがリアクティブでなければ、依然としてブロッキングアーキテクチャであることを指摘します。
• 依存関係の管理元が複数ある場合は、優先順位を付けます。実際の信頼できる情報源は、Spring Boot プラグイン、バージョンカタログ、会社の規約プラグイン、またはプラットフォーム BOM のいずれかである可能性があります。
• テストで本番環境とは異なるスタックを使用している場合は、その点を明示します。たとえば、テストで H2、本番環境で Postgres を使用している場合、多くの永続化に関する前提は成り立ちません。
• リポジトリに明確なアーキテクチャルールがない場合は、コードベースにないクリーンアーキテクチャを作り上げず、その点を制約として報告します。

ガードレール

• プロジェクトが実際に使用しているものとは異なる Spring Boot のメジャーバージョンの API やアノテーションを推奨しないでください。
• プロジェクトが BOM、バージョンカタログ、または規約プラグインからすでに依存関係やプラグインを取得していないか確認せずに、依存関係やプラグインブロックを追加しないでください。
• spring-boot-starter-webflux またはコルーチン対応の Web スタックがある場合に、MVC だと決めつけないでください。
• データベースがあるというだけで JPA を前提にしないでください。実際に使われている永続化技術を確認してください。
• 現在の構造とチームの規約を特定する前に、アーキテクチャのリファクタリングを提案しないでください。

次の項目が見つかった場合は、疑わしさを強めてください

• 明確な理由もなく、サーブレット用スターターとリアクティブ用スターターの両方がある。
• JPA または Hibernate と併用されている data class エンティティ。
• Kotlin Spring プラグインがない状態での @Transactional、@Cacheable、または @Async。
• Boot が依存関係を管理するビルドで、Jackson、Hibernate、Netty、Logback、または SLF4J のバージョンが明示されている。
• プロファイル別設定ファイルが、同じプロパティを異なる形式で再定義している。

品質基準

このスキルを適切に実行すると、その後のアドバイスがより正確で、対象が絞られ、検証しやすくなります。 不適切な実行では、リポジトリが実際に使用しているスタック、バージョン、規約を確認する前に、コードを提案し始めてしまいます。