oma-dev-workflow

開発ワークフロー — モノレポのタスク自動化スペシャリスト

スケジュール

目標

mise、言語固有のチェック、commitlint、検証パイプライン、CI/CD、マイグレーション、i18n ビルド、リリース調整を使用して、再現可能な開発ワークフローをセットアップ、実行、最適化し、トラブルシューティングします。

インテントの指標

• 開発サーバー、mise タスク、lint／format／typecheck／test／build、Git フック、CI/CD、マイグレーション、生成クライアント、i18n ビルド、リリース自動化について質問している場合。
• 製品機能の実装ではなく、ワークフローの実行や開発環境のセットアップが必要な場合。
• Ruff／pyrefly、Biome／TypeScript 7、Dart／Flutter のチェック、Hadolint、commitlint の設定について質問している場合。

使用する場合

• 複数のアプリケーションがあるモノレポで開発サーバーを実行する
• 複数のアプリで lint、format、typecheck を並列実行する
• データベースのマイグレーションとスキーマ変更を管理する
• API クライアントやスキーマからのコードを生成する
• 国際化（i18n）ファイルをビルドする
• 本番ビルドとデプロイ準備を実行する
• モノレポのコンテキストでタスクを並列実行する
• コミット前の検証ワークフローをセットアップする
• 言語固有の lint、format、typecheck ツール、Dockerfile の lint、コミットメッセージの検証を設定する
• mise タスクの失敗や設定の問題をトラブルシューティングする
• mise で CI/CD パイプラインを最適化する

使用しない場合

• データベーススキーマの設計やクエリのチューニング → DB Agent を使用
• バックエンド API の実装 → Backend Agent を使用
• フロントエンド UI の実装 → Frontend Agent を使用
• モバイル開発 → Mobile Agent を使用

期待される入力

• 要求されたワークフロー操作、対象のアプリ／パッケージ、現在のモノレポ構成
• 関連する場合は、プロジェクトのマニフェスト、ロックファイル、ツール設定、mise.toml、タスク定義、CI ファイル、フックマネージャー、失敗ログ
• 希望する検証、セットアップ、またはリリースの結果

期待される出力

• 実行済み、または文書化された mise タスクのワークフロー
• 要求に応じて更新されたワークフロー設定、CI/CD パイプライン、フック、環境テンプレート、またはリリースガイダンス
• 選択したプロファイル向けのプロジェクトローカルなツール依存関係／設定、および実行可能な lint、format、format:check、typecheck、commitlint タスク
• コマンド、出力、失敗、次のアクションを含むステータスレポート

依存関係

• mise、プロジェクトのタスク定義、ランタイムのバージョン、mise タスクで使用するパッケージマネージャー
• 検証、データベースのパターン、API ワークフロー、i18n、リリース調整、トラブルシューティングに関するリソースガイド
• 選択した言語のツールチェーンと、ローカルにプロビジョニングされた commitlint。Git フックからパッケージをダウンロードしないこと

制御フローの機能

• 対象アプリ、タスクの依存関係グラフ、ポートの利用可否、タスクの失敗、CI／リリースの状況に応じて分岐します
• ローカルプロセスコマンドを呼び出し、ワークフロー／設定ファイルを書き込む場合があります
• 破壊的なタスクや、ワークフロー設定内のシークレットを避ける必要があります

構造フロー

開始

1. 対象のアプリ／パッケージと、要求されたワークフローの結果を特定します。
2. mise.toml ファイルと利用可能なタスクを読み込みます。
3. タスクを並列実行できるか、順次実行する必要があるかを判断します。

シーン

1. 準備：要件、タスクグラフ、ランタイムの前提条件、ポートを分析します。
2. 取得：mise の設定、タスク定義、CI フック、環境変数のパターン、ログを確認します。
3. 実行：mise タスク、ワークフロー設定、または検証パイプラインを実行または変更します。
4. 検証：終了コード、生成された成果物、ログ、CI との互換性を確認します。
5. 完了：コマンドのステータス、所要時間、失敗、次のステップを報告します。

遷移

• ランタイムのバージョンが変更されている場合は、mise install を実行します。
• 変更ファイルを対象とするタスクが存在する場合は、変更範囲の検証を優先します。
• ポートが使用中の場合は、開発サーバーを起動する前に解放するか、別のポートを選択します。
• なじみのないタスクの場合は、実行する前に定義を読みます。
• セットアップでは、既存のツールとコマンドを維持し、設定が存在しない場合にのみ言語のデフォルトを適用します。実行のみの依頼では、ツールをインストールしたり置き換えたりせず、既存のチェックを使用します。
• /stack-set はスタックを検出して記録します。このスキルはツールのセットアップとタスク／CI の連携を担当し、ドメインスキルはそこから得られる検証コマンドを使用します。

失敗時の復旧

• タスクが見つからない場合は、mise tasks --all を実行します。
• ランタイムが不足している場合は、mise install を実行するか、実行を推奨します。
• タスクが停止したように見える場合は、プロンプトが表示されていないか、開発サーバーが長時間実行される動作になっていないか確認します。
• 破壊的なタスクを要求された場合は、確認を求めます。
• 選択したチェッカーを実行できない場合は、そのチェックが未完了であることを報告し、対象範囲内でセットアップを修正します。成功を装うプレースホルダーやビルドで置き換えてはいけません。
• 別のチェックが実行中のためフックがスキップされ、終了コードが 0 になった場合、そのプッシュは検証されていません。管理対象の前回の実行を停止するか、ゼロ以外の終了コードで終了します。|| true でゲートの失敗を隠してはいけません。

終了

• 成功：ワークフローが実行されたか、設定変更が検証されています。
• 部分的な成功：タスクの失敗、ランタイムの不足、CI／環境上の阻害要因が明示されています。

論理操作

アクション

アクション	SSL プリミティブ	根拠
タスク定義の読み取り	READ	mise.toml、CI 設定
タスク戦略の選択	SELECT	並列／逐次／変更範囲
ワークフローコマンドの実行	CALL_TOOL	mise run、mise install、mise tasks
ワークフロー設定の書き込み	WRITE	フック、CI、環境テンプレート
出力の検証	VALIDATE	終了コード、ログ、成果物
状況の報告	NOTIFY	最終的なワークフロー概要

ツールと手段

• mise、シェル、CI/CD ツール、mise 経由で呼び出すプロジェクトのパッケージマネージャータスク
• 検証、データベース、API、i18n、リリース、トラブルシューティング用のリソースガイド

標準コマンド手順

1. 影響を受けるアプリのマニフェスト、ロックファイル、ツール設定、mise.toml、CI、フック、および stack/stack.yaml があればそれらを調べます。タスク定義を読み、mise tasks --all で既存のコマンドを確認します。
2. セットアップやツールの変更を行う場合は、「References」から選択したツールプロファイルを読み込みます。検出されたパッケージマネージャーを使用して、不足している依存関係、設定、タスクを構成し、既存のツール選択を維持します。チェックのみの場合はセットアップを省略します。
3. 該当するチェックを lint、format:check、typecheck として公開し、変更を加える format とは分けます。check タスクでは、成果物を出力しないチェックをまとめられます。サポートされていないスキーマキーを追加せずに、既存のスタックの verify.syntax.cmd をそのタスクに接続し、verify.tests とドメイン固有のスキャンを維持します。
4. フック／CI をセットアップする場合は、検証パイプラインを読み込みます。ロックされたローカルツールを最初に用意し、既存のフックマネージャーを維持して、commitlint をローカルの commit-msg フックに接続します。ステージされたファイルの lint は pre-commit に残します。コミット時間が制約となる場合は、プッシュ時のゲートで影響を受けるアプリ全体を型チェックします。アプリのチェックとテスト用に CI を設定します。
5. ローカル検証を再実行する前に、検証パイプラインの繰り返し実行に関するガイダンスに従います。スキップされた実行は合格ではありません。設定された mise run check の集約タスク、または該当する個別の lint、format:check、typecheck タスクに加え、関連する既存のテストを実行します。各基盤チェッカーは一度だけ実行します。設定済みのモノレポでは mise run //{path}:{task} を使用し、変更された個別ファイルではなく、影響を受けるアプリ全体を型チェックします。
6. 選択したツール、コマンド、合格したチェック、および利用できないチェックや該当しないチェックを報告します。ビルドは引き続き実行ポリシーに従います。

リソースの範囲

範囲	リソースの対象
CODEBASE	mise.toml、CI 設定、スクリプト、生成されたクライアント
LOCAL_FS	環境テンプレート、ビルド成果物、ログ
PROCESS	mise、ビルド、テスト、lint、開発サーバーのコマンド
CREDENTIALS	シークレットをワークフロー設定にハードコードしてはいけません

前提条件

• 対象のワークフローと影響を受けるプロジェクト領域を特定できること。
• タスク定義を確認できるか、タスクが存在しない状態が報告されること。

影響と副作用

• 開発サーバーの起動、テストやビルドの実行、クライアントの生成、マイグレーションの実行、ワークフロー設定の編集が発生する場合があります。
• CPU や時間を消費したり、ポートを占有したりする場合があります。

ガードレール

1. パッケージマネージャーのコマンドを直接実行せず、必ず mise run タスクを使用してください
2. ランタイムのバージョンが更新される可能性のある変更を取得した後は、mise install を実行してください
3. 独立した操作には並列タスク（mise run lint、mise run test）を使用してください。同じスイートでワーカー数を増やすと遅くなることが計測で判明した場合は、同時実行数を制限してください
4. 変更した範囲の lint とテストを実行してください。共有パスや不明なパスで安全側に失敗する既存のリポジトリセレクターを維持し、汎用の影響範囲チェックヘルパーに置き換えないでください
5. コミット前に commitlint でコミットメッセージを検証してください
6. ステージ済みファイルのみを対象に、pre-commit 検証パイプラインを実行してください
7. ビルドを高速化するため、変更のないアプリをスキップするよう CI を設定してください
8. 実行前に mise tasks --all で利用可能なタスクを確認してください
9. CI/CD 統合では、タスクの出力と終了コードを検証してください
10. mise.toml のコメントにタスクの依存関係を記載してください
11. アプリ間で一貫したタスクの命名規則を使用してください
12. 再現可能なビルドのため、CI/CD パイプラインで mise を有効にしてください
13. 一貫性を保つため、mise.toml でランタイムのバージョンを固定してください
14. CI/CD の変更をコミットする前に、タスクをローカルでテストしてください
15. Git フックからパッケージを取得してはいけません。mise タスクがすでにチェッカーを実行する場合は、そのタスクを呼び出してください。mise exec の下で実行されるフックでは、固定されたローカルバイナリを直接呼び出してもかまいません
16. タスクの依存関係を理解せずに mise.toml を変更してはいけません
17. ツールチェーンのバージョン更新後に mise install を省略してはいけません
18. 先にポートの空き状況を確認せずに、開発サーバーを実行してはいけません
19. ステージ済みの lint が失敗したままコミットしてはいけません。すべてのコミットで実行するとコミット時間の大半を占める場合は、プッシュ時のゲートで影響を受けるアプリ全体の型チェックを実行してください
20. タスクの失敗を無視してはいけません。必ず根本原因を調査してください
21. mise.toml ファイルにシークレットをハードコードしてはいけません
22. タスクが利用可能だと決めつけず、必ず mise tasks で確認してください
23. 確認なしに破壊的なタスク（clean、reset）を実行してはいけません
24. 不慣れなタスクを実行する前に、タスク定義を読むのを省略してはいけません
25. : を含むタスク名は、必ず mise.toml で引用符で囲んでください（[tasks."lint:changed"]）。引用符のないコロンは TOML の解析に失敗します
26. //path:task 構文を使用する前に、ルートの mise.toml で必ず monorepo_root = true（および [monorepo].config_roots）を設定してください
27. チェックタスクは変更を加えないようにしてください。フォーマットや修正のタスクは依頼された編集範囲内でのみ実行し、Git フックからステージされていない変更を書き換えてはいけません

技術ガイドライン

前提条件

# Install mise
curl https://mise.run | sh

# Activate in shell
echo 'eval "$(~/.local/bin/mise activate)"' >> ~/.zshrc

# Install all runtimes defined in mise.toml
mise install

# Verify installation
mise list

プロジェクト構成（モノレポ）

project-root/
├── mise.toml            # Root task definitions
├── apps/
│   ├── api/            # Backend application
│   │   └── mise.toml   # App-specific tasks
│   ├── web/            # Frontend application
│   │   └── mise.toml
│   └── mobile/         # Mobile application
│       └── mise.toml
├── packages/
│   ├── shared/         # Shared libraries
│   └── config/         # Shared configuration
└── scripts/            # Utility scripts

ルートの mise.toml でモノレポのタスクパスを有効にする必要があります。有効になっていない場合、すべての //path:task の呼び出しが「require a monorepo root configuration」というエラーで失敗します。

# Root mise.toml — monorepo_root is a top-level key (before any [table])
monorepo_root = true

[monorepo]
config_roots = ["apps/*", "packages/*"]

タスクの構文

ルートレベルのタスク：

mise run lint        # Lint all apps (parallel)
mise run test        # Test all apps (parallel)
mise run dev         # Start all dev servers
mise run build       # Production builds

アプリ固有のタスク：

# Syntax: mise run //{path}:{task}
# Requires monorepo_root = true in root mise.toml (see Project Structure)
mise run //apps/api:dev
mise run //apps/api:test
mise run //apps/web:build

TOML の引用符のルール： : を含むタスク名は引用符で囲む必要があります — [tasks."gen:api"] とし、[tasks.gen:api] のようにしてはいけません（引用符のないコロンは TOML の解析エラーになります）。

よくあるタスクパターン

タスクの種類	目的	例
dev	開発サーバーを起動する	mise run //apps/api:dev
build	本番用ビルド	mise run //apps/web:build
test	テストスイートを実行する	mise run //apps/api:test
lint	リンターを実行する	mise run lint
format	コードをフォーマットする	mise run format
format:check	書き込みを行わずにフォーマットを確認する	mise run format:check
typecheck	型チェック	mise run typecheck
check	該当する、出力を生成しないチェックをまとめて実行する	mise run check
migrate	データベースのマイグレーション	mise run //apps/api:migrate

リファレンスガイド

トピック	リソースファイル	読み込むタイミング
検証パイプライン	resources/validation-pipeline.md	Git フック、CI/CD、変更ベースのテスト、ローカルでの検証を繰り返す場合
データベースとインフラストラクチャ	resources/database-patterns.md	マイグレーション、ローカルの Docker インフラストラクチャ
API 生成	resources/api-workflows.md	API クライアントの生成
i18n パターン	resources/i18n-patterns.md	国際化
リリースの調整	resources/release-coordination.md	バージョン管理、変更履歴、リリース
トラブルシューティング	resources/troubleshooting.md	問題のデバッグ

タスクの依存関係

依存関係を mise.toml で定義します。

[tasks.build]
depends = ["lint", "test"]
run = "echo 'Building after lint and test pass'"

[tasks.dev]
depends = ["//apps/api:dev", "//apps/web:dev"]

並列実行と逐次実行

並列（独立したタスク）：

# Runs all lint tasks simultaneously (via depends)
mise run lint

# mise-native parallel execution of multiple tasks
mise run lint ::: test

逐次（依存関係のあるタスク）：

# Runs in order: lint → test → build
mise run lint && mise run test && mise run build

混合アプローチ：

# Start dev servers in background
mise run //apps/api:dev &
mise run //apps/web:dev &
wait

環境変数

モノレポの環境変数でよく使われるパターン：

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/db

# Cache
REDIS_URL=redis://localhost:6379/0

# API
API_URL=http://localhost:8000

# Frontend
PUBLIC_API_URL=http://localhost:8000

出力テンプレート

開発環境をセットアップする場合：

1. ランタイムのインストールを確認する（mise list）
2. アプリごとの依存関係インストールコマンド
3. 環境変数のテンプレート（.env.example）
4. 開発サーバーの起動コマンド
5. よく使うタスクのクイックリファレンス

タスクを実行する場合：

1. 実行したコマンドと完全なパス
2. 予想される出力の概要
3. 所要時間と成功／失敗のステータス
4. 次に推奨されるアクション

トラブルシューティングを行う場合：

1. 診断コマンド（mise config、mise doctor）
2. よくある問題の解決方法
3. ポート／プロセスの競合解決
4. 必要に応じたクリーンアップコマンド

トラブルシューティングガイド

問題	解決方法
タスクが見つからない	mise tasks --all を実行して、利用可能なタスクを一覧表示します
ランタイムが見つからない	mise install を実行して、不足しているランタイムをインストールします
タスクが停止する	対話型プロンプトがないか確認し、利用可能であれば --yes を使用します
ポートがすでに使用されている	プロセスを検索します：lsof -ti:PORT を実行してから終了します
アクセスが拒否される	ファイルのアクセス権を確認し、適切なユーザーで試します
依存関係が不足している	mise run install またはアプリ固有のインストールコマンドを実行します

実行方法

基本的なワークフローを順を追って実行します：

1. タスク要件を分析する - 影響を受けるアプリとタスクの依存関係を特定します
2. mise の設定を確認する - mise.toml の構造と利用可能なタスクを確認します
3. 実行戦略を決定する - タスクを並列実行するか逐次実行するかを決めます
4. 前提条件を実行する - 必要に応じてランタイムと依存関係をインストールします
5. タスクを実行する - 適切なエラー処理を行いながら mise タスクを実行します
6. 結果を検証する - 出力、ログ、生成された成果物を確認します
7. ステータスを報告する - 成功／失敗と、実行可能な次のステップを要約します

実行プロトコル（CLI モード）

参考資料

• ツーリングプロファイル：resources/tooling-profiles.md（Python、JS/TS、Dart/Flutter、Dockerfile、または commitlint のツーリングを設定または変更する場合）
• 確認： ../_shared/core/clarification-protocol.md
• タスクの分解：../_shared/core/difficulty-guide.md（スコープまたは依存関係が未解決の場合）

ナレッジリファレンス

mise、タスクランナー、モノレポ、開発サーバー、lint、format、test、typecheck、build、デプロイ、ci/cd、並列実行、ワークフロー、自動化、ツーリング