bootstrap-monorepo

Polyglot モノレポのブートストラップ（moon + proto + Bun、Nx 収束型）

正式なリファレンスはこのスキル内にあります。

→ 参照：references/bootstrap-monorepo.md → 言語間の境界：references/cross-language-interop.md — 境界の判断手順と検証済みツールの状況（2026年6月の調査で確認済み）

自己進化するスキル：このスキルは使用を通じて改善されます。指示に誤りがある、パラメーターが変わった、または回避策が必要になった場合は、先送りせず、このファイルをすぐに修正してください。実際に再現できる問題がある場合にのみ更新してください。

このスキルを使うタイミング

次のような場合にこのスキルを使用してください。

• 新しいリポジトリを始めるとき（単一言語でもポリグロットでも構いません。構造は小規模にも対応します）
• moon がオーケストレーションし、proto でバージョンを固定し、Bun/TypeScript を組み込んだモノレポをセットアップするとき
• TS のコントロールプレーンの背後に、コントラクトを介してエンジン（Rust/Python/Go）を接続するとき
• 初日からリポジトリを Nx 収束型にしたいとき（後からの nx init は構造変更ではなく機械的な作業です）

スタック

ツール	役割
proto	リポジトリローカルの .prototools でツールチェーンのバージョン（bun、python、rust、node、…）を固定します
moon	プロジェクトグラフ、タスクのオーケストレーション、キャッシュ、変更の影響範囲の検出（moon ci）
Bun	すべてのスクリプト、CLI、接着用ツール、テストに使う TS ランタイム。ルートのワークスペースを管理します
uv / cargo	moon の script: タスクからネイティブに呼び出す Python / Rust エンジン
TypeScript	型安全なコントロールプレーン（7.0.2+）。下記の TypeScript の設定を参照してください

TypeScript はコントロールプレーンです。それ以外の言語は、ドリフト検出ゲートとパリティテストを備えた、言語に依存しないコントラクト（JSON Schema 2020-12 / proto）の背後にあるエンジンです。

TypeScript の設定

このスキルは、新しいリポジトリすべての標準リファレンス実装として tsconfig.base.json を足場にします。ボイラープレートの場所は [templates/tsconfig.base.json](templates/tsconfig.base.json) です。TS7 の設定形式に関する唯一の信頼できる情報源です。

新しいモノレポには、ルートに次の設定を含む tsconfig.base.json が用意されます。

• moduleResolution: bundler、target: ESNext、strict: true、noEmit、skipLibCheck
• allowImportingTsExtensions、lib: ["ESNext"]、verbatimModuleSyntax、noUncheckedIndexedAccess、noImplicitOverride、exactOptionalPropertyTypes
• ベース設定では意図的に types を省略します — TS7 ではデフォルトが [] となり、@types/*、process、JSX グローバルの解決が停止します。各パッケージは "types": ["bun"] や ["node"] などを個別に宣言します。名前だけを指定し、@types/bun や bun-types は使いません。

パッケージレベルの tsconfig.json ファイルはベース設定を継承し、独自の types 配列と、正当なパッケージ固有のオーバーライドを追加します。

リファレンス：~/.claude/typescript-latest-CLAUDE.md（リポジトリ全体に適用）。package.json では "typescript": "latest"（TS7.0.2+）を宣言します。

TS 7 への移行の詳細と、リポジトリごとの導入については、ブートストラップ済みスキルのドキュメント文字列と上流のリファレンスを参照してください。

言語選択のデフォルト（グリーンフィールドでのタイブレーカー）

言語間の連携方法を決める前に、_どの言語がコードを担うか_を選びます。これはタイブレーカーであり、必須ではありません。SOTAネイティブのエコシステムや既存リポジトリの慣例があれば、そちらを優先します。

• コントロールプレーンはデフォルトでTypeScriptです。アプリのロジック、オーケストレーション、CLI、API、設定、検証、エージェント／ワークフローの自動化、将来のエージェントがリファクタリングする必要のあるものが対象です。（TSはデフォルトで構造的型付けを採用しており、エージェントが最も把握しやすいサーフェスです。）
• エンジン言語を使うのは、そのエコシステムがSOTAネイティブである場合に限ります。ML／データ／科学計算／クオンツ、またはPython専用ライブラリにはPythonを、ホットカーネルやシステム開発にはRust／Goを使います（タイブレーカーではGoがRustに優先します）。
• エンジン言語をリポジトリ全体に漏らしてはいけません。 Python専用ライブラリを使うからといって、プロジェクトがPythonになるわけではありません。下記の段階に従って、1つの型付き境界の背後にラップし、公開インターフェースにはTSを維持します。境界で検証してください。TSの型はコンパイル時のみ有効で、Pythonの型ヒントは実行時に強制されません。

言語境界を越える（判断の段階）

言語間の連携が必要な場合は、最も低コストで結合度の低い方法から検討し、ニーズを満たす最初の段階で止めてください（詳細な指針と検証済みツールの状況：references/cross-language-interop.md）。

1. プロセス境界 — 標準入出力でCLI＋JSON／NDJSON（moonのscript:タスク）。デフォルトです。
2. スキーマ型付きRPC — 長時間稼働するサービスやストリームがある場合はprotobuf＋buf／ConnectRPC。
3. データプレーン — 2つの言語間で_テーブル_を交換する場合はApache Arrow IPC／Flight／ADBC。
4. プロセス内FFI — 呼び出し頻度が高く、1～3では遅すぎる場合はPyO3／maturin、napi-rs、Bun FFI。
5. 単一のWASMコンポーネントコア — カーネルにスレッドが不要な場合にのみWIT＋Component Modelを使用します（2026年半ば時点でWASIのスレッド機能はまだ未提供です）。

パターンBの条件の追記：8浮動小数点演算のテストでパターンBを選んだ後、「カーネルにスレッドが必要か？」を確認します。必要な場合は、WASMではなくネイティブコア（cdylib／PyO3）を使います。

TypeScript ↔ Python（最も一般的な組み合わせ）の検証済み選択肢、2026年6月時点：段階1＝Bun.spawn／child_processでuv run経由でPythonを実行し、.python-versionのバージョンを使います（bun:ffiではありません。C-ABIのみです）。段階2＝FastAPI＋@hey-api/openapi-ts（HTTP）、またはbufで生成したprotobuf-es＋protocolbuffers/pythonのスタブ（RPC）。スキーマのSSoT＝Pydantic v2 → JSON Schema 2020-12 → TSとし、CIで差分検出ゲートを設けます。完全な表はリファレンスを参照してください。

クイックコマンド

# After bootstrap:
moon ci                          # affected quality pipeline
moon run <project>:check         # one project's full gate (lint+test+drift)
moon query projects              # machine-readable project graph (agents read this)
moon query tasks                 # machine-readable task surface
proto use                        # install all .prototools pins on a fresh machine

レガシーパス

Pants＋miseを使っている2026-06より前のリポジトリ（miseは廃止済みで、mise時代のリファレンスは残っていません）は、リポジトリごとにこのスタックへ移行します（同等性を優先し、タスクを一つずつ切り替えてください）。一括移行は行わないでください。旧構成から新構成への対応表は、references/bootstrap-monorepo.mdのMigration Mapを参照してください。

リリース（ローカル優先）

ケースは2つあります（完全な手順はreferences/bootstrap-monorepo.mdのPhase 9を参照してください）。

• リリース可能な単位が1つ → 標準のsemantic-release、単一の.releaserc.yml、タグはv${version}。
• 個別にバージョン管理するプロジェクトが複数ある（モノレポの標準） → @rimac-technology/semantic-release-monorepoを使って、プロジェクトごとに名前空間付きタグ（<project>/v${version}）を付けます（標準のsemantic-releaseはcommitPathsを無視します。上流の#1279／#1212を参照）。RELEASE_PROFILEをキーにした.releaserc.cjsディスパッチャーで、各ストリームのcommitPathsからprocessCommitsを導出し、さらにリポジトリ全体を対象とするアンブレラ設定を標準のsemantic-releaseで用意します。フォークはnpm i -D --ignore-scriptsでインストールします。実装例：example-org/monorepo。

関連スキル

• itp:semantic-release - リリースの自動化（ローカル優先。Actionsはリリース／CodeQL／Dependabot／デプロイにのみ使用）

---

トラブルシューティング

問題	原因	解決策
moon で proto::detect::failed が発生する	ツールはインストールされているが、バージョンが固定されていない	proto pin --to global moon <version>（または .prototools に追加）
ssh 経由で moon が見つからない	非対話型の PATH にシムが含まれていない	~/.zshenv で PROTO_HOME とシムの PATH をエクスポートする（.zshrc だけでは不可）
Python テストで「No module named pytest」が発生する	uv run が開発用エクストラを削除する	リポジトリのルートから uv run --extra dev pytest <path> を実行する
PyO3 クレートの cargo test でリンクエラー（_PyBool_Type）が発生する	テストが extension-module の下で #[pyfunction] を参照している	ロジックは純粋な Rust のコア関数に置き、テストではコアを呼び出し、ラッパーは薄く保つ
タスクが誤った cwd で実行される	スクリプトがリポジトリのルートを前提としている	タスクに options: { runFromWorkspaceRoot: true } を指定する
ガードタスクが誤ってキャッシュされる	moon はデフォルトでキャッシュする	ガード／パリティ／ネットワークタスクに options: { cache: false } を指定する
コミットが「成功」したのに反映されていない	フックがファイルを自動修正し、中断した	ステージし直して再試行し、コミット後に必ず git log --oneline -1 で確認する

実行後の振り返り

このスキルの実行が完了したら、終了する前に確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラーテーブルを修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを一致するように更新します。
3. 回避策が必要でしたか？ — 別のフラグや追加手順などの工夫が必要だった場合は、次回同じ回避策が不要になるように、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合に限って更新してください。推測に基づく問題は対象外です。