justfile

Justfile スキル

just はコマンドランナー（ビルドシステムではありません）で、プロジェクト固有のコマンドを Justfile というファイルに保存して実行します。make に着想を得た構文を使いますが、よりシンプルで移植性に優れており、make 特有の癖（.PHONY、タブの扱い、暗黙のルール、タイムスタンプの追跡）はありません。

このスキルでは、一貫したハウススタイルを適用し、すべてのプロジェクトで Justfile の見た目を統一します。以下のルールが正式な規約であり、決定論的に検証できる項目は Tools/lint.ts で検証します。

ワークフローの振り分け

トリガー	ワークフロー
"create a justfile", "set up just", "add a recipe/module"	Workflows/CreateJustfile.md
"migrate Makefile to just", "convert make to just"	Workflows/MigrateFromMake.md
"check/lint this justfile", "is this justfile correct"	Workflows/CheckJustfile.md

Just と Make の使い分け

シナリオ	ツール
プロジェクトのタスク自動化（ビルド、テスト、デプロイ、リンティング）	just
クロスプラットフォームのコマンドランナー	just
実際のファイルベースのビルド依存関係（.c → .o のコンパイル）	make
すでに make に深く依存しているレガシープロジェクト	make（または移行）

よくある間違い — 次のようにしないでください

モデルがよく誤って生成するパターンです。出力がこの一覧に反していないか確認してください。

間違い	正しい
justfile（小文字）	Justfile（J は大文字）
mod docker（単独）	mod docker '.justfiles/docker.just'
docker.just または just/docker.just にモジュールを配置	.justfiles/docker.just にモジュールを配置
default:	_default:（アンダースコアが必須）
@just --list	@just --list --unsorted（モジュール）または --unsorted --list-submodules（モジュールを含むルート）
env("NAME", "val")	env_var_or_default("NAME", "val")
3 行のヘッダーがないモジュールファイル	すべてのファイルに完全なヘッダーを付ける
独自の _default レシピがないモジュールファイル	すべてのファイルに独自の _default を設ける
ツール名にちなんだモジュール（psql.just）	懸念事項にちなんだモジュール（db.just）
コンテナ内で実行するからと docker.just にテストを配置	テストは test.just に配置 — 実装方法ではなく目的で分類する
ルートのレシピでモジュールのロジックを重複	ルートのショートカットから委譲する：build: docker-build
場当たり的な名前（run-tests、do-lint）	標準的な名前：test、lint、build、dev、fmt、check
モジュールのレシピで相対パスを使用（bash tests/run.sh）	絶対パスには source_directory() を使う

必須ルール — 作成または編集するすべてのファイルに適用

1. ルートファイルの名前は必ず Justfile（J は大文字）にしてください。
2. すべてのファイル（ルートおよびすべての .just モジュール）は、次の3行のヘッダーで始める必要があります。

   #!/usr/bin/env just --justfile
   set shell := ["bash", "-euo", "pipefail", "-c"]
   set dotenv-load := true
   

   適切な場合は set dotenv-load := false を使用しますが、この行は必ず含めてください。
3. すべてのファイルで、最初のレシピは必ず _default にしてください。

   # List all available recipes
   _default:
       @just --list --unsorted
   

   モジュールを含むルートの Justfile では @just --list --unsorted --list-submodules を使用します。モジュールファイルでは @just --list --unsorted を使用します（--list-submodules は付けません）。
4. すべてのファイルで、セクションの順序は 変数 → モジュールのインポート → レシピ とします。
5. モジュールファイルは .justfiles/<name>.just に置く必要があります。just/ やルートと同じディレクトリには置かないでください。
6. モジュールは明示的なパスでインポートします：mod name '.justfiles/name.just'。mod name のみの指定は禁止です。
7. 変数のデフォルト値には env_var_or_default("NAME", "value") を使用します。env() は使用しないでください。
8. すべてのレシピの直前の行に、# のドキュメントコメントを付けてください。
9. パラメーター付きのレシピでは、各パラメーターを説明してください：# param - description (default: value)。
10. プライベート／ヘルパーレシピの名前は _ で始めてください。
11. 依存関係は定義行に記述してください：build: _lint test。
12. 破壊的なレシピでは確認を求めます。ドキュメントコメントには「DESTRUCTIVE, prompts for confirmation」と記載してください。
13. モジュールはツールではなく ドメイン上の関心事 ごとに分割し、その関心事にちなんだ名前（psql.just ではなく db.just）を付けてください。ルートの Justfile は薄いオーケストレーターとし、_default、ショートカットレシピ、check／clean のようなプロジェクト全体のレシピを配置します。
14. ルートには、モジュールに処理を委譲する、よく使うワークフロー用のショートカットレシピを用意し、開発者が日常的なタスクをフラットな名前空間で実行できるようにします。
15. パブリック API には、以下の標準レシピ名を使用してください。run-tests、do-lint、compile、format などの名前を独自に作らないでください。
16. モジュールでは、相対パスをそのまま使用しないでください。モジュールのレシピは、そのモジュールのディレクトリを CWD として実行されます。root := source_directory() / ".." を定義し、ファイルを {{root}}/tests/run.sh のように参照してください。

標準レシピ名

開発者がどのプロジェクトでも、迷わず just test、just dev、just check を実行できるようにしてください。以下の正確な名前を使用し、該当するものだけを含めてください。

レシピ	目的	含める条件
dev	開発環境を起動する（サーバー、監視、REPL）	プロジェクトに開発ループがある
test	テストスイートを実行する	常に含める
build	ビルドまたはコンパイルする	プロジェクトにビルド手順がある
lint	リンターを実行する	リンターが設定されている
fmt	コードをフォーマットする	フォーマッターが設定されている
check	すべての品質ゲートを実行する（check: lint test）	常に含める
clean	ビルド成果物、キャッシュ、生成ファイルを削除する	プロジェクトが出力を生成する

check はメタレシピです。該当する品質ゲートに依存させ、必要に応じてフォーマットチェック（cargo fmt --check、ruff format --check）も追加してください。

関心事ごとの名前空間

ツールではなく ドメイン ごとにまとめてください。目的に基づいて分類します。Docker で実行するテストは テスト レシピ（test.just）であり、Docker レシピではありません。kubectl を使うマイグレーションは データベース レシピ（db.just）です。

関心事	モジュール	代表的なレシピ
開発	dev.just	build、test、lint、fmt、bench
テスト	test.just	run、list、watch、coverage
コンテナー	docker.just	build、push、run、compose-up
CI/CD	ci.just	lint、deploy、release
データベース	db.just	migrate、seed、reset、dump、restore
インフラストラクチャ	infra.just	plan、apply、destroy
Kubernetes	k8s.just	apply、diff、rollback、logs
ドキュメント	docs.just	build、serve、publish

単一の関心事だけを扱うプロジェクト（ビルド／テスト／リンター／フォーマッターのみの Go／Rust プロジェクトなど）では、dev.just を1つだけ使用し、ルートは引き続き薄く保ちます。モジュールは自己完結させます。独自の変数と _default を持たせ、モジュール間でレシピに依存しないようにしてください。

テンプレートとリファレンス

• テンプレート（ルート＋モジュール、コピーして調整）：Templates.md
• just 言語リファレンス（変数、引数、依存関係、条件分岐、属性、関数、インストール）：References/Syntax.md
• プロジェクトの種類別レシピの断片（Terraform、Go、Python、Docker、Azure、Ansible）：References/Patterns.md
• Makefile から just への移行ガイド：References/MakeMigration.md

リント

Justfile または .just モジュールを作成または編集した後は必ず、構造リントを実行し、すべての失敗を修正してください。

bun Tools/lint.ts <project-dir>

このリントでは、ファイル名、3 行のヘッダー、先頭のレシピが _default であること、--unsorted／--list-submodules フラグ、env_var_or_default() の使用、すべてのレシピへのドキュメントコメント、明示的なモジュールのインポートパス、セクションの順序をチェックします。FAIL はすべてバグです。問題がなくなるまで修正して再実行してください。このリントでは、関心事に基づいた命名、自己完結性、標準的な語彙の使用は判断できません。目視で確認してください（Workflows/CheckJustfile.md を参照）。

注意点

• 各レシピ行はデフォルトで別々のシェルで実行されます。1 行目で cd foo、次の行で ls を実行すると、ls は元のディレクトリで実行されます。複数行のスクリプトにはシバン付きレシピを使用してください。
• set dotenv-load は実行したディレクトリではなく、justfile のあるディレクトリから .env を読み込みます。サブディレクトリから just を実行すると、親ディレクトリの .env が読み込まれます。上書きするには set dotenv-path を使用してください。
• バッククォート内の変数は、呼び出しのたびに解析時に評価されます。git_hash := \git rev-parse HEAD`は、無関係なレシピを実行する場合でもjust` を呼び出すたびに git を実行します。大規模なリポジトリでは遅くなるため、全体で必要ない場合はレシピ内に移動してください。
• レシピの引数は自動的にシェル用に引用されません。just deploy "my server" は 2 つの引数を渡します。"$@" とともに set positional-arguments を使用するか、{{quote(target)}} で囲んでください。
• set shell := ["bash", "-c"] は set -euo pipefail の動作を損ないます。各行が個別の -c 呼び出しになるため、pipefail はその行内でのみ有効です。エラー時に正しく即時終了するスクリプトには、シバン付きレシピを使用してください。
• just --list は _ で始まるレシピと [private] レシピを表示しませんが、これらは引き続き呼び出せます。これは見えにくくするだけで、アクセス制御ではありません。
• クロスプラットフォームの [macos]／[linux] 属性は、対象外の OS ではレシピをエラーなくスキップします。[linux]／[macos] のバリアントしかないときに Windows で just install を実行すると、エラーなしで 0 を返しますが、成功したように見えます。
• リントで検証されるのは構造であり、動作ではありません。すべてのチェックに合格したレシピでも、誤ったコマンドを実行することがあります。展開結果を確認するには just --dry-run <recipe> を実行してください。