Work Documentation

Appearance

mise Guide ​

本ガイドでは、コマンド実行制限下における miseタスクの運用方針、タスク設定ファイルの役割分担、タスクの定義方法、および実行手順について解説します。

概要と実行方針 ​

コマンド実行権限のセキュリティを強化するため、原則として任意のコマンド直接実行を制限します。作業に必要なコマンドは、事前に定義された miseタスク経由（mise run <task>）で実行します。

運用のメリット ​

  • 再現性の確保: プロジェクト内で実行するコマンドとその引数を標準化できます。

  • 安全性の向上: 許可されたタスクのみを実行するため、意図しない破壊的コマンドの実行を防止できます。

  • 環境の統一: mise が管理するツールバージョンや環境変数を自動で適用して実行できます。

タスク設定ファイルの配置と役割分担 ​

タスクはその性質や寿命に応じて、3つの設定ファイルに分類して記述します。

タスク分類設定ファイル配置パス主な役割Git 管理
永続タスクmise.toml<root>/mise.tomlプロジェクト共通のビルド、テスト、リント等の長期タスク対象
一時タスクtasks.toml<workspace>/tasks.toml開発作業中の検証、使い捨て処理、デバッグ用タスク対象外
テンプレートタスクconfig.toml<root>/.mise/config.tomlaidev-template 基盤の共通管理タスク対象

1. 永続タスク (<root>/mise.toml) ​

プロジェクト全体で継続的に使用するタスクを定義します。開発メンバー全員で共有し、Git のバージョン管理対象に含めます。

  • プロジェクトのビルド、テスト実行、リント検証
  • アプリケーションの起動やデプロイ手順
  • プロジェクト固有の定常的なスクリプト実行

2. 一時タスク (<workspace>/tasks.toml) ​

特定の課題対応や検証作業のために一時的に作成するタスクを定義します。<workspace>（.local/workspace/）配下に配置され、Git 管理からは除外されます。

  • ワンショットのデータ移行や検証スクリプトの実行
  • 問題切り分けのためのデバッグ用コマンド
  • 試作中のスクリプト呼び出し

3. テンプレートタスク (<root>/.mise/config.toml) ​

aidev-template の基盤機能として提供される共通タスクを定義します。テンプレート同期やドキュメント検証など、テンプレート共通の仕組みを担います。

  • テンプレート同期スクリプト（sync_template.py）の実行
  • ドキュメントサーバーの起動
  • エージェントハーネス共通のユーティリティ呼び出し

設定ファイルの連携 (include 設定) ​

一時タスク（<workspace>/tasks.toml）やテンプレートタスク（.mise/config.toml）を mise に認識させるため、<root>/mise.toml または .mise/config.toml にて includes 設定を行います。

toml
# <root>/mise.toml または .mise/config.toml
[includes]
files = [
    ".local/workspace/tasks.toml",
    ".mise/config.toml"
]

※ 一時タスクファイルが存在しない場合でもエラーとならないよう、ファイル作成時に読み込みを有効化します。

mise タスクの定義方法 ​

タスクは TOML 形式で定義します。目的に応じて適切な設定ファイルを選択し、ファイル種別に応じたキー形式で記述します。

IMPORTANT

設定ファイルによるタスク名キー形式の違い:

  • 一時タスク (<workspace>/tasks.toml): 単体タスク定義ファイルのため、[tasks.<task-name>] ではなく [<task-name>] （例: [hello], ["scope:task"]）と直接記述します。
  • 永続タスク (<root>/mise.toml, .mise/config.toml): 設定ファイル内のタスク定義のため、[tasks.<task-name>] と記述します。

タスクを作成・追加する際は、create-mise-task スキル を使用して適切なファイルと形式で作成します。

1. 基本的なタスク定義 ​

最も単純な形式では、run プロパティに実行するコマンド文字列を指定します。

toml
[tasks.hello]
description = "挨拶を出力するタスク"
run = "echo Hello World"

2. 複数行コマンドの定義 ​

複数のコマンドを順番に実行する場合は、文字列配列またはヒアドキュメントを使用します。

toml
[tasks.build]
description = "ビルドを実行するタスク"
run = [
    "echo Building project...",
    "npm run build"
]

3. 作業ディレクトリと環境変数の指定 ​

特定のディレクトリでコマンドを実行したい場合や、一時的な環境変数を渡したい場合は、dir や env を指定します。

toml
[tasks.test-app]
description = "app コンポーネントのテストを実行"
dir = "apps/my-app"
env = { NODE_ENV = "test" }
run = "npm test"

4. 依存タスクの指定 ​

実行前に別のタスクを完了させる必要がある場合は、depends を指定します。

toml
[tasks.deploy]
description = "ビルド後にデプロイを実行"
depends = ["build"]
run = "pwsh.exe ./scripts/deploy.ps1"

mise タスクの実行方法 ​

タスクを実行する際の基本コマンドとオプションです。

1. タスクの一覧表示 ​

利用可能なタスクの一覧および説明を確認します。

powershell
mise tasks

2. タスクの実行 ​

定義されたタスク名を指定して実行します。

powershell
mise run <task-name>

▸ 実行例

powershell
mise run test

3. 引数の受け渡し ​

タスクに任意の引数を渡す場合は、-- に続けて引数を指定します。

powershell
mise run <task-name> -- <args...>

▸ 実行例

powershell
mise run lint -- docs/guide/mise-guide.md

4. 作業ディレクトリを指定した実行 ​

プロジェクトルート以外のディレクトリをカレントとして実行する場合は、-C オプションを使用します。

powershell
mise -C apps/my-app run test

運用フローとルール ​

1. エージェント作業時のタスク実行手順 ​

  1. 既存タスクの確認: 実行したい処理がすでに <root>/mise.toml、<workspace>/tasks.toml、.mise/config.toml に定義されているか確認します。
  2. タスクの追加: 未定義の処理の場合、create-mise-task スキルを使用して適切なファイル（一時タスクなら <workspace>/tasks.toml、永続タスクなら <root>/mise.toml）にタスク定義を追加します。
  3. タスクの実行: mise run <task-name> を使用してタスクを実行します。
  4. 永続化の検討: 作成した一時タスクが今後も繰り返し利用される性質のものである場合、<root>/mise.toml への移動を検討・提案します。

2. 注意事項 ​

  • PowerShell 構文: Windows 環境では標準シェルとして pwsh.exe が使われるため、タスク内のスクリプトも PowerShell 7.x 互換で記述します。
  • パスの表記: 設定ファイル内および引数のパス指定にはスラッシュ（/）を使用します。
  • ファイル配置の厳守: 一時的なタスクをプロジェクトルートの mise.toml に直接書き込まず、必ず <workspace>/tasks.toml に切り分けて管理します。