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 です。どちらも完全なゲート（フォーマット／リンター → 型チェック → テスト → カバレッジ）を実行し、出力を簡潔にまとめます。各ステップが成功すると ✓ <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 を参照してください。

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

• 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 のファイルターゲット依存関係の追跡）
• 削除：ユーザーに確認してから、古いファイルを削除します

既存の justfile も確認します。すでに存在する場合は、変更案の差分をユーザーに提示し、上書きする前に明示的な許可を待ってください。

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 dist --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 スクリプトと同じ動作です。レシピでより柔軟な動作が必要な場合は、シェルフラグを弱めるのではなく、- 行接頭辞を使って単一のコマンドのエラーを無視します。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 を使用します。設定 § 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> のみを出力し、 失敗時に限りツールの出力全体（file:line を含む）を表示します。カバレッジはゲート内で実行され、 成功時はその表が出力されず、しきい値を下回ったときは全体が表示されます。（これは以前の 「トークン節約のためカバレッジを省略する」という助言に代わるものです。カバレッジはゲートに 含め、トークンコストへの対処は省略ではなくコンパクト化に任せてください。）

ゲートを構成する個々のレシピでは、レシピのエコーを抑えるために @ プレフィックスを使い、 バナー／監査／資金提供に関するノイズを抑えるために npm に --silent --no-audit --no-fund を渡してください。

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

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

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

## 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 ワークフロー — 既存の検証ステップを just ci に切り替え、ローカルと CI で 同一のゲートを実行するようにしてください。このスキルではパイプラインの設計は行いません。 検証ステップの切り替えのみを行います（例：lint／test／coverage の個別ステップを 単一の run: just ci に置き換える）。Actions のスニペットは references/agent-build.md を 参照してください。

README.md — 「Development」または「Getting Started」セクションを追加してください。

## 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+）： パラメーターを位置引数ではなく CLI オプションとして 公開するには [arg()] を使います。プロンプトで人が実行するレシピに最適です。

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

使用例：just dist --target x86_64 --release。生成されたヘルプを確認するには just --usage dist を実行してください。

スクリプトブロック（[script]）： shebang レシピよりもすっきりしており、 1行ごとに再評価させたくないシェル制御フローを本体に含む場合に適しています（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"])

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

組み込みのカラー定数： 定義なしでグローバルに使用できます — 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 には組み込みの監視フラグがありません。マニュアルでは、 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 ゲートは 変更のたびに行う検証に使います。詳細は ファイル変更時にレシピを再実行する を参照してください。

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

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

shebang レシピ（複数行スクリプト。set unstable は不要）：

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

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

アンチパターン

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

対応しないこと

• CI パイプラインや GitHub Actions のワークフローをゼロから設計しません。ただし、既存の CI 検証ステップを 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 で関連する最小バージョンを指定してください