justfile

justfile

あらゆるプロジェクトに適した、慣用的な justfile を生成します。Makefile や場当たり的なシェルスクリプトを、すっきりと見つけやすいコマンドランナーに置き換えます。

Make より just を選ぶ理由

• .PHONY の小細工は不要です。すべてのレシピはファイルターゲットではなくコマンドです
• タブによるインデントの問題はありません。任意の空白文字を使用できます
• パラメーター、dotenv の読み込み、OS の検出、モジュールを標準でサポートします
• just --list とドキュメントコメントで、コマンドをすぐに見つけられます
• シバンレシピを使えば、Python／Ruby／Node をインラインで記述できます

公式の機能解説（よく使われる機能、justfile を本当に便利にする特殊なユースケース、章への詳細なリンク付きインデックス）については、 Just Programmer's Manualに基づく references/manual.mdを参照してください。

デフォルト：標準コマンドを 1 つにする

このスキルが生成するすべての justfile には、エージェントが変更のたびに実行するコマンドを 1 つ用意します。just build と、その自動修正なしの CI 用コマンド just ci です。build はデフォルトのレシピです。どちらもすべてのゲート（フォーマット／Lint → 型チェック → テスト → カバレッジ）を実行し、出力を簡潔にまとめます。各ステップの成功時は ✓ <step> を表示し、失敗時のみ、ファイル名と行番号を含むツールの出力全体を表示します。

これは、ユーザーが明示的に異なる構成を求めない限り、生成するすべての justfile のデフォルトの方針です。エージェントが一貫したコマンドでより速く収束し、合否が決定的になり、エラーだけを簡潔に表示できるという根拠（出典付き）、完全なレシピテンプレート、_gate ヘルパー、必須の AGENTS.md／CI の更新方法は、すべて references/agent-build.mdに記載されています。justfile を作成する前に、必ずお読みください。

build ＝ ゲート（自動修正あり）。ci ＝ ゲート（自動修正なし）。成果物をコンパイルまたはパッケージ化するレシピには、dist（または release）という名前を付けます。ゲート用に予約されている build は決して使わないでください。

手順

1. プロジェクトを検出する

プロジェクトのルートで、エコシステムを示すファイルを確認します。

ファイル	エコシステム	参照先
Cargo.toml	Rust	references/rust.md
pyproject.toml、setup.py、uv.lock	Python	references/python.md
package.json	TypeScript/JS	references/typescript.md
go.mod	Go	references/go.md
Gemfile	Ruby	references/ruby.md

言語固有のレシピについては、該当する参照ファイルを読んでください。

複数のファイルが見つかった場合（Rust のバックエンドと TypeScript のフロントエンドなど）、パターンを組み合わせます。本格的なモノレポではモジュール（mod frontend、mod backend）を使います。ルートの build ゲートが各モジュールのゲートを集約し、just build が引き続き「すべてを検証する」コマンドになるためです。モジュール／インポートの構成パターン全体と、mod より import を選ぶ場面については、references/composition.mdを参照してください。

複数エコシステムでの命名： Tauri のように複数の言語（Rust と TypeScript など）を使うプロジェクトでは、重複する処理を区別できるよう、エコシステムの接尾辞を付けます。

• test-rust、test-ts（実行内容が分からなくなる汎用的な test は使わない）
• fmt-rust、fmt-ts（各エコシステムのフォーマッター）
• lint-rust（clippy）、lint-ts（eslint／biome）
• 集約レシピでは組み合わせます：test: test-rust test-ts、fmt: fmt-rust fmt-ts
• 両方のエコシステムにまたがる共通レシピには、通常の名前を使います：dev、build、clean

2. 既存のビルドファイルを確認する

Makefile、Taskfile.yml、Rakefile、package.json のスクリプト、または scripts/ や bin/ 内のシェルスクリプトを探します。見つかった場合は、次のようにします。

• 移行：既存のターゲットを just のレシピに変換します（下の移行表を参照）
• 維持：just では置き換えられない複雑なロジックはそのまま残します（実際のビルド成果物に対する Make のファイルターゲット依存関係の追跡など）
• 削除：ユーザーに確認してから、古いファイルを削除します

3. justfile を作成する

プロジェクトのルートに justfile を配置します。次の規約に従ってください。

構成の順序：

1. 設定（set dotenv-load、set shell）
2. 変数（バージョン、バイナリ名など）
3. デフォルトレシピ — default: build（標準のゲート）。ユーザーがデフォルトゲートを明示的に不要としている場合に限り、@just --list を使用します。
4. ゲート：build（自動修正あり）＋ ci（自動修正なし）＋ _gate ヘルパー — references/agent-build.md を参照してください
5. ゲートを構成する細分化されたレシピ：test、lint、fmt、typecheck、coverage
6. 用途別のその他のレシピ：run/dev、dist/release、docs
7. ユーティリティレシピ（clean など）
8. 非公開ヘルパー（_ で始まる名前、または [private]）

レシピの命名：

• ケバブケースを使用します：test-coverage、build-release
• 動詞を使用します：build、test、lint、deploy（builder、tests ではありません）
• ファイルが大きい場合は、接頭辞でグループ化します：db-migrate、db-seed、db-reset
• デフォルトレシピには、最も一般的な操作または --list を指定します

ドキュメントコメント： 公開レシピにはすべて、直前の行にコメントを付けます。これは just --list に表示されます。

# Run the full test suite
test *args:
    cargo test {{args}}

パラメーター：

• 省略可能な引数にはデフォルト値を使用します：test filter=""
• 引数をそのまま渡すには可変長引数を使用します：run *args
• +args（1 個以上必須）は控えめに使用します
• 使いやすい CLI フラグ（just build --target x86_64）には、[arg()] 属性を使用します（v1.46 以降。「Recipe argument flags」を参照してください）

エイリアス： 開発者が 1 日に何度も入力するレシピには、1 文字のエイリアスを追加します。レシピの直下の行に定義すると、just --list に正規の名前が先に表示されます。

# Run tests
test *args:
    cargo test {{args}}
alias t := test

すべてのレシピにエイリアスを作る必要はありません。頻繁に使うものだけにしてください。

常に含める設定：

set dotenv-load
set shell := ["bash", "-euo", "pipefail", "-c"]

-euo pipefail を指定すると、シェルレシピはエラー、未設定の変数、パイプの破損が発生したときに確実に失敗します。これは、適切に記述された bash スクリプトと同じ方針です。レシピでより緩やかな動作が必要な場合は、弱いシェルフラグを使うのではなく、1 つのコマンドのエラーを無視するために行頭に - を付けてください。Windows を対象にする場合や、bash に依存しないプロジェクトでは set shell の行を省略してください。ほとんどのレシピでは、デフォルトの /bin/sh で問題ありません。

一般的な機能については、set unstable は不要になりました。モジュール（just 1.31 以降で安定）、[script] 属性（1.44）、[arg()] フラグ（1.46）は、いずれも現在の just で使用できます。該当機能の安定化より前の just に対応する場合に限り、set unstable を追加してください。

dotenv の堅牢化： .env が存在しない場合、set dotenv-load は何もせず、エラーも出しません。プロジェクトで .env（DB URL、API キーなど）が本当に必須の場合は、失敗を明示させ、空の変数のまま実行せずにすぐ失敗するようにしてください。

set dotenv-load
set dotenv-required          # error if no dotenv file is found

# Pick ONE of the following (omit both to load ./.env):
set dotenv-path := ".env.local"     # explicit path (relative to justfile), OR…
# set dotenv-filename := ".env.dev" # …a filename to search for up the tree

dotenv-required を使うと、環境ファイルがない場合に何もせず続行するのではなく、明確なエラーになります。これは「すぐに、明確に失敗させる」という方針です。特定のファイルを指定するには dotenv-path を使用し、just がツリーを検索する際のファイル名を変更するには dotenv-filename を使用してください。Settings § dotenv を参照してください。

ツールの依存関係 — require()

レシピが標準のシステムコマンドではないツールに依存する場合、justfile の先頭で宣言して、ツールがないときに just --evaluate がすぐ失敗するようにしてください。

# https://github.com/jqlang/jq
jq := require("jq")

# https://github.com/casey/just (yes, just itself)
just := require("just")

解決されたパスを使って呼び出すには {{ jq }} を使用するか、通常どおり jq を呼び出してください。require() によって評価時に存在がすでに確認されているため、どちらの形式でも動作します。URL のコメントはインストール方法のヒントも兼ねています。git、curl、言語ツールチェーンのような広く使われているツールには require() を使用せず、新しいマシンにない可能性があるものだけを宣言してください。

4. トークン最適化された出力（デフォルト、オプトイン不要）

build と ci は、すでにコンパクト化されている references/agent-build.md の _gate ヘルパーを通じて実行されます。各ステップの成功時には ✓ <step> のみを表示し、 失敗時に限り、ファイル名と行番号を含むツール出力全体を表示します。カバレッジはゲート内で実行されます。成功時にはその表は表示されず、しきい値を下回った場合はすべて表示されます。（これにより、「トークン節約のためカバレッジを省略する」という以前のアドバイスは置き換えられます。カバレッジはゲート内に含めたままにし、トークンコストへの対処は省略ではなくコンパクト化に任せてください。）

ゲートを構成する詳細なレシピには、引き続き次の内容を適用してください。

1. @ プレフィックスとツールフラグ。 レシピのエコーを抑制します。npm に --silent --no-audit --no-fund を渡して、バナー、監査、資金援助に関するノイズを減らします。

2. rtk へのアップグレード。 プロジェクトに rtk がインストールされている場合は、_gate 内の step 呼び出しを rtk test / rtk err に置き換えると、成功時の出力抑制に加えて、ツールごとのスマートなフィルタリングが適用されます。シェルラップのパターンと npm のスクリプト名に関する注意点については、references/rtk.md を参照してください。rtk は機能強化であり、必須ではありません。bash の step ヘルパーが、移植性のある最低限の選択肢です。

5. プロジェクトのドキュメントを更新する（必須）

レシピの生成は作業の半分にすぎません。エージェントに使うよう伝えなければ、コマンドを一元化する価値は失われます。justfile を作成したら、必ず次の両方を更新してください。完全なスニペットは references/agent-build.md にあります。

エージェントのコンテキストファイル（AGENTS.md、CLAUDE.md、GEMINI.md、.cursor/rules、またはハーネスが使用するファイル。存在しない場合は AGENTS.md を作成してください）— エージェントに必ず単一のコマンドを実行させ、失敗したら作業を完全に止めるよう指示するビルドセクションを追加または置き換えてください。

## Build & verification

This project has ONE canonical verification command. ALWAYS run it after
changing code, and treat a non-zero exit as a hard stop.

- `just build` — autofix, then lint, typecheck, test, and coverage. Run after
  every change.
- `just ci` — the same gate with no autofixes; exactly what CI runs.

Output is compacted: `✓ <step>` on success, full output (file:line) only on
failure. Don't invent ad-hoc test/lint commands — run `just build`.

CI ワークフロー — 既存の verify ステップを just ci に向け、ローカルと CI で同じゲートを実行します。このスキルではパイプラインを設計せず、verify ステップの向き先だけを変更します（例：個別の lint／test／coverage ステップを単一の run: just ci に置き換えます）。Actions のスニペットについては references/agent-build.md を参照してください。

README.md — 「開発」または「はじめに」セクションを追加してください。

## Development

### Prerequisites
- [just](https://github.com/casey/just) — `brew install just` / `cargo install just`

### Quick Start
```bash
just install   # Install dependencies
just test      # Run tests
just           # See all available commands

Don't duplicate the full recipe list — `just --list` is self-documenting.

## Makefile Migration Table

| Makefile | justfile |
|----------|----------|
| `.PHONY: target` | (not needed) |
| `$(VAR)` | `{{var}}` |
| `$(shell cmd)` | `` `cmd` `` |
| `-include .env` | `set dotenv-load` |
| `ifeq ($(OS),Darwin)` | `if os() == "macos" { ... }` |
| `ifndef VAR` / `$(or ...)` | `env_var_or_default("VAR", "default")` |
| `make -C subdir` | `mod subdir` |
| `$(MAKE) target` | `just target` |
| `.DEFAULT_GOAL := help` | First recipe is default |
| `@cmd` (suppress echo) | `@cmd` (same) |
| Tab indentation | Any whitespace |
| `%:` pattern rules | Not applicable — just has no file targets |

## Key Syntax Reference

**Variables:**
```just
VERSION := "1.0.0"
GIT_HASH := `git rev-parse --short HEAD`
DB_URL := env_var_or_default("DATABASE_URL", "postgres://localhost/dev")
OPEN := if os() == "macos" { "open" } else { "xdg-open" }

レシピの属性：

[confirm("Deploy to production?")]
deploy: build test

[macos]
open-docs:
    open target/doc/index.html

[linux]
open-docs:
    xdg-open target/doc/index.html

[private]
_setup:
    mkdir -p tmp/

# Group recipes in `just --list` output
[group("checks")]
lint:
    cargo clippy

[group("checks")]
fmt:
    cargo fmt

# Multiple attributes — same line (comma-separated) or stacked
[group("dev"), no-cd]
status:
    git status

レシピの引数フラグ（v1.46+）： [arg()] を使うと、引数を位置引数ではなく CLI オプションとして公開できます。プロンプトで人が実行するレシピに最適です。

[arg("target", long, help="Build target architecture")]
[arg("release", long, value="true", help="Build in release mode")]
build target release="false":
    cargo build --target {{target}} {{ if release == "true" { "--release" } else { "" } }}

使い方：just build --target x86_64 --release。生成されたヘルプを確認するには just --usage build を実行します。

スクリプトブロック（[script]）： シェバン付きレシピより簡潔で、本文内のシェル制御フローを行ごとに再評価させたくない場合に推奨されます（just 1.44 以降で安定版。set unstable は不要です）。

[script("bash")]
deploy env:
    set -e
    case {{env}} in
        prod) URL="https://prod.example.com" ;;
        stage) URL="https://stage.example.com" ;;
        *) echo "unknown env: {{env}}"; exit 1 ;;
    esac
    curl -X POST "$URL/deploy"

[script("python3")]
analyze:
    import json
    print(json.load(open("results.json"))["total"])

クロスプラットフォームでの移植性を高め、本文全体をひとつのブロックとして実行するため、[script()] は #!/usr/bin/env によるシェバンより推奨されます。

組み込みカラー定数： 定義なしでグローバルに使用できます。RED、GREEN、YELLOW、BLUE、CYAN、MAGENTA に加え、リセット用の BOLD、UNDERLINE、NORMAL があります。複数のステップを含むレシピでステータスを出力するのに便利です。

@check:
    cargo check
    echo -e '{{ GREEN }}✓ check passed{{ NORMAL }}'

@fail-loudly:
    echo -e '{{ BOLD + RED }}deploy aborted{{ NORMAL }}'

すべてのレシピに色を散りばめないでください。複数ステップをまとめた処理の概要を示すステータス行に限定してください。

監視／開発ループ： just には組み込みの watch フラグがありません。マニュアルでは、監視対象のファイルが変更されるたびに watchexec でレシピを再実行する方法が紹介されています：watchexec just <recipe>。これはゲートに対する開発時の内側のループです。よく使う処理を dev レシピにまとめ、依存関係を宣言してください。

# https://github.com/watchexec/watchexec
watchexec := require("watchexec")

# Re-run the fast checks on every save (Ctrl-C to stop).
dev:
    watchexec just test

watchexec just test は日々の開発時の内側のループであり、正規の build ゲートは変更のたびに行う検証として維持します。ファイル変更時にレシピを再実行するを参照してください。

モジュール（モノレポ）： パターンの全容については、references/composition.md を参照してください。モジュールのゲートをルートの build に集約する方法と、mod と import の違いについて説明しています。

mod api        # looks for api/justfile or api.just
mod web
mod? local     # optional — no error if missing

# Usage: just api::test, just web::build

シェバン付きレシピ（複数行スクリプト。set unstable は不要）：

analyze:
    #!/usr/bin/env python3
    import json
    data = json.load(open("results.json"))
    print(f"Total: {len(data)}")

just ≥ 1.44 では、シェバンより [script("python3")] を推奨します（安定版であり、set unstable は不要です）。本文をひとつのブロックとして実行し、シェバンの移植性に関する問題を避けられます。

アンチパターン

• Make のファイルターゲットシステムを再現しないでください。just はコマンドランナーであり、ビルドシステムではありません
• 強い理由がない限り set positional-arguments を使わないでください。{{arg}} のほうが明確です
• シークレットを justfile に記述しないでください。dotenv または環境変数を使ってください
• 200 行の justfile を書かないでください。モジュール（mod）を使って関心ごとに分割してください
• CI パイプラインのステップを一つずつ重複させないでください。build／ci ゲートにまとめてください
• アーティファクト／コンパイル用レシピに build という名前を付けないでください。この名前はゲート用です。dist または release を使ってください

対応しないこと

• CI パイプラインや GitHub Actions ワークフローを一から設計すること。ただし、既存の CI verify ステップは just ci に向けてください（ステップ 5 を参照）
• Dockerfile やコンテナ設定を作成すること
• 実際のビルドシステム（cargo、webpack、go build）を置き換えること。just はそれらをラップします
• ユーザーに確認せずに既存の Makefile を削除すること

注意点

• just バイナリが PATH にない場合があります。レシピを生成する前に which just で確認してください
• シバンレシピをシステム間で移植可能にするには、明示的に #!/usr/bin/env を指定する必要があります
• dotenv-load はすべての環境変数をすべてのレシピに公開します。シークレットの多いプロジェクトでは使用を避けてください
• モジュールパスは作業ディレクトリではなく、justfile の場所を基準にします
• set positional-arguments を指定すると、レシピ内での $1 の動作が変わります。使用する場合は説明を記載してください
• require("tool") は評価時に検証します。解決済みのパス経由で呼び出すには {{ jq }} を使うか、jq を直接呼び出してください。どちらも、require によってツールの存在が確認された後であれば動作します
• [script()] は just 1.44 以降、モジュールは 1.31 以降、[arg()] は 1.46 以降で安定版です。現在の just では、いずれも set unstable は必要ありません。古い just を使う場合にのみ set unstable を追加し、これらに依存する場合は README で該当する最小バージョンを指定してください