justfile-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Justfile Expert

Justfile 专家

Expert knowledge for Just command runner, recipe development, and task automation with focus on cross-platform compatibility and project standardization.

精通Just命令运行器、Recipe开发和任务自动化，重点关注跨平台兼容性与项目标准化。

When to Use This Skill

何时使用该技能

Use this skill when...	Use alternative when...
Creating/editing justfiles for task automation	Need build system with incremental compilation → Make
Writing cross-platform project commands	Need tool version management bundled → mise tasks
Adding shebang recipes (Python, Node, Ruby, etc.)	Already using mise for all project tooling
Configuring dotenv loading and settings	Simple one-off shell scripts → Bash directly
Setting up CI/CD with just recipes	Project already has extensive Makefile
Standardizing recipes across projects	Need Docker-specific workflows → docker-compose

适用场景	替代方案场景
为任务自动化创建/编辑justfiles	需要支持增量编译的构建系统 → 使用Make
编写跨平台项目命令	需要捆绑工具版本管理 → 使用mise tasks
添加shebang Recipe（Python、Node、Ruby等）	已使用mise管理所有项目工具
配置dotenv加载与设置	简单一次性Shell脚本 → 直接使用Bash
使用just Recipe搭建CI/CD	项目已有完善的Makefile
跨项目标准化Recipe	需要Docker专属工作流 → 使用docker-compose

Core Expertise

核心能力

Command Runner Mastery

Justfile syntax and recipe structure
Cross-platform task automation (Linux, macOS, Windows)
Parameter handling and argument forwarding
Module organization for large projects

Recipe Development Excellence

Recipe patterns for common operations
Dependency management between recipes
Shebang recipes for complex logic
Environment variable integration

Project Standardization

Golden template with standard naming and section structure
Self-documenting project operations
Portable patterns across projects
Integration with CI/CD pipelines

命令运行器精通

Justfile语法与Recipe结构
跨平台任务自动化（Linux、macOS、Windows）
参数处理与参数转发
大型项目的模块组织

Recipe开发进阶

通用操作的Recipe模式
Recipe间的依赖管理
复杂逻辑的shebang Recipe
环境变量集成

项目标准化

含标准命名与章节结构的黄金模板
自文档化的项目操作
跨项目可移植的模式
与CI/CD流水线的集成

Recipe Naming Conventions

Recipe命名规范

Rule	Pattern	Examples
Hyphen-separated	`word-word`	`test-unit` , `format-check`
Verb-first (actions)	`verb-object`	`lint` , `build` , `clean`
Noun-first (categories)	`noun-verb`	`db-migrate` , `docs-serve`
Private prefix	`_name`	`_generate-secrets` , `_setup`
`-check` suffix	Read-only verification	`format-check`
`-fix` suffix	Auto-correction	`lint-fix` , `check-fix`
`-watch` suffix	Watch mode	`test-watch` , `docs-watch`
Modifiers after base	`base-modifier`	`build-release` (not `release-build` )

规则	格式	示例
连字符分隔	`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` ）

Semantic Workflow Recipes

语义化工作流Recipe

Standard composite recipes with defined meanings:

Recipe	Composition	Purpose
`check`	`format-check` + `lint` + `typecheck`	Code quality only, no tests
`pre-commit`	`format-check` + `lint` + `typecheck` + `test-unit`	Fast, non-mutating validation
`ci`	`check` + `test-coverage` + `build`	Full CI simulation
`clean`	Remove build artifacts	Partial cleanup
`clean-all`	`clean` + remove deps/caches	Full cleanup

just

undefined

具有明确含义的标准组合Recipe：

Recipe	组合	用途
`check`	`format-check` + `lint` + `typecheck`	仅代码质量检查，不包含测试
`pre-commit`	`format-check` + `lint` + `typecheck` + `test-unit`	快速、非破坏性的校验
`ci`	`check` + `test-coverage` + `build`	完整CI模拟
`clean`	删除构建产物	部分清理
`clean-all`	`clean` + 删除依赖/缓存	完全清理

just

undefined

Composite: code quality only (no tests)

check: format-check lint typecheck

Pre-commit checks (fast, non-mutating)

pre-commit: format-check lint typecheck test-unit @echo "Pre-commit checks passed"

Full CI simulation

ci: check test-coverage build @echo "CI simulation passed"

Clean build artifacts

clean: rm -rf dist build .next

Clean everything including deps

clean-all: clean rm -rf node_modules .venv pycache

undefined

clean-all: clean rm -rf node_modules .venv pycache

undefined

Key Capabilities

关键功能

Recipe Parameters

Required parameters:
```
recipe param:
```
- must be provided
Default values:
```
recipe param="default":
```
- optional with fallback
Variadic
+
:
```
recipe +FILES:
```
- one or more arguments
Variadic
*
:
```
recipe *FLAGS:
```
- zero or more arguments
Environment export:
```
recipe $VAR:
```
- parameter as env var

Settings Configuration

set dotenv-load
: Load
```
.env
```
file automatically
set positional-arguments
: Enable
```
$1
```
,
```
$2
```
syntax
set export
: Export all variables as env vars
set shell
: Custom shell interpreter
set quiet
: Suppress command echoing

Recipe Attributes

[private]
: Hide from
```
--list
```
output
[no-cd]
: Don't change directory
[no-exit-message]
: Suppress exit messages
[unix]
/ [windows]
/ [linux]
/ [macos]
: Platform-specific recipes
[positional-arguments]
: Per-recipe positional args
[confirm]
/ [confirm("message")]
: Require confirmation before running
[group: "name"]
: Group recipes in
```
--list
```
output
[working-directory: "path"]
: Run in specific directory

Module System

mod name
: Declare submodule
mod name 'path'
: Custom module path
Invocation:
```
just module::recipe
```
or
```
just module recipe
```

Recipe参数

必填参数：
```
recipe param:
```
- 必须传入
默认值：
```
recipe param="default":
```
- 可选，含回退值
可变参数
+
：
```
recipe +FILES:
```
- 一个或多个参数
可变参数
*
：
```
recipe *FLAGS:
```
- 零个或多个参数
环境变量导出：
```
recipe $VAR:
```
- 参数作为环境变量

设置配置

set dotenv-load
：自动加载
```
.env
```
文件
set positional-arguments
：启用
```
$1
```
,
```
$2
```
语法
set export
：导出所有变量为环境变量
set shell
：自定义Shell解释器
set quiet
：抑制命令回显

Recipe属性

[private]
：在
```
--list
```
输出中隐藏
[no-cd]
：不切换目录
[no-exit-message]
：抑制退出提示
[unix]
/ [windows]
/ [linux]
/ [macos]
：特定平台的Recipe
[positional-arguments]
：针对单个Recipe的位置参数
[confirm]
/ [confirm("message")]
：运行前需确认
[group: "name"]
：在
```
--list
```
输出中分组显示Recipe
[working-directory: "path"]
：在指定目录运行

模块系统

mod name
：声明子模块
mod name 'path'
：自定义模块路径
调用方式：
```
just module::recipe
```
或
```
just module recipe
```

Essential Syntax

基础语法

Basic Recipe Structure

just

undefined

基础Recipe结构

just

undefined

Comment describes the recipe

recipe-name: command1 command2


**Recipe with Parameters**
```just
build target:
    @echo "Building {{target}}..."
    cd {{target}} && make

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

Recipe Dependencies

just

default: build test

build: _setup
    cargo build --release

_setup:
    @echo "Setting up..."

Variables and Interpolation

just

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

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

Conditional Recipes

just

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

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

recipe-name: command1 command2


**带参数的Recipe**
```just
build target:
    @echo "Building {{target}}..."
    cd {{target}} && make

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

Recipe依赖

just

default: build test

build: _setup
    cargo build --release

_setup:
    @echo "Setting up..."

变量与插值

just

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

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

条件Recipe

just

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

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

Standard Recipes

标准Recipe

Every project should provide these standard recipes, organized by section:

just

undefined

每个项目都应提供以下标准Recipe，按章节组织：

just

undefined

Justfile - Project task runner

Run

just

just help

to see available recipes

Run

just

just help

to see available recipes

set dotenv-load set positional-arguments

Default recipe - show help

default: @just --list

Show available recipes with descriptions

help: @just --list --unsorted

####################

help: @just --list --unsorted

####################

Development

####################

Start development environment

dev: # bun run dev / uv run uvicorn app:app --reload / skaffold dev

Build for production

build: # bun run build / cargo build --release / docker build

Clean build artifacts

clean: # rm -rf dist build .next

####################

clean: # rm -rf dist build .next

####################

Code Quality

####################

Run linter (read-only)

lint *args: # bun run lint / uv run ruff check {{args}}

Auto-fix lint issues

lint-fix: # bun run lint:fix / uv run ruff check --fix .

Format code (mutating)

format *args: # bun run format / uv run ruff format {{args}}

Check formatting without modifying (non-mutating)

format-check *args: # bun run format:check / uv run ruff format --check {{args}}

Type checking

typecheck: # bunx tsc --noEmit / uv run basedpyright

####################

typecheck: # bunx tsc --noEmit / uv run basedpyright

####################

Testing

####################

Run all tests

test *args: # bun test {{args}} / uv run pytest {{args}}

Run unit tests only

test-unit *args: # bun test --grep unit {{args}} / uv run pytest -m unit {{args}}

####################

test-unit *args: # bun test --grep unit {{args}} / uv run pytest -m unit {{args}}

####################

Workflows

####################

Composite: code quality (no tests)

check: format-check lint typecheck

Pre-commit checks (fast, non-mutating)

pre-commit: format-check lint typecheck test-unit @echo "Pre-commit checks passed"

Full CI simulation

ci: check test-coverage build @echo "CI simulation passed"

undefined

ci: check test-coverage build @echo "CI simulation passed"

undefined

Section Structure

章节结构

Organize recipes into these standard sections:

Section	Recipes	Purpose
Metadata	`default` , `help`	Discovery and navigation
Development	`dev` , `build` , `clean` , `start` , `stop`	Core dev cycle
Code Quality	`lint` , `lint-fix` , `format` , `format-check` , `typecheck`	Code standards
Testing	`test` , `test-unit` , `test-integration` , `test-e2e` , `test-watch`	Test tiers
Workflows	`check` , `pre-commit` , `ci`	Composite operations
Dependencies	`install` , `update`	Package management
Database	`db-migrate` , `db-seed` , `db-reset`	Data operations
Kubernetes	`skaffold` , `dev-k8s`	Container orchestration
Documentation	`docs` , `docs-serve`	Project docs

Use

####################

comment blocks as section dividers for readability.

按以下标准章节组织Recipe：

章节	Recipe	用途
元数据	`default` , `help`	发现与导航
开发	`dev` , `build` , `clean` , `start` , `stop`	核心开发周期
代码质量	`lint` , `lint-fix` , `format` , `format-check` , `typecheck`	代码标准
测试	`test` , `test-unit` , `test-integration` , `test-e2e` , `test-watch`	测试层级
工作流	`check` , `pre-commit` , `ci`	组合操作
依赖	`install` , `update`	包管理
数据库	`db-migrate` , `db-seed` , `db-reset`	数据操作
Kubernetes	`skaffold` , `dev-k8s`	容器编排
文档	`docs` , `docs-serve`	项目文档

使用

####################

注释块作为章节分隔符以提升可读性。

Common Patterns

常见模式

Setup/Bootstrap Recipe

just

undefined

初始化/引导Recipe

just

undefined

Initial project setup

setup: #!/usr/bin/env bash set -euo pipefail echo "Installing dependencies..." uv sync echo "Setting up pre-commit..." pre-commit install echo "Done!"


**Docker Integration**
```just

setup: #!/usr/bin/env bash set -euo pipefail echo "Installing dependencies..." uv sync echo "Setting up pre-commit..." pre-commit install echo "Done!"


**Docker集成**
```just

Build container image

docker-build tag="latest": docker build -t {{project}}:{{tag}} .

Run container

docker-run tag="latest" *args: docker run --rm -it {{project}}:{{tag}} {{args}}

Push to registry

docker-push tag="latest": docker push {{registry}}/{{project}}:{{tag}}


**Database Operations**
```just

docker-push tag="latest": docker push {{registry}}/{{project}}:{{tag}}


**数据库操作**
```just

Run database migrations

db-migrate: uv run alembic upgrade head

Create new migration

db-revision message: uv run alembic revision --autogenerate -m "{{message}}"

Reset database

db-reset: uv run alembic downgrade base uv run alembic upgrade head


**CI/CD Recipes**
```just

db-reset: uv run alembic downgrade base uv run alembic upgrade head


**CI/CD Recipe**
```just

Full CI check (lint + test + build)

ci: lint test build @echo "CI passed!"

Release workflow

release version: git tag -a "v{{version}}" -m "Release {{version}}" git push origin "v{{version}}"

undefined

release version: git tag -a "v{{version}}" -m "Release {{version}}" git push origin "v{{version}}"

undefined

MCP Integration (just-mcp)

MCP集成（just-mcp）

The

just-mcp

MCP server enables AI assistants to discover and execute justfile recipes through the Model Context Protocol, reducing context waste since the AI doesn't need to read the full justfile.

Installation:

bash

undefined

just-mcp

MCP服务器允许AI助手通过模型上下文协议（Model Context Protocol）发现并执行justfile Recipe，减少上下文损耗，因为AI无需读取完整的justfile。

安装方式：

bash

undefined

Via npm

npx just-mcp --stdio

Via pip/uvx

uvx just-mcp --stdio

Via cargo

cargo install just-mcp


**Claude Desktop configuration (`.claude/mcp.json`):**
```json
{
  "mcpServers": {
    "just-mcp": {
      "command": "npx",
      "args": ["-y", "just-mcp", "--stdio"]
    }
  }
}

Available MCP Tools:

```
list_recipes
```
- Discover all recipes and parameters
```
run_recipe
```
- Execute a recipe with arguments
```
get_recipe_info
```
- Get detailed recipe documentation
```
validate_justfile
```
- Check for syntax errors

cargo install just-mcp


**Claude桌面端配置（`.claude/mcp.json`）：**
```json
{
  "mcpServers": {
    "just-mcp": {
      "command": "npx",
      "args": ["-y", "just-mcp", "--stdio"]
    }
  }
}

可用MCP工具：

```
list_recipes
```
- 发现所有Recipe与参数
```
run_recipe
```
- 传入参数执行Recipe
```
get_recipe_info
```
- 获取Recipe的详细文档
```
validate_justfile
```
- 检查语法错误

Agentic Optimizations

智能优化命令

Context	Command
List all recipes	`just --list` or `just -l`
Dry run (preview)	`just --dry-run recipe`
Show variables	`just --evaluate`
JSON recipe list	`just --dump --dump-format json`
Verbose execution	`just --verbose recipe`
Specific justfile	`just --justfile path recipe`
Working directory	`just --working-directory path recipe`
Choose interactively	`just --choose`

场景	命令
列出所有Recipe	`just --list` 或 `just -l`
空运行（预览）	`just --dry-run recipe`
显示变量	`just --evaluate`
JSON格式Recipe列表	`just --dump --dump-format json`
详细执行日志	`just --verbose recipe`
指定justfile	`just --justfile path recipe`
指定工作目录	`just --working-directory path recipe`
交互式选择	`just --choose`

Best Practices

最佳实践

Recipe Development Workflow

Name clearly: Use descriptive, verb-based names (
```
build
```
,
```
test
```
,
```
deploy
```
)
Document always: Add comment before each recipe
Use defaults: Provide sensible default parameter values
Group logically: Organize with section comments
Hide internals: Mark helper recipes as
```
[private]
```
Test portability: Verify on all target platforms

Critical Guidelines

Always provide
```
default
```
recipe pointing to help
Use
```
@
```
prefix to suppress command echo when appropriate
Use shebang recipes for multi-line logic
Prefer
```
set dotenv-load
```
for configuration
Use modules for large projects (>20 recipes)
Include variadic
```
*args
```
for passthrough flexibility
Quote all variables in shell commands

Recipe开发流程

命名清晰：使用描述性的动词式名称（
```
build
```
,
```
test
```
,
```
deploy
```
）
始终文档化：每个Recipe前添加注释
使用默认值：为参数提供合理的默认值
逻辑分组：使用章节注释组织Recipe
隐藏内部实现：将辅助Recipe标记为
```
[private]
```
测试可移植性：在所有目标平台上验证

关键准则

始终提供指向帮助的
```
default
```
Recipe
适当使用
```
@
```
前缀抑制命令回显
对于多行逻辑使用shebang Recipe
优先使用
```
set dotenv-load
```
进行配置
大型项目（超过20个Recipe）使用模块
包含可变参数
```
*args
```
以支持灵活的参数传递
在Shell命令中为所有变量添加引号

Comparison with Alternatives

与替代方案的对比

Feature	Just	Make	mise tasks
Syntax	Simple, clear	Complex, tabs required	YAML
Dependencies	Built-in	Built-in	Manual
Parameters	Full support	Limited	Full support
Cross-platform	Excellent	Good	Excellent
Tool versions	No	No	Yes
Error messages	Clear	Cryptic	Clear
Installation	Single binary	Pre-installed	Requires mise

When to use Just:

Cross-project standard recipes
Simple, readable task automation
No tool version management needed

When to use mise tasks:

Project-specific with tool version pinning
Already using mise for tool management

When to use Make:

Legacy projects with existing Makefiles
Build systems requiring incremental compilation

For the golden justfile template, detailed syntax reference, advanced patterns, and troubleshooting, see REFERENCE.md.

特性	Just	Make	mise tasks
语法	简洁清晰	复杂，要求使用制表符	YAML
依赖	内置	内置	手动管理
参数支持	完整	有限	完整
跨平台性	优秀	良好	优秀
工具版本管理	无	无	有
错误提示	清晰	晦涩	清晰
安装方式	单二进制文件	预安装	需要安装mise

何时使用Just：

跨项目的标准Recipe
简洁、易读的任务自动化
无需工具版本管理

何时使用mise tasks：

带工具版本固定的项目专属场景
已使用mise进行工具管理

何时使用Make：

已有Makefile的遗留项目
需要增量编译的构建系统

如需获取golden justfile模板、详细语法参考、进阶模式与故障排除内容，请查看REFERENCE.md。

justfile-expert

Original

Translation

Justfile Expert

Justfile 专家

When to Use This Skill

何时使用该技能

Core Expertise

核心能力

Recipe Naming Conventions

Recipe命名规范

Semantic Workflow Recipes

语义化工作流Recipe

Composite: code quality only (no tests)

Composite: code quality only (no tests)

Pre-commit checks (fast, non-mutating)

Pre-commit checks (fast, non-mutating)

Full CI simulation

Full CI simulation

Clean build artifacts

Clean build artifacts

Clean everything including deps

Clean everything including deps

Key Capabilities

关键功能

Essential Syntax

基础语法

Comment describes the recipe

Comment describes the recipe

Standard Recipes

标准Recipe

Justfile - Project task runner

Justfile - Project task runner

Run just or just help to see available recipes

Run just or just help to see available recipes

Default recipe - show help

Default recipe - show help

Show available recipes with descriptions

Show available recipes with descriptions

Development

Development

Start development environment

Start development environment

Build for production

Build for production

Clean build artifacts

Clean build artifacts

Code Quality

Code Quality

Run linter (read-only)

Run linter (read-only)

Auto-fix lint issues

Auto-fix lint issues

Format code (mutating)

Format code (mutating)

Check formatting without modifying (non-mutating)

Check formatting without modifying (non-mutating)

Type checking

Type checking

Testing

Testing

Run all tests

Run all tests

Run unit tests only

Run unit tests only

Workflows

Workflows

Composite: code quality (no tests)

Composite: code quality (no tests)

Pre-commit checks (fast, non-mutating)

Pre-commit checks (fast, non-mutating)

Full CI simulation

Full CI simulation

Section Structure

章节结构

Common Patterns

常见模式

Initial project setup

Initial project setup

Build container image

Run
`just`
or
`just help`
to see available recipes

Run
`just`
or
`just help`
to see available recipes