mise-fy

mise-fy

人間向けの紹介

mise（hkと併用）を最大限に活用するためのベストプラクティス、ヒント、注意点を、さまざまなレベルのチーム向けに、開発（および CI）環境を構築してきた経験からまとめました。あなたやエージェントが使いたくなる、✨すぐに使える✨環境を目指します。

このスキルには、次の 2 つのトリガーモードがあります。

1. Mise を使う際のヒントや注意点をエージェントに提供します。（当然です！）
2. 既存のプロジェクトを**Mise-fy** 🪄し、推奨される構成に変換します。

このスキルに含まれる内容については、各トピックのリファレンスである./referencesを参照してください。

ヒント

このスキルは、特に mise-fy を行う際に、Opus 4.8やGPT 5.5と同程度の一貫性レベルを持つモデルで使えるように作成、最適化されています。

このスキルは、Mise の全機能を列挙するものではありません。エージェントが持つ世界知識とドキュメントを読む能力（そして、エージェントにドキュメントを読むよう求めること）を活用しつつ、ベストプラクティスに沿ってエージェントを導きます。今後、対応するユースケースを増やすかもしれません！

これは「Mise」スキル？それとも優れたローカル開発環境のセットアップスキル？

どちらでもあります。開発環境で優れた UX を実現するには、Mise が最適なツールなので、両者には大きな重なりがあります。ただし、このスキルは主に Mise に焦点を当てており、Mise が関わる場合のヒントや注意点のみを扱います。ランタイムに特化した「local-setup」スキルと組み合わせるとよいでしょう（近いうちに登場するかもしれません！）。

このスキルでは具体的に何を扱いますか？

このスキルでは、開発環境がすぐに使え、見つけやすく、正しくセットアップできるようにするために必要なことを扱います。

すぐに使えます。 リポジトリをクローンして、mise trust && mise run setupを実行すれば完了です。ツールはバージョンが固定され、ロックされた状態でインストールされるため、全員と CI で同じバージョンを使えます。セットアップは冪等でキャッシュされるため、再実行しても手間はかかりません（worktree でも同様です！）。また、git フックはmise install時に自動でインストールされ、インストールしていない場合は警告されます。そうすれば、信頼した全員とそのエージェントが、ローカルのリンター、テスト、検証を利用できます！

見つけやすいです。 タスク名は、すべてのリポジトリで統一されています

---

スキルの使い方

このスキルでは段階的開示を採用しています。各領域から、実際のルールとベストプラクティスが記載されたreferences/ファイルを参照します。 計画や作業に取りかかる前に、該当するリファレンスを読んでください。作業の後ではありません。SKILL.md だけでは不十分です。事前に計画を立て、必要なリファレンスをすべて読んでください！

リファレンスを読むタイミング

以下のルーターから、少なくとも 1 つのリファレンスを必ず読んでください。目的によっては、複数のリファレンスを読む必要があるかもしれません。 ローカルの.md リファレンスは積極的に読み込んでください。オンラインのリンクやリファレンスは、本当に必要な場合を除き、読み込まないでください。基本的には自分の知識を信頼してください。詳しく知る必要がある場合に限り、オンラインのリファレンスを読み込んでください。 リファレンス内のコマンドやキーは、一般的な呼び出し方であり、すべての機能を網羅しているわけではありません。--helpと最新のドキュメントを優先してください。[daemons]などの実験的な機能は学習データにあまり含まれていないため、ページに記載されていない機能を使う前に、リンク先のドキュメントを読んでください。

Router

mise のインストール（プロジェクトのセットアップではなく、マシンのセットアップ）→ references/install.md パッケージマネージャー経由でのインストール、シェルの有効化、非対話型シェル向けのシム、補完機能。

開発ツール／ランタイム（インストール、バージョン固定、更新、バックエンド、ロックファイル、遅延読み込み／一般的でないツール）→ references/tools.md ツールまたはランタイムのインストール。

ランタイム統合（ランタイムごとのパッケージマネージャー、依存関係のインストール）→ references/runtimes/。

• Node → runtimes/node.md

環境と変数（プロジェクト環境、dotenv、シークレット）→ references/env.md [env]、_.file／_.path／_.source、テンプレート、必須変数、デフォルトのフォールバック、値の秘匿、PATH の更新、.env ファイルの読み込み、設定環境（MISE_ENV）、シェルエイリアス。

タスク（スクリプトの実行、ビルドパイプライン、監視）→ references/tasks.md TOML タスクとファイルタスク、depends／wait_for、キャッシュ用の sources／outputs、実行と並列処理、mise watch（変更時に再実行）。

ローカル開発スタック（バックグラウンドで動作するデータベース、キャッシュ、アプリケーションサーバー、ワーカー。ワークツリーごとのスタック）→ references/dev.md [daemons] のプリセットとカスタムデーモン、ポートブロック、準備完了／ヘルスチェック／再試行、マイグレーション、dev:* タスク、例外としての Compose。

フック（ディレクトリとライフサイクル：enter／cd、watch_files、postinstall）→ references/hooks.md enter／cd フックをオフラインでも安全に保つ方法（mise run ではなく通常のシェル）、信頼への影響、シムに関する注意点。Git／pre-commit フックについては、下記の hk を参照してください。

hk フック（pre-commit／Git フック）→ references/hk.md hk.pkl（Pkl、.config/hk.pkl に配置）、check と fix の違い、組み込み機能、mise との統合、インストール、カスタムステップによる拡張、リンター設定の配置場所である .config/。

CI（CI での mise タスク／ツールの実行：シム、キャッシュ、バージョン固定、トークン）→ references/ci.md プラットフォームに依存しない一般的な CI のルール。プラットフォーム固有の内容は references/ci/ にあります。

• GitHub Actions → ci/github.md

既存プロジェクトを mise-fy する（移行と監査）→ references/mise-fy.md カスタム設定／asdf／Makefile からの段階的な移行に加え、完全な監査チェックリストを掲載しています。他のすべてのドキュメントを参照しています。

プロジェクトドキュメント（README と AGENTS.md によるオンボーディング）→ references/docs.md 人間とエージェントが mise をインストールし、セットアップして、タスクを実行し、セットアップを拡張できるよう、README.md と AGENTS.md／CLAUDE.md に記載する内容。mise-fy／監査のたびに必要です。

リファレンスセットアップ（標準的なサンプル構成）→ references/reference-setup-and-patterns.md 注釈付きのサンプルファイルツリーと、コピーして使用できる mise.toml。

補完スキル

CI/CD（チェック／リリース／公開のワークフロー、ゲーティング、署名、コミュニティの衛生管理）→ インストールされている場合は、cicd-fy スキル（同じ作成者による）を読み込んでください。 このスキルでは CI での mise の実行を扱います。パイプラインの構成は cicd-fy の担当領域です。

常に適用される事項（タスクに関係なく）

どのリファレンスを読み込んだ場合も、これらの事項は適用されます。特定のタスクに集中しているときも確認してください。 意見の分かれるベストプラクティスとは異なり（それらは目標に合わせて適用範囲を絞ってください）、これらは安全性と正確性を守るための最低基準です。1 つのツールを変更するだけの場合も適用し、後回しにしてよい仕上げとして扱わないでください。

1. 信頼されていない設定ファイルはエラーになります。 [env]、フック、テンプレート、またはタスクロジックを含む mise.toml は、mise trust を実行するまでファイル全体がハードエラーになります（対話型シェルでは信頼するか確認され、非対話型シェルではエラーになります）。min_version と、プレーン文字列のみを含む [tools]／[tasks] だけのファイルは、信頼されていない状態でも読み込まれます（2026.6.6 以降）。mise run／install／exec は、アクティブな設定ファイルを自動的に信頼します（2026.8.9 以降）。一方、mise env と古いクライアントでは引き続きエラーになり、シェルフックは警告を出してファイルをスキップします。そのため、ドキュメントでは明示的な mise trust（または trusted_config_paths エントリ）を記載してください。 信頼されていないファイルの [settings] は何も通知されずに無視されるため、disable_backends や minimum_release_age などのセキュリティ設定は、信頼されるまで無効のままです。
2. **一部の機能には experimental = true が必要で、**リリース間で変更される場合があります。ドキュメントに記載されたフラグでエラーが発生した場合は、実験的機能として制限されていないか確認してください。
3. min_version を設定してください（[settings] の中ではなく、ルートレベルに設定します）。設定ファイルが使用するすべての機能に対応する最古のリリースを指定します。ただし、既知の脆弱性があるバージョンの下限（2026.10.13）より古くしてはならず、作成者がインストールしているバージョンより新しくしてもいけません。これにより、古いクライアントには、対応していない機能で失敗する代わりに、更新を促すメッセージが表示されます。
4. ツールのインストール時の GitHub レート制限を回避してください（ローカル環境と CI の両方）。[settings] の下に github.gh_cli_tokens と github.use_git_credentials を設定します。 mise はまず gh CLI のトークンを試し、次に git の認証情報にフォールバックします。失敗しても処理は続行されます。 CI では GITHUB_TOKEN 環境変数も使用できます（ci.md を参照）。
5. **Mise の変化は速いため、**行き詰まったときはドキュメントと併せて最近の変更履歴を確認してください。
6. シムでは mise activate のすべての機能を利用できるわけではありません（例：cd 時の一部の環境変数設定）。ローカル環境と CI の不一致は、多くの場合これが原因です。install.md／ci.md を参照してください。
7. Fast path と slow path の考え方を常に意識してください。 1 日に何度も実行されるもの（例：check、enter フック、pre-commit）は fast path です。低コストで、オフラインでも安全に実行でき、対話を必要としないものにしてください。 セットアップは slow path です。時間がかかっても、オンラインでも、対話型でもかまいません。fast-path タスクを slow-path タスクに依存させてはいけません。代わりに、実行を促すようにしてください。 メンバーを一覧にしているのはレーンマップだけです。
8. より一般的には、ユーザーがそのタスクをどのくらいの頻度で実行するかを常に考えてください。実行頻度の異なるタスク同士を依存させてはいけません。
9. mise.toml のトップレベルセクションは、初めて追加する場合も含め、順序を守ってください。 min_version → [tools] → [env] → [vars] → [tasks] → [daemons] → [hooks] → [doctor] → [settings] の順です。一覧にないセクションは [settings] より前に置き、関連するセクションの隣に配置してください。