justfile-expert

Justfile エキスパート

Just コマンドランナー、レシピの開発、タスクの自動化に関する専門知識を提供します。クロスプラットフォーム対応とプロジェクトの標準化に重点を置いています。

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

このスキルを使用する場合...	代替手段を使用する場合...
タスク自動化のために justfile を作成・編集する	増分コンパイルに対応したビルドシステムが必要 → Make
クロスプラットフォーム対応のプロジェクトコマンドを作成する	ツールのバージョン管理が組み込まれている必要がある → mise tasks
シバンレシピ（Python、Node、Ruby など）を追加する	プロジェクトのすべてのツールにすでに mise を使用している
dotenv の読み込みと設定を構成する	シェル自体を作成する（パイプ、トラップ、引数解析）→ shell-expert
just レシピを使用して CI/CD を設定する	プロジェクトですでに大規模な Makefile を使用している
複数のプロジェクトでレシピを標準化する	一括スモークテスト用のモジュールを公開する → cli-smoke-recipes

主な専門分野

コマンドランナーの熟知

• Justfile の構文とレシピ構成
• クロスプラットフォームのタスク自動化（Linux、macOS、Windows）
• パラメーターの処理と引数の転送
• 大規模プロジェクト向けのモジュール構成

優れたレシピの開発

• 一般的な操作に対応するレシピのパターン
• レシピ間の依存関係の管理
• 複雑なロジックに対応するシバンレシピ
• 環境変数との連携

プロジェクトの標準化

• 標準的な命名とセクション構成を採用したゴールデンテンプレート
• プロジェクトの操作を自己文書化
• プロジェクト間で再利用できるポータブルなパターン
• CI/CD パイプラインとの統合

レシピの命名規則

ルール	パターン	例
ハイフンで区切る	word-word	test-unit、format-check
動詞を先頭にする（アクション）	verb-object	lint、build、clean
名詞を先頭にする（カテゴリ）	noun-verb	db-migrate、docs-serve
プライベート用の接頭辞	_name	_generate-secrets、_setup
-check の接尾辞	読み取り専用の検証	format-check
-fix の接尾辞	自動修正	lint-fix、check-fix
-watch の接尾辞	ウォッチモード	test-watch、docs-watch
基本名の後に修飾語を付ける	base-modifier	build-release（release-build ではない）

標準レシピとワークフローレシピ

プロジェクトの justfile を作成または標準化する際は、意味的な複合レシピ（check、pre-commit、ci、clean、clean-all）、標準レシピ一式、セクション構成について、references/standard-recipes.md を開いてください。

主な機能

パラメーターの形式、設定、レシピ属性（[doc]、[private]、[group]、[confirm]、プラットフォーム）、モジュールシステムについては、references/key-capabilities.md を参照してください。set fallback はモジュールに継承されない点にも注意してください。

基本構文

基本的なレシピ構造

# Comment describes the recipe
recipe-name:
    command1
    command2

パラメーター付きレシピ

build target:
    @echo "Building {{target}}..."
    cd {{quote(target)}} && make

test *args:
    uv run pytest {{args}}

補間は引用符で囲まれません — スペースを含む可能性のある値はすべて引用符で囲んでください

{{...}} はシェルが解析する前にレシピ本文へ生のテキストを挿入するため、スペースや引用符を含む値は単語に分割されます。上記の *args による引き渡しでは特に問題になります。just 自体ではなく呼び出されたプログラムがエラーを報告するため、ツールのバグのように見えてしまいます。

# Trap — one argument with spaces arrives as several
caption *ARGS:
    ./tool.py {{ARGS}}

$ just caption ./data "the subject's face"
tool.py: error: unrecognized arguments: subjects face

外側のシェルが引用符を取り除き（アポストロフィも一緒に取り除き）、the／subject's／face がそれぞれ別の argv 要素として渡されました。スペースを含む可能性があるパラメーターには名前を付け、適切にシェルエスケープされたリテラルを出力する quote() に渡してください。

# Correct — named params are quoted; trailing flags still pass through
caption DIR SUBJECT="" *ARGS:
    ./tool.py {{quote(DIR)}} {{quote(SUBJECT)}} {{ARGS}}

quote() は埋め込まれたスペース、'、"、$ に対応します。{{ARGS}} は引用符で囲まずに使ってください。そうすることで、末尾にある複数のフラグを個別の単語として展開できます。その代わり、個々の引き渡しフラグの値にはスペースを含められません。スペースが含まれる可能性がある場合は、それも名前付きパラメーターにしてください。

--list に表示されるのは1行だけであり、コメントブロックではありません

just --list では、レシピごとに1つの説明が表示されます。[doc] 属性がない場合、レシピの直前にあるコメントブロックの最後の行が使われます。最初の行でも、ブロック全体でもありません。

レシピの直前にあるもの	--list に表示される内容
[doc("Build the release bundle.")]	そのテキスト
コメントブロック、属性なし	最後の行だけ
[doc] のみ	なし
なし	なし

つまり、「各レシピの前にコメントを追加する」ことと、レシピをドキュメント化することは同じではありません。例や注意事項で終わるブロックは一般的な書き方ですが、その場合はその断片だけが一覧に表示されます。

# Pitch-correct the singing in an MP4. Video is stream-copied.
#   just autotune take.mp4 out.mp4 --key C:minor
autotune IN OUT *FLAGS:

$ just --list
    autotune IN OUT *FLAGS   # just autotune take.mp4 out.mp4 --key C:minor

レシピのコメントブロックが2行以上になったら、すぐに [doc("one line")] を追加してください。 ブロックはそのままの場所に置いて詳細を記載し続け、--list が読み取るのはこの属性だけです。

ブロックは隣接するレシピに結び付き、割り当て直されても通知されません。 空行があるとブロックは終了するため、ブロックと説明対象のレシピの間に別のレシピを挿入すると、そのブロックは新しいレシピに付け替えられます。元のレシピは一覧で空欄になり、警告も表示されません。既存のファイルにレシピを挿入した後は、just --list をもう一度確認してください。

必須の位置引数を持つレシピには、--help の形式がありません。 recipe *ARGS: は --help を下位のツールに渡しますが、位置引数が必須になると、just はツールを実行する前に呼び出しを拒否します。

$ just autotune --help
error: recipe `autotune` got 1 positional argument but takes at least 2

このようなレシピには、ヘルプだけを表示する指定方法はありません。フラグを [doc] またはコメントブロックに記載するか、フラグを表示する help レシピを追加してください。

レシピの依存関係

default: build test

build: _setup
    cargo build --release

_setup:
    @echo "Setting up..."

変数と補間

version := "1.0.0"
project := env('PROJECT_NAME', 'default')

info:
    @echo "Project: {{project}} v{{version}}"

条件付きレシピ

[unix]
open:
    xdg-open http://localhost:8080

[windows]
open:
    start http://localhost:8080

よくあるパターン

セットアップ、Docker、データベース、CI／リリースのレシピ、およびモジュール間の共有インポートにプロジェクトごとの値を渡す方法（共有変数ではなくパラメーターを使用）：references/common-patterns.md。

MCP 統合（just-mcp）

justfile を読み込む代わりに、AI クライアントが MCP 経由でレシピを一覧表示・実行できるようにする方法については、references/mcp-integration.md を参照してください。

エージェント向けの最適化

コンテキスト	コマンド
すべてのレシピを一覧表示	just --list または just -l
ドライラン（プレビュー）	just --dry-run recipe
変数を表示	just --evaluate
解析済み justfile 全体を JSON で表示（レシピ、パラメーター、依存関係、設定）	just --dump --dump-format json
レシピ名のみを表示	just --summary
詳細な実行情報を表示	just --verbose recipe
特定の justfile を指定	just --justfile path recipe
作業ディレクトリを指定	just --working-directory path recipe
対話形式で選択	just --choose

ベストプラクティス

レシピ開発のワークフロー

1. わかりやすい名前を付ける：build、test、deploy など、動詞を使った具体的な名前にします
2. --list に表示される内容を記述する：1 行コメントで十分です。それより長い場合は [doc("...")] が必要です。指定しないと、一覧にはブロックの最終行だけが表示されます
3. デフォルト値を使う：妥当なデフォルトのパラメーター値を指定します
4. 論理的にグループ化する：ファイル内にはセクションコメントを付け、一覧には [group("name")] を使います。レシピが 20 個程度を超えると、フラットな --list では一覧性が損なわれます
5. 内部処理を隠す：ヘルパーレシピに [private] を指定します
6. 移植性をテストする：対象となるすべてのプラットフォームで動作を確認します

重要なガイドライン

• ヘルプを表示する default レシピを必ず用意します
• 必要に応じて @ プレフィックスを付け、コマンドのエコーを抑制します
• 複数行のロジックにはシバンレシピを使います
• 設定には set dotenv-load を優先して使います
• 大規模なプロジェクト（レシピが 20 個を超える場合）ではモジュールを使います
• コメントブロックの最終行だけでは説明として読めない場合は、レシピに [doc("...")] を指定します。--list にはその行だけが表示されます（上記の「--list に表示される内容」を参照）。該当箇所を見つけるには、次を実行します： python3 "${CLAUDE_PLUGIN_ROOT}/scripts/just-recipe-help.py" --audit
• 柔軟に引数を受け渡せるよう、可変長の *args を含めます
• シェルコマンド内の変数はすべて引用符で囲みます。{{...}} は引用符なしで展開されるため、スペースを含む可能性があるパラメーターは quote() で囲みます（上記の「展開時に引用符は付かない」を参照）。スペースを含まない引数をそのまま渡す場合に限り、引用符なしの {{args}} が適切です

代替手段との比較

機能の比較表と Just、Make、mise タスクの選び方については、references/comparison.md を参照してください。

基本となる justfile のテンプレート、詳細な構文リファレンス、高度なパターン、トラブルシューティングについては、REFERENCE.md を参照してください。