メタプロジェクト初期化とアップグレード（メタプロジェクト・イニット＆監査）

エージェント環境の初期化とアップグレード（メタプロジェクト・イニット＆監査）

任意のリポジトリをエージェントワークフロー用に準備するための自律型スキル。既存のmeta-project構造を自動的に確認し、蓄積されたデータの上書きを防ぎ、最新規格への安全なアップグレードを実行するか、構造をゼロからブートストラップします。

継続的/日和見的リフレッシュの原則に依存します。メタ知識スライスにアクセスする際、エージェントはギャップを埋め、プロジェクトの一貫したビジョンを維持する必要があります。

---

スキルを呼び出すタイミング

• ユーザーが「リポジトリをエージェント用に準備」、「メタプロジェクトを初期化」、「agents.mdを確認」、「エージェント構造を更新」、「メタ知識をリフレッシュ」とリクエストした場合。

---

実行手順

フェーズ0: 既存のメタプロジェクト環境を確認する

書き込みを実行する前に、メタプロジェクトコンポーネントの存在を確認します。

1. リポジトリルートにAGENTS.mdが存在するか確認します。
2. .agents/project_knowledge/および.agents/skills/ディレクトリが存在するか確認します。

シナリオA: 構造が既に存在する場合（監査＆セーフアップグレードモード）

リポジトリにAGENTS.mdまたは.agents/フォルダが既に存在する場合：

1. 破壊的上書きの禁止:
   • observations.mdの削除または上書きは固く禁止されます。蓄積されたすべての観察結果は保持されなければなりません。
   • 既存のAGENTS.mdからカスタムインバリアントとユーザー記述を削除することは禁止されています。
2. 標準準拠監査:
   • AGENTS.mdに「原則とアーキテクチャの方針（ノーススターズ）」セクションが存在するか確認します。存在しない場合、サービスの目的とインバリアントを変更せずに追加します。
   • AGENTS.mdに「アクセス＋日和見的リフレッシュ」リンクを含むディレクティブプロトコルが存在するか確認します。古くなっている場合、セクションを更新します。
   • boundaries.mdでグロブパターンの使用、データディレクトリの保護（data/**、*.db）、フォーマット/レンダリングモジュールのYellowゾーンへの割り当て、デフォルト拒否（Blackゾーン）インバリアントの存在を確認します。
   • observations.mdテーブルにCategory列が存在するか確認します。レガシーな4列形式を使用している場合、データ行を削除せずにテーブルヘッダーを更新します。
   • .agents/skills/内のSKILL.mdファイル（record-observation、sync-architecture、ground-meta-project）の鮮度を確認します。
3. 安全な強化:
   • 不足しているスライスを作成します（例：weak_spots.mdがない場合）。
   • AGENTS.mdのスキルレジストリに、リポジトリ用の新しい専門スタックスキルを追加します。
4. アップグレードレポート:
   • ユーザーに通知：「既存のメタプロジェクトを検出しました。蓄積されたデータを失うことなく、最新規格に監査およびアップグレードしました。」

---

シナリオB: 初期セットアップ（クリーンスキャフォールドモード）

構造が存在しない場合、標準の2パスアルゴリズムを実行します：

パス1: 簡易スキャンとスケルトン生成（高速＆高レベル）

1. リポジトリルートの簡易検査: ルートディレクトリをリストし、以下を特定します：

   • マニフェスト: package.json、pyproject.toml、go.mod、Cargo.toml、requirements.txt、pom.xml、docker-compose.yml。
   • コアディレクトリ: src/、app/、tests/、migrations/、scripts/、data/。
   • ゼロ未マップディレクトリルール: リポジトリルートのすべてのトップレベルソースディレクトリを列挙します。.gitignoreパス、VCSメタデータ、標準ビルド/パッケージ/テストキャッシュ（.git、node_modules、.venv、venv、dist、build、coverage、__pycache__、.pytest_cache、.idea、.vscode）を厳密に除外します。残りのトップレベルソースディレクトリはすべて、boundaries.mdでGreen、Yellow、またはRedゾーンに明示的に割り当てられなければなりません（デフォルトでは、未マップのディレクトリはデフォルト拒否/Redゾーンに該当します）。
   • README.mdからのプロジェクト名、目的、コアコンセプト（存在する場合）。
   • .env.exampleからの必須キーと依存関係（存在する場合）。

2. 技術スタックとコア原則の特定:

   • 簡潔なスタック文字列を策定します（例：Python 3.12、FastAPI、uv、pytest、Docker）。
   • 2～3のベースライン方針を強調します（例：アーキテクチャのシンプルさ、厳格な型付け、データの不変性、オフラインファースト）。

3. ディレクトリ構造の作成: ディレクトリを作成します：

   • .agents/project_knowledge/
   • .agents/project_knowledge/archive/
   • .agents/skills/record-observation/
   • .agents/skills/sync-architecture/
   • .agents/skills/ground-meta-project/
   • scripts/

4. バンドルされたメタプロジェクトスキルとランタイムスクリプトの展開: 以下の埋め込みテンプレートからSKILL.mdファイルを書き込みます：

   • .agents/skills/record-observation/SKILL.md
   • .agents/skills/sync-architecture/SKILL.md
   • .agents/skills/ground-meta-project/SKILL.md 依存関係のない境界とコンパクション自動化スクリプトをリポジトリのscripts/に展開します：
   • scripts/check_boundaries.py（境界ゲートCLI）
   • scripts/compact_memory.py（コンテキストローテシールド＆メモリコンパクター）

5. 初期ナレッジスライスドラフトの作成: .agents/project_knowledge/にファイルを書き込みます：

   • observations.md（最初の初期化行を含む5列テーブル。クロスプラットフォームのコマンド例を使用：python -m pytest）。
   • boundaries.md（基本グロブパターンを含むゾーンテンプレート：フォーマットはYellowゾーン、データはRedゾーン）。
   • weak_spots.md（ベースラインリスクレジストリ構造）。
   • architecture.md（ベースラインアーキテクチャスキャフォールド）。
   • tasks.md（アクティブな目的、チームチェックリスト、委任レジストリ）。

パス2: リポジトリ深掘り、原則、およびシェルスキル

1. 必須コア検査チェックリスト: 主要モジュールのソースコードを読まずに、weak_spots.mdとarchitecture.mdにボイラープレートテンプレートを入力することは禁止！ エージェントは以下の重要な領域に対してread_file呼び出しを実行する必要があります：

   • ストレージ＆データベース: 主要なデータアクセスモジュール（storage.py、リポジトリ、モデル）を読み込みます。モノリシックサイズ（LOC数）、スキーマ結合、移行セットアップを評価します。
   • 外部API＆サービス クライアント: 統合モジュール（AIモデルSDK、外部クライアント）を読み込みます。リトライ、タイムアウト、フォールバック、グローバルシングルトンを確認します。
   • コンテナ化＆ランタイム: Dockerfile、docker-compose.yml、CIワークフロー（.github/workflows/）を読み込みます。システムバイナリ依存関係（FFmpeg、ユーティリティ）、ユーザー権限（UID）、データボリュームマウントを確認します。
   • ユーザーインターフェース＆入力: キーボード/ルーターモジュールを読み込みます。プラットフォームの制約（例：Telegram callback_dataの64バイト制限、FSM状態、破壊的アクションに対する確認）を確認します。

2. インタラクティブキャリブレーションインタビュー（コード化された2質問プロトコル）: 自動スキャンはコード内に存在するものを特定しますが、文書化されていない履歴コンテキスト、ビジネスインバリアント、またはプロダクションの機密事項を検出することはできません。エージェントは、ask_questionツールまたは直接のインタラクティブプロンプトを介して、厳密に2つの焦点を絞った質問からなる短く構造化されたインタラクティブインタビューを実施します：

   • 質問1（ノーススターズ＆コアインバリアント）: 「どのような主要なアーキテクチャ上のインバリアント、ビジネスルール、プロダクションの制約（ノーススターズ）が、いかなる修正においても決して破ってはならないものですか？」
   • 質問2（Redゾーン＆機密パス）: 「どの特定のディレクトリまたはモジュール（課金、DB、暗号化、キー、レガシー）が重要であり、Redゾーンに厳密にロックされるべきですか？」

   回答の処理:

   • 質問1へのユーザー回答は、直ちにAGENTS.mdのセクション1（「原則とアーキテクチャの方針（ノーススターズ）」）に統合されます。
   • 質問2へのユーザー回答は、シングルパスフラッシュの前にboundaries.mdのRedゾーンにマッピングされます。
   • ユーザーがスキップするか空の回答を提供した場合、コア検査チェックリストから推定された方針にグレースフルにフォールバックします。

3. プロジェクトのコンセプトと原則のキャリブレーション: チェックリストの調査結果とインタビュー回答を統合して、2～3の簡潔なアーキテクチャ方針（ノーススターズ）を作成し、矛盾するエージェントのアクションを防止します。

4. エージェントシェルレジストリからのスタックスキルのマッチング: リポジトリスタックをエージェント環境で利用可能な専門スキル（~/.gemini/config/skills/および組み込み）にマッピングします：

   • Python / uv / ruff → python-pro
   • FastAPI → fastapi-pro
   • TypeScript / JavaScript → typescript-expert
   • Next.js → nextjs-best-practices
   • Docker / Dockerfile / Compose → docker-expert
   • PostgreSQL / SQL / マイグレーション → postgresql-optimization、sql-pro
   • Kubernetes / Helm → kubernetes-architect
   • Telegram bot / aiogram → telegram-bot-builder
   • CI/CD パイプライン → github-actions-creator
   • クリーンコード＆レビュー → clean-code、code-reviewer

5. 境界のキャリブレーション（boundaries.md）: 実際のプロジェクトディレクトリに対して、.agents/project_knowledge/boundaries.mdのグロブパターンを調整します：

   • デフォルト拒否 / 100%パスカバレッジ（ゼロ未マップディレクトリ）: 無視されていないすべてのトップレベルソースディレクトリがゾーンに明示的に割り当てられることを保証します。デフォルト拒否（Blackゾーン）ルールを追加します。マップされていないパスはデフォルトで厳密にRedゾーンとなります。
   • テストゾーンの区別:
     • 新しい機能のための新しいテストの作成 — Greenゾーン。
     • 既存の回帰テストスイート（tests/**、*_test.*、*.spec.*） — アサーション（assert/expect）の弱体化を禁止するインバリアントを持つ厳格なYellowゾーン。
     • アーキテクチャの整合性、APIコントラクト、データスキーマのテスト（*integrity*、*contract*、*schema*、E2E） — 厳格なRedゾーン。
   • フォーマット/エスケープモジュールとテンプレートエンジン — 厳格なYellowゾーン。
   • データベースファイルとディレクトリ（data/**、*.db、*.sqlite*） — 厳格なRedゾーン。
   • プレースホルダーパスを実際のマイグレーションパス（alembic/versions/**、prisma/migrations/**など）に置き換えます。
   • ルート/コントローラーパスを実際のサブシステムの場所に置き換えます。

6. リスクとウィークスポット分析（weak_spots.md）: コア検査中に特定された具体的な技術負債（モノリス、シングルトン）、外部ランタイム依存関係（Redis、Postgres、メッセージブローカー、FFmpegなどのシステムユーティリティ）、プラットフォーム制約、および.env.exampleからの必須変数を記録します。

7. アーキテクチャスライス（architecture.md）への入力: 検査されたコアモジュールに基づいて、高レベルのスタック、サブシステム、バックグラウンドタスク/スケジューラ、データフローを記述します。

   • 条件付きエンドツーエンドデータフロー: マルチティア、クライアントサーバー、API、またはUIコンポーネントが検出された場合、「エンドツーエンドデータフロー（プリフライトフロートレーシング）」スキーマを生成します（[発信元: UI/CLI/イベント] ➔ [トランスポート: APIルート/メッセージ] ➔ [ドメイン/ストレージ: 永続化] ➔ [アセンブリ/パッケージャ] ➔ [消費者: クライアント/デーモン]をマッピング）。外部通信や永続化層を持たない純粋な単一層CLIまたはstdlibライブラリの場合は、コンテキストの肥大化を防ぐためにこのセクションを省略します。

8. インメモリ合成フラッシュプロトコル: エージェントは中間ドラフトをディスクに書き込みません。すべてのインバリアントはパス1および2の間、ワーキングメモリで合成され、その後、ファイルは厳密なボトムアップ順序で書き込まれます：

   • ステップA: プリインストールされたスキル（.agents/skills/record-observation/、sync-architecture/、およびground-meta-project/）と自動化スクリプト（scripts/check_boundaries.py、scripts/compact_memory.py（共有リポジトリセットアップの場合））。
   • ステップB: ナレッジスライス（observations.md -> boundaries.md -> weak_spots.md -> architecture.md）。
   • ステップC: ルートパスポート（AGENTS.md） — 厳密に最後。スライスとスタックスキルへの参照の集約者として。

---

最終化と検証

1. Get-ChildItem -Recurse .agents または ls -R .agents を使用して、作成/更新されたファイルを確認します。
2. ローカルインビジブルオーバーレイオプション: 外部/クライアントプロジェクトで初期化する場合、またはGitコミットなしの個人モードが要求された場合：
   • AGENTS.mdと.agents/をターゲットリポジトリの.git/info/excludeに追加します。
   • git statusを確認：メタプロジェクトファイルがUntrackedファイルに表示されてはなりません。
3. ユーザーに簡潔なサマリーを出力します：
   • 実行モード（初期セットアップ vs 監査付きアップグレード；共有 vs インビジブルオーバーレイ）。
   • 作成/更新されたファイルツリー。
   • キャプチャされたプロジェクト方針（ノーススターズ）。
   • リンクされたスタックスキルのリスト。

---

埋め込みリファレンステンプレート

テンプレート: record-observation/SKILL.md

---
name: record-observation
description: >-
  このスキルは、文書化されていないバグ、環境の癖、ランタイムのエッジケース、
  または自明でない解決策をリポジトリの`.agents/project_knowledge/observations.md`テーブルに記録するために使用します。
---

# ナレッジベースへの観察結果の記録

1. `.agents/project_knowledge/observations.md`が存在することを確認します。
2. 最後の20行をチェックして重複を確認します。
3. エントリを厳密に1行のMarkdownテーブル行として追加します：
   `| YYYY-MM-DD | [<カテゴリ>] | <パスまたはコンポーネント> | <簡単な問題サマリー/事実> | <解決策または回避策> |`
   カテゴリ: `[build]`、`[runtime]`、`[deps]`、`[db]`、`[api]`、`[test]`、`[env]`、`[ci]`、`[boundaries]`、`[orchestration]`、`[decommission]`、`[incident]`、`[init]`、または明示的なドメインタグ（例：`[theme]`）。
4. 行数が30～40を超える場合は、解決済みのレコードを`.agents/project_knowledge/archive/observations-YYYY.md`にアーカイブします。

テンプレート: sync-architecture/SKILL.md

---
name: sync-architecture
description: >-
  このスキルは、リポジトリのモジュール、依存関係、エントリポイントを分析し、
  `.agents/project_knowledge/architecture.md`を生成または更新するために使用します。
---

# プロジェクトアーキテクチャスライスの同期

1. 依存関係とビルドマニフェストを読み取ります。
2. エントリポイントとトップレベルディレクトリを特定します。
3. 3～5のサブシステム、その役割、データフローを特定します。
4. `.agents/project_knowledge/architecture.md`を更新します。
5. 変更の簡単なサマリーをユーザーに表示します。

テンプレート: ground-meta-project/SKILL.md

---
name: ground-meta-project
description: >-
  緊急グラウンディングと再キャリブレーションスキル：暴走した編集を停止し、強制的にズームアウトし、
  AGENTS.md、アクティブなロールパスポート、boundaries.md、アーキテクチャマップを再読み込みし、
  コンテキストドリフトを診断し、エイジをリセットします。
---

# メタプロジェクトのグラウンディング

[セクションは翻訳のために切り詰められています]