mise-configuration

単一の信頼できる情報源としての mise 設定

後方互換性のあるデフォルト値を使い、mise の [env] を一元的な設定として使用します。

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

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• mise.toml に環境変数を一元化する
• mise で Python 仮想環境を自動作成するよう設定する
• モノレポ向けにハブ・スポーク構成を実装する
• 後方互換性のある環境設定パターンを作成する

基本原則

設定可能な値はすべて .mise.toml の [env] セクションで定義します。スクリプトでは、環境変数をデフォルト値にフォールバックさせて読み取ります。mise がインストールされていても、いなくても、同じコードパスが機能します。

重要なポイント：シェルで mise activate が設定されていると、mise は [env] の値を自動的に読み込みます。os.environ.get("VAR", "default") パターンを使用するスクリプトは、mise がある場合もない場合も同じように動作します。

クイックリファレンス

言語別パターン

言語	パターン	備考
Python	os.environ.get("VAR", "default")	文字列を返します。整数の場合は型変換してください
Bash	${VAR:-default}	標準の POSIX 展開
JavaScript	process.env.VAR || "default"	falsy チェック。「0」に注意してください
Go	os.Getenv("VAR") とデフォルト値	未設定の場合は空文字列になります
Rust	std::env::var("VAR").unwrap_or()	Result<String> を返します

特別なディレクティブ

ディレクティブ	目的	例
_.file	.env ファイルから読み込む	_.file = ".env"
_.path	PATH を拡張する	_.path = ["bin", "node_modules/.bin"]
_.source	bash スクリプトを実行する	_.source = "./scripts/env.sh"
_.python.venv	Python 仮想環境を自動作成する	_.python.venv = { path = ".venv", create = true }

オプションを含むディレクティブの詳細な例（redact、tools、複数ファイル）については、コードパターンを参照してください。

Python 仮想環境の自動作成（重要）

Python 仮想環境を自動作成して有効化します。

[env]
_.python.venv = { path = ".venv", create = true }

このパターンはすべてのプロジェクトで使用されます。mise を有効化した状態でディレクトリに入ると、次のように動作します。

1. .venv が存在しない場合は作成します
2. 仮想環境を自動的に有効化します
3. 仮想環境の高速作成に uv を使用できます

[settings] を使う方法：

[settings]
python.uv_venv_auto = true

ハブ・スポークアーキテクチャ（重要）

ドメイン固有のタスクをサブフォルダーの mise.toml ファイルに委譲し、ルートの mise.toml を簡潔に保ちます。モノレポ、ML／研究プロジェクト、インフラストラクチャ、データパイプラインに適用できます。

主なルール：

• ハブは [tools] とオーケストレーションタスクを管理します
• スポークはハブの [tools] を自動的に継承します
• スポークの [env] はハブの [env] を拡張します（ドメインごとに上書きできます）
• .mise.local.toml はディレクトリ単位で適用されます（シークレットはローカルに保持されます）

ディレクトリ構成、例、アンチパターンを含む詳細ガイド：ハブ・スポークアーキテクチャ

Wiki リファレンス：Pattern-mise-Configuration

モノレポのワークスペースパターン

uv ワークスペースを使用する Python モノレポでは、仮想環境はワークスペースのルートに作成されます。開発用依存関係は [dependency-groups]（PEP 735）を使ってルートの pyproject.toml に集約してください。

詳細ガイド：モノレポのワークスペースパターン

テンプレート構文（Tera）

mise は Tera テンプレートを使用します。区切り文字は、式が {{ }}、文が {% %}、コメントが {# #} です。

組み込み変数

変数	説明
{{config_root}}	.mise.toml を含むディレクトリ
{{cwd}}	現在の作業ディレクトリ
{{env.VAR}}	環境変数
{{mise_bin}}	mise バイナリへのパス
{{mise_pid}}	mise プロセス ID
{{xdg_cache_home}}	XDG キャッシュディレクトリ
{{xdg_config_home}}	XDG 設定ディレクトリ
{{xdg_data_home}}	XDG データディレクトリ

関数（get_env、exec、arch、read_file、hash_file）、フィルター（snakecase、trim、absolute）、条件分岐については、コードパターン - テンプレート構文をご覧ください。

必須変数と秘匿変数

[env]
# Required - fails if not set
DATABASE_URL = { required = true }
API_KEY = { required = "Get from https://example.com/api-keys" }

# Redacted - hides from output
SECRET = { value = "my_secret", redact = true }
_.file = { path = ".env.secrets", redact = true }

# Pattern-based redactions
redactions = ["*_TOKEN", "*_KEY", "PASSWORD"]

パターンの組み合わせや詳細な例については、コードパターン - 必須変数と秘匿変数をご覧ください。

遅延評価（tools = true）

デフォルトでは、ツールのインストール前に環境変数が解決されます。ツールが生成したパスにアクセスするには、tools = trueを使用してください。

[env]
GEM_BIN = { value = "{{env.GEM_HOME}}/bin", tools = true }
_.file = { path = ".env", tools = true }

[settings] と [tools]

[settings]
experimental = true
python.uv_venv_auto = true

[tools]
python = "<version>"
node = "latest"
uv = "latest"
rust = { version = "<version>", profile = "minimal" }

# SSoT-OK: mise min_version directive, not a package version
min_version = "2024.9.5"

設定の全リファレンスとバージョン固定のオプションについては、コードパターン - 設定とツールをご覧ください。

実装手順

1. ハードコードされた値を特定する - タイムアウト、パス、しきい値、機能フラグ
2. .mise.tomlを作成する - [env]セクションを追加し、変数を文書化する
3. venvの自動作成を追加する - _.python.venv = { path = ".venv", create = true }
4. スクリプトを更新する - 環境変数を使用し、元の値をデフォルトとして設定する
5. ADRへの参照を追加する - コメント：# ADR: 2025-12-08-mise-env-centralized-config
6. miseなしでテストする - デフォルト値を使用してスクリプトが動作することを確認する
7. miseを使用してテストする - 有効化したシェルが.mise.tomlの値を使用することを確認する

GitHub トークンの複数アカウントパターン {#github-token-multi-account-patterns}

miseはGitHubトークンを管理しません（ADR 2026-06-21）。 miseの[env]によるディレクトリごとのGH_TOKEN 注入は廃止されています。GitHubのIDはリポジトリの originホストエイリアス（[email protected]<account>:owner/repo）によって決まり、SSHキー、コミット ID（includeIf hasconfig:remote.*.url）、ghアカウントもすべてそこから導出されます。 ~/.zshrcのghラッパーは、環境に設定されたGH_TOKENをすべて除去します。スクリプトでトークンが必要な場合は、 その都度解決してください：GH_PAT="$(~/.claude/tools/bin/gh-token-for-repo)"。

詳細ガイド：GitHubの複数アカウント認証（ホストエイリアスモデル）

アンチパターン

アンチパターン	理由	代わりに
mise exec -- script.py	miseへの依存を強制する	デフォルト値を設定した環境変数を使用する
.mise.toml内のシークレット	リポジトリ内で見える	Dopplerまたはredact = trueを使用する
スクリプトにデフォルト値がない	miseなしでは動作しない	常に代替値を用意する
pueueジョブの[env]シークレット	Pueueはmiseのないクリーンなシェルを実行する	python-dotenvと.envファイルを使用する
SSH経由で__MISE_DIFFが漏れる	リモートの信頼エラー	SSHの前にunset __MISE_DIFFを実行する

非対話型シェルのシークレットに関する重要事項：アンチパターンガイド

タスクオーケストレーションとの統合

miseの設定中に複数ステップのプロジェクトワークフローを検出した場合は、依存関係を管理するタスク定義にmise-tasksスキルを呼び出してください。

検出のきっかけ：複数ステップのワークフロー、繰り返し実行するコマンド、依存関係チェーン、ファイル追跡型ビルド。

例を含む詳細ガイド：タスクオーケストレーション | mise-tasksスキル

---

追加リソース

• コードパターンとテンプレート - Python、Bash、JS、Go、Rust の完全なコード例と、完全な .mise.toml テンプレート
• ハブ・スポークアーキテクチャ - ディレクトリ構造、ハブ／スポークの役割、継承ルール
• GitHub トークンのパターン - 複数アカウントのセットアップ、検証、1Password との連携
• アンチパターンガイド - 非対話型シェルのシークレット、pueue／cron／systemd の注意点
• タスクオーケストレーション - ワークフロー検出のトリガー、環境からタスクへの設定例
• モノレポワークスペース - uv ワークスペース、集約された開発依存関係（PEP 735）
• Wiki: Pattern-mise-Configuration

ADR の参照先：mise の設定を実装する際は、プロジェクト内の docs/adr/YYYY-MM-DD-mise-env-centralized-config.md に ADR を作成してください。

---

トラブルシューティング

問題	原因	解決策
環境変数が読み込まれない	mise が有効化されていない	シェルの rc ファイルに mise activate を追加
venv が作成されない	Python がインストールされていない	mise install python を実行
タスクが見つからない	mise.toml の場所が誤っている	mise.toml がプロジェクトのルートにあることを確認
PATH が更新されない	PATH に shims がない	~/.zshenv に mise shims を追加
.file が読み込まれない	.env ファイルがない	.env ファイルを作成するか、.file ディレクティブを削除
サブフォルダーの設定が無視される	min_version がない	サブフォルダーの mise.toml に min_version を追加

実行後の振り返り

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

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

問題が実際に発生し、再現できる場合にのみ更新してください。推測に基づく更新は行わないでください。