justfile-expert

Justfile 专家

Just 命令运行器、配方开发和任务自动化方面的专业知识，侧重于跨平台兼容性和项目标准化。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用替代方案……
为任务自动化创建/编辑 justfile	需要支持增量编译的构建系统 → Make
编写跨平台项目命令	需要捆绑工具版本管理 → mise tasks
添加 shebang 配方（Python、Node、Ruby 等）	已使用 mise 管理所有项目工具
配置 dotenv 加载和设置	编写 shell 本身（管道、陷阱、参数解析）→ shell-expert
使用 just 配方设置 CI/CD	项目已有大量 Makefile
在多个项目中统一配方	暴露用于批量冒烟测试的模块 → cli-smoke-recipes

核心专长

命令运行器精通

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

配方开发能力

• 常见操作的配方模式
• 配方间的依赖管理
• 用于复杂逻辑的 Shebang 配方
• 环境变量集成

项目标准化

• 包含标准命名和章节结构的黄金模板
• 项目操作的自文档化
• 可在多个项目间移植的模式
• 与 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 时，请打开 references/standard-recipes.md，了解语义组合（check、pre-commit、ci、clean、clean-all）、标准配方集和章节结构。

关键功能

参数形式、设置、配方属性（[doc]、[private]、[group]、[confirm]、平台）以及模块系统，包括 set fallback 不会被模块继承这一点：references/key-capabilities.md。

基本语法

基本配方结构

# Comment describes the recipe
recipe-name:
    command1
    command2

带参数的配方

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

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

插值不带引号——任何可能包含空格的内容都要加引号

{{...}} 会在 shell 解析之前将原始文本插入配方主体，因此，包含空格或引号的值会被按词拆分。这对上面的 *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

外层 shell 消耗了引号（连同其中的撇号），于是 the / subject's / face 被作为三个独立的 argv 条目传入。为可能包含空格的参数命名，并通过 quote() 处理，这会生成经过正确 shell 转义的字面量：

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

quote() 可以处理内嵌空格、'、" 和 $。让 {{ARGS}} 保持不加引号——这样多个末尾标志才能展开为单独的词；同时也要接受其推论：单个透传标志的值不能包含空格。如果可能包含空格，也将它提升为命名参数。

--list 显示的内容只有一行，而且不是你的注释块

just --list 会为每个配方显示一条描述。如果没有 [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

配方的注释块超过一行时，立即添加 [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）

如需让 AI 客户端通过 MCP 列出并运行配方，而不是读取 justfile，请参阅 references/mcp-integration.md。

Agentic 优化

使用场景	命令
列出所有配方	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 会读取的内容：一行注释就够了；更长的内容需要使用 [doc("...")]，否则列表中只会显示代码块的最后一行
3. 使用默认值：为参数提供合理的默认值
4. 逻辑分组：使用文件的分节注释、使用 [group("name")] 对列表分组——配方超过 20 个左右时，扁平的 --list 就不再便于浏览
5. 隐藏内部实现：将辅助配方标记为 [private]
6. 测试可移植性：在所有目标平台上验证

关键指南

• 始终提供指向帮助信息的 default 配方
• 适当时使用 @ 前缀来抑制命令回显
• 多行逻辑使用 shebang 配方
• 配置优先使用 set dotenv-load
• 大型项目（配方超过 20 个）使用模块
• 如果配方注释块的最后一行单独看不像描述，就为配方添加 [doc("...")]——--list 只会显示该行（参见上文“--list 显示的内容”）。查找此类配方： python3 "${CLAUDE_PLUGIN_ROOT}/scripts/just-recipe-help.py" --audit
• 使用可变参数 *args 以便灵活透传
• 在 shell 命令中为所有变量加引号——{{...}} 会以不带引号的形式插入，因此任何可能包含空格的参数都要用 quote() 包裹（参见上文“插值不带引号”）；仅当透传标志不含空格时，才可以直接使用 {{args}}

与其他方案的比较

功能表以及何时选择 Just、Make 或 mise 任务：references/comparison.md。

黄金标准 justfile 模板、详细语法参考、高级模式和故障排查，请参阅 REFERENCE.md。