MonoSpecs マルチリポジトリ管理ガイド

概要

MonoSpecs は、HagiCode のマルチリポジトリ管理アプローチです。サブリポジトリを追跡および管理します。 monospecs.yaml複数の独立したリポジトリを調整するために 1 か所を必要とするあらゆるプロジェクトで機能します。

中心となる概念

設定ファイル

monospecs.yaml は管理ソリューション全体の中核であり、以下を定義します。

• サブリポジトリのリストと場所
• 各リポジトリの Git URL
• 表示名とアイコン
• OpenSpec との統合動作

通常のリポジトリとの違い

特徴	通常のリポジトリ	モノスペック管理プロジェクト
OpenSpec の場所	ルートディレクトリの openspec/	メインリポジトリのルートディレクトリ openspec/
範囲の変更	現在のリポジトリに限定される	複数のサブリポジトリが関与する可能性がある
サブリポジトリの純度	仕様とコードの混合	仕様はメインリポジトリで確立され、サブリポジトリはよりクリーンになります
アーカイブの自動コミット	手動による仕様のコミットが必要	commit_when_archive: true 仕様をメインリポジトリに自動的にコミットします

モノスペックを使用する理由

• 統合管理: すべてのサブリポジトリを 1 つの構成ファイルで管理します
• 自動化サポート: スクリプトとツールのリポジトリ メタデータを提供します
• AI フレンドリーさ: 構造化された構成は、AI エージェントがリポジトリの関係を理解するのに役立ちます
• OpenSpec 統合: 変更管理ワークフローとのシームレスな統合
• よりクリーンなサブリポジトリ: 仕様はメイン リポジトリに保持され、サブリポジトリには実際のコードのみが含まれます

該当するシナリオ

次のようなシナリオでは、最初に MonoSpecs を使用します。

1.マルチリポジトリの共同開発 プロジェクトが複数の独立したリポジトリに分割される場合:

• フロントエンド アプリケーション、バックエンド サービス、デスクトップ アプリを個別に開発
• リポジトリ全体でバージョンと依存関係を調整する必要がある
• メインコードから分離されたドキュメントとヘルパープロジェクト

2.補助的なプロジェクト管理 MonoSpecs を使用して以下を管理します。

• ドキュメントプロジェクト
• 公式サイト
• ビルドツールとスクリプト
• 各リポジトリは独自のバージョン管理を維持します

3.クロスリポジトリ機能開発 複数のリポジトリにわたる変更が必要な機能:

• どのリポジトリの変更を追跡する必要があるか
• 仕様を正しいターゲットリポジトリに自動的にコミットします
• バージョンの更新と依存関係を調整する

クイックスタート

初期化

モノスペックの初期化を完了するには、次の手順に従います。

1. 空の git リポジトリを作成する

空のを作成する git メイン リポジトリ内のフォルダー (注: これは gitではありません repos/ - これはモノスペック規約です):

mkdir git
cd git
git init
cd ..

2.monospecs ファイルの構成

を作成します。 monospecs.yaml メイン リポジトリのルート ディレクトリにある設定ファイル:

version: "1.0"
commit_when_archive: true

repositories:
  - path: "repos/frontend"
    url: "https://github.com/your-org/frontend.git"
    displayName: "Frontend App"
    icon: "🌐"

  - path: "repos/backend"
    url: "https://github.com/your-org/backend.git"
    displayName: "Backend Service"
    icon: "⚙️"

設定項目:

構成アイテム	種類	必須	説明
version	文字列	はい	設定ファイルのバージョン
commit_when_archive	ブール値	いいえ	アーカイブ時に仕様を自動コミットするかどうか (サブリポジトリ コードをコミットしない)
repositories	配列	はい	リポジトリ構成リスト
repositories[].path	文字列	はい	リポジトリ パス (プロジェクト ルートからの相対パス)
repositories[].url	文字列	はい	Git リポジトリ URL
repositories[].displayName	文字列	いいえ	リポジトリの表示名
repositories[].icon	文字列	いいえ	リポジトリアイコン（絵文字）

サブリポジトリをメインリポジトリに追加する

すべてのサブリポジトリを repos/ ディレクトリ。サブリポジトリのコンテンツの追跡を避けるために、このディレクトリは メイン リポジトリの Git バージョン管理から除外する必要があります。

# Exclude all sub-repositories
repos/

3. 親リポジトリをHagiCodeに追加する

HagiCode デスクトップ アプリケーションを使用する場合は、アプリを開いてメイン リポジトリをプロジェクトとして追加します。ホーム画面で「プロジェクトの追加」または「+」ボタンをクリックし、メイン リポジトリ フォルダを選択すると、すべてのサブ リポジトリとそのステータス情報が表示されます。

4. サブリポジトリのクローンを作成する

を使用します。 monospecs.yaml 設定されたすべてのサブリポジトリのクローンを repos/ ディレクトリ:

これにより、構成ファイルで指定された URL に基づいてすべてのサブリポジトリのクローンが作成されます。

設定ファイルの構造

ルートレベルの構成

version: "1.0"
commit_when_archive: true

repositories:
  # ... repository configurations

リポジトリレベルの構成

各サブリポジトリには以下を含めることができます。

• OpenSpec 変更フォルダー (openspec/)
• 独立した .git/ ディレクトリ
• オプション AGENTS.md AI エージェント構成用

リポジトリ管理操作

新しいリポジトリの追加

新しいサブリポジトリを monospecs.yaml repositories 配列:

repositories:
  - path: "repos/new-service"
    url: "https://github.com/HagiCode-org/new-service.git"
    displayName: "New Service"
    icon: "🆕"

リポジトリ構成の更新

リポジトリ URL またはメタデータが変更された場合:

1. 編集 monospecs.yaml 対応するエントリを更新します
2. YAML 構文が正しいことを確認する
3. 同期が変更された場合は、ローカル リポジトリ構成を手動で更新します

AI エージェント構成のサポート

エージェント.md

の AGENTS.md このファイルには、AI エージェントのリポジトリ固有のガイダンスが含まれています。

技術スタック情報

• フレームワークとビルドツール
• コード規則と命名規則
• バージョン管理と展開構成

プロジェクト固有の動作

• 構成の拡張と特別な要件
• OpenSpec の統合パターン
• リポジトリ間の調整の必要性

AI の利点

使用する AGENTS.md AI エージェントは次のことを可能にします。

• リポジトリの関係と依存関係を理解する
• コードを生成し、複数のリポジトリにわたってリファクタリングする
• バージョン管理と構成の一貫性を維持する

OpenSpec の統合

MonoSpecs が OpenSpec でどのように動作するか

モノスペック管理プロジェクトを管理する場合でも、通常のリポジトリを管理する場合でも、HagiCode の OpenSpec ワークフローを使用できます。

通常のリポジトリ:

• ルートの OpenSpec openspec/ ディレクトリ
• 変更は現在のリポジトリにのみ影響します

モノスペック管理プロジェクト:

• OpenSpec の読み取り monospecs.yaml 構成
• サブリポジトリによって追跡される変更
• 仕様は正しいターゲットに自動的にコミットされます

アーカイブ動作

いつ commit_when_archive: true:

• 仕様はメイン リポジトリに自動的にコミットされます
• サブリポジトリのコードはコミットされません（分離されたままになります）
• 仕様管理を簡素化 - サブリポジトリに手動で仕様をコミットする必要はありません

手動サブリポジトリコミット

サブリポジトリは独立したバージョン管理を維持します。

• 実際のコード変更を独自のリポジトリにコミットする
• 仕様は個別にコミットされます (アーカイブ時にメイン リポジトリから)

ベストプラクティス

リポジトリの命名規則

• リポジトリ パスにはケバブケース (小文字とハイフン) を使用します。
• 中国語のシンプルでわかりやすい表示名を使用する
• 関連する絵文字をアイコンとして使用する

表示名のガイドライン

• 簡潔かつ説明的なものにしてください
• 同様のリポジトリ間で一貫した名前を使用する
• リポジトリの目的を表すアイコンを選択します

構成のメンテナンス

設定と実際のステータスを同期

• 定期的に確認する monospecs.yaml 実際のリポジトリ構造を反映します
• リポジトリの追加または削除時にエントリを更新または削除する
• 変更をテストして構成の妥当性を確認する

構成のバージョン管理

• git を使用して構成ファイルの変更を追跡する
• 主要な構成変更の理由を文書化する
• 簡単にロールバックできるように構成ファイルのバージョンをタグ付けする

トラブルシューティング

設定ファイルが見つかりません

もし monospecs.yaml ファイルがプロジェクトのルートに見つかりません:

1. ファイルが正しい場所に存在するかどうかを確認してください
2. 正しい作業ディレクトリにいることを確認してください
3. 設定ファイル名のタイプミスをチェックする

YAML 構文エラー

一般的な YAML 構文の問題:

• 不正なインデント (タブではなくスペースを使用してください)
• 文字列の周りの引用符が欠落しているか、余分な引用符がある
• 無効なデータ型 (文字列には引用符が必要ですが、数値には必要ありません)
• 必須フィールドが欠落しています (例: path または url)

リポジトリが検出されない

新しく追加されたリポジトリが表示されない場合:

1. チェックしてください path は正しいです monospecs.yaml
2. リポジトリが正常にクローン作成されたことを確認します
3. リポジトリが予想される場所に存在するかどうかを確認します

クローン作成の失敗

リポジトリのクローン作成が失敗した場合:

1. ネットワーク接続を確認する
2. Git リポジトリ URL が正しいことを確認する
3. 認証の問題を確認する
4. Dockerコンテナのステータスを確認する
5. 利用可能なディスク容量を確認する

---

詳細情報については、monospecs ドキュメントを参照し、構成例については、HagiCode リポジトリを確認してください。