oma-dev-workflow

Dev Workflow - モノレポのタスク自動化スペシャリスト

スケジューリング

目標

mise、タスク自動化、検証パイプライン、CI/CD、マイグレーション、i18n ビルド、リリース調整を使用して、モノレポで再現可能な開発ワークフローをセットアップし、実行、最適化、トラブルシューティングします。

インテントシグネチャ

• ユーザーが開発サーバー、mise タスク、lint／format／typecheck／test／build、Git フック、CI/CD、マイグレーション、生成クライアント、i18n ビルド、リリース自動化について尋ねている。
• ユーザーが製品機能の実装ではなく、ワークフローの実行や開発環境のセットアップを必要としている。

使用する場合

• 複数のアプリケーションを含むモノレポで開発サーバーを実行する場合
• 複数のアプリに対して lint、format、typecheck を並列実行する場合
• データベースのマイグレーションやスキーマ変更を管理する場合
• スキーマから API クライアントやコードを生成する場合
• 国際化（i18n）ファイルをビルドする場合
• 本番ビルドを実行し、デプロイの準備をする場合
• モノレポ環境でタスクを並列実行する場合
• コミット前の検証ワークフローをセットアップする場合
• mise タスクの失敗や設定上の問題をトラブルシューティングする場合
• mise を使用して CI/CD パイプラインを最適化する場合

使用しない場合

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

想定される入力

• 要求されたワークフロー操作、対象のアプリ／パッケージ、現在のモノレポ構成
• 必要に応じて、mise.toml、タスク定義、CI ファイル、マイグレーション／i18n／ビルド設定、失敗ログ
• 希望する検証、セットアップ、またはリリースの結果

想定される出力

• 実行済み、または文書化された mise タスクのワークフロー
• 要求に応じて更新されたワークフロー設定、CI/CD パイプライン、フック、環境変数テンプレート、またはリリース手順
• コマンド、出力、失敗、次のアクションを含むステータスレポート

依存関係

• mise、プロジェクトのタスク定義、ランタイムバージョン、mise タスクが使用するパッケージマネージャー
• 検証、データベースのパターン、API ワークフロー、i18n、リリース調整、トラブルシューティングのリソースガイド

制御フローの機能

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

構造フロー

開始

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

シーン

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

遷移

• ランタイムバージョンが変更された場合は、mise install を実行します。
• 変更ファイルを対象とするタスクがある場合は、変更範囲に絞った検証を優先します。
• ポートが使用中の場合は、開発サーバーを起動する前に解決するか、別のポートを選択します。
• 不慣れなタスクの場合は、実行前に定義を読みます。

失敗と復旧

• タスクが見つからない場合は、mise tasks --all を実行します。
• ランタイムが見つからない場合は、mise install を実行するか、実行を推奨します。
• タスクが停止しない場合は、プロンプトの有無や、長時間実行される開発サーバーの動作を確認します。
• 破壊的なタスクが要求された場合は、確認を求めます。

終了

• 成功：ワークフローの実行、または設定変更を検証済みです。
• 部分的な成功：タスクの失敗、ランタイムの不足、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、リリース、トラブルシューティングのリソースガイド

標準コマンドパス

mise tasks --all
mise install
mise run lint
mise run test

アプリ固有のタスクの場合：

mise run //{path}:{task}

リソースの範囲

範囲	リソースの対象
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／テストを実行します（lint:changed、test:changed）
5. コミット前に commitlint でコミットメッセージを検証します
6. ステージ済みファイルのみを対象に、コミット前検証パイプラインを実行します
7. ビルドを高速化するため、変更のないアプリをスキップするよう CI を設定します
8. 実行前に mise tasks --all を確認して、利用可能なタスクを見つけます
9. CI/CD 統合では、タスクの出力と終了コードを検証します
10. mise.toml のコメントにタスクの依存関係を記載します
11. アプリ間で一貫したタスク命名規則を使用します
12. 再現可能なビルドのため、CI/CD パイプラインで mise を有効にします
13. 一貫性を保つため、mise.toml でランタイムバージョンを固定します
14. CI/CD の変更をコミットする前に、タスクをローカルでテストします
15. mise タスクが存在する場合、パッケージマネージャーのコマンドを直接実行してはいけません
16. タスクの依存関係を理解せずに mise.toml を変更してはいけません
17. ツールチェーンのバージョンを更新した後、mise install を省略してはいけません
18. まずポートが使用可能か確認せずに、開発サーバーを実行してはいけません
19. 影響を受けるアプリの検証を実行せずに、コミットしてはいけません
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）を設定します

技術ガイドライン

前提条件

# 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
typecheck	型チェックを実行する	mise run typecheck
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 モード）

参考資料

• 明確化：../_shared/core/clarification-protocol.md
• タスクの分解：../_shared/core/difficulty-guide.md（スコープまたは依存関係が未解決の場合）

ナレッジのリファレンス

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