justfile

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Justfile

Author and maintain Just task runners. House style matches this repo's root

justfile

minimum-version

≥ 1.55.0,

default-list

require()

[default]

[doc]

[group]

[arg]

, prefer

[script]

for multi-line bodies. Distill casey/Just principles; never paste third-party skill prose or embed the casey README.

Load reference files on demand from the index below — do not load all at once. Frontmatter is for discovery; references carry deep procedure.

编写并维护Just任务运行器。内部规范（house style）需匹配本仓库根目录下的

justfile

：

minimum-version

≥ 1.55.0、

default-list

、

require()

、

[default]

[doc]

[group]

[arg]

，多行内容优先使用

[script]

。提炼casey/Just的核心原则；请勿粘贴第三方技能文档或嵌入casey的README内容。

按需从下方索引加载参考文件——请勿一次性加载全部文件。前置元数据用于功能探索；参考文件包含详细操作流程。

Permission posture

权限策略

write-scoped

— may write justfiles; read-only

just

inspect by default; ask before destructive recipes, deleting a Makefile, or running side-effecting recipes.

write-scoped

—— 可写入justfile；默认仅以只读方式查看just内容；执行破坏性脚本、删除Makefile或运行有副作用的脚本前需征得用户同意。

Dispatch

调度

$ARGUMENTS	Mode
(empty) / `help`	Empty-args gallery
`create [description]`	Create
`edit [path\|recipe]`	Edit
`migrate [source]`	Migrate
`check [path]`	Check
`discover [query]`	Discover
Natural language about justfiles	Auto-detect

$ARGUMENTS	模式
(空值) / `help`	空参数功能概览
`create [description]`	创建
`edit [path\|recipe]`	编辑
`migrate [source]`	迁移
`check [path]`	检查
`discover [query]`	探索
关于justfile的自然语言指令	自动检测

Auto-detection heuristic

自动检测规则

Existing
```
justfile
```
/
```
Justfile
```
+ modify/fix/rename → edit
"migrate" / Makefile /
```
package.json
```
scripts → just → migrate
"lint" / "check" / "fmt" / house-style audit → check
"list" / "show" / "what recipes" / dump → discover
New justfile or "add recipe" without existing file → create
Pure shell / CI YAML / Make build semantics / mise / Compose → refuse (see negatives)

已存在
```
justfile
```
/
```
Justfile
```
+ 修改/修复/重命名 → 编辑
包含“migrate” / Makefile /
```
package.json
```
脚本 → 转换为just → 迁移
包含“lint” / “check” / “fmt” / 内部规范审计 → 检查
包含“list” / “show” / “what recipes” / dump → 探索
新建justfile或无现有文件时“添加脚本” → 创建
纯Shell / CI YAML / Make构建语义 / mise / Compose → 拒绝处理（参见不适用场景）

Empty args

空参数

When

$ARGUMENTS

is empty, show the mode gallery, posture line, critical rules summary, and reference index. Do not invent a mutating default.

当

$ARGUMENTS

为空时，展示模式概览、权限策略、核心规则摘要及参考索引。请勿默认执行任何会修改内容的操作。

Canonical vocabulary

标准术语

Use these exactly (canonical terms):

Term	Meaning
`write-scoped`	May write justfiles; ask before destructive runs/deletes
house style	This repo's justfile conventions ( `default-list` , `[doc]` , `[script]` , …)
discover	Read-only inspect via `just --list` / `--show` / `--dump`
migrate	Map Makefile/npm task scripts into Just recipes
`[script]`	Multi-line script recipe attribute (never combine with recipe-level `@` )
opt-in gate	Create-mode confirmations before overwrite or side effects

请严格使用以下标准术语：

术语	含义
`write-scoped`	可写入justfile；执行破坏性运行/删除操作前需征得同意
house style	本仓库的justfile规范（ `default-list` 、 `[doc]` 、 `[script]` 等）
discover	通过 `just --list` / `--show` / `--dump` 进行只读查看
migrate	将Makefile/npm任务脚本映射为Just脚本
`[script]`	多行脚本属性（请勿与脚本级 `@` 结合使用）
opt-in gate	创建模式下，覆盖文件或执行副作用操作前需确认

Critical rules

核心规则

Version-first — run
```
just --version
```
before using mid-2026 attributes; prefer ≥1.55.0.
Quiet vs script — never put
```
@
```
on a
```
[script]
```
recipe; use
```
@
```
only for line quieting.
Prefer
[script]
for multi-line shell; avoid fragile escaped multi-line recipes.
No blind
--fmt
— inspect with
```
--dump
```
/
```
--check
```
first; apply
```
--fmt
```
only with intent.
Dry-run / inspect before side effects — discover with
```
--list
```
/
```
--show
```
before running recipes that write, delete, or network.
check.py-before-complete — after skill or justfile edits in this repo skill, run
```
uv run python scripts/check.py
```
from
```
skills/justfile/
```
before declaring done.
No secrets in justfiles — use env / dotenv / user-owned secrets; never hardcode tokens.
Ask before deleting Makefile or other source runners during migrate.

版本优先 —— 使用2026年中期新增的属性前，先运行
```
just --version
```
；优先使用≥1.55.0版本。
静默模式vs脚本 —— 请勿在
```
[script]
```
脚本上添加
```
@
```
；仅在需要单行静默时使用
```
@
```
。
**优先使用
```
[script]
```
**处理多行Shell代码；避免使用脆弱的转义多行脚本。
勿盲目使用
--fmt
—— 先通过
```
--dump
```
/
```
--check
```
查看内容；仅在明确需求时应用
```
--fmt
```
。
执行副作用前先试运行/查看 —— 运行会写入、删除或联网的脚本前，先通过
```
--list
```
/
```
--show
```
进行探索。
完成前运行check.py —— 在本仓库技能中修改技能或justfile后，需从
```
skills/justfile/
```
目录运行
```
uv run python scripts/check.py
```
，再标记任务完成。
justfile中禁止存储密钥 —— 使用环境变量/dotenv/用户自有密钥；切勿硬编码令牌。
迁移期间删除Makefile或其他源运行器前需征得同意。

Operator contract

操作协议

create

create

Confirm target path; refuse overwrite without explicit approval.
Load references/create.md (includes opt-in gate).
Scaffold house-style settings +
```
[default]
```
list recipe + grouped docs.
Prefer
```
require("tool")
```
for hard deps; document optional tools.

确认目标路径；未经明确许可，拒绝覆盖现有文件。
加载references/create.md（包含opt-in gate确认步骤）。
生成符合内部规范的设置 +
```
[default]
```
列表脚本 + 分组文档。
硬依赖优先使用
```
require("tool")
```
；记录可选工具。

edit

edit

Read the target justfile; run discover inspect if recipes unclear.
Load references/edit.md.
Preserve house settings; migrate Make-flavored
```
##
```
comment docs to
```
[doc]
```
.

读取目标justfile；若脚本不清晰，先执行探索查看操作。
加载references/edit.md。
保留内部规范设置；将Make风格的
```
##
```
注释文档迁移至
```
[doc]
```
。

migrate

migrate

Inventory Makefile / npm scripts; map to recipes (see references/migrate.md).
Keep sources until user approves deletion.
Convert Make
```
##
```
help to Just
```
[doc]
```
/
```
default-list
```
— never keep Make comment-docs as the Just help system.

梳理Makefile/npm脚本；映射为Just脚本（参见references/migrate.md）。
保留源文件，直至用户批准删除。
将Make的
```
##
```
帮助注释转换为Just的
```
[doc]
```
/
```
default-list
```
—— 切勿保留Make注释文档作为Just的帮助系统。

check

check

Load references/check.md.
```
just --version
```
, then
```
--list
```
/
```
--dump
```
/
```
--check
```
as needed.
Report house-style gaps; do not auto-
```
--fmt
```
unless asked.

加载references/check.md。
先运行
```
just --version
```
，再根据需要执行
```
--list
```
/
```
--dump
```
/
```
--check
```
。
报告不符合内部规范的内容；除非用户要求，否则勿自动执行
```
--fmt
```
。

discover

discover

Load references/discover.md.

Prefer read-only:

--list

--show

--dump

(

--dump-format=json

--groups

Link casey manual for deep semantics: https://just.systems/man/en/

加载references/discover.md。

优先使用只读命令：

--list

--show

--dump

(

--dump-format=json

--groups

。

链接casey官方手册获取深层语义：https://just.systems/man/en/

When NOT to use

不适用场景

Shell script generation →
```
shell-scripter
```
Shell convention-only edits →
```
shell-conventions
```
CI/CD workflow YAML →
```
devops-engineer
```
Make file-timestamp / pattern-rule builds (not task recipes)
Docker Compose authorship
Toolchain version management as the product → mise tooling

See references/when-not-just.md.

Shell脚本生成 → 使用
```
shell-scripter
```
仅修改Shell规范 → 使用
```
shell-conventions
```
CI/CD工作流YAML → 使用
```
devops-engineer
```
Make文件时间戳 / 模式规则构建（非任务脚本）
Docker Compose编写
以工具链版本管理为核心需求 → 使用mise工具

参见references/when-not-just.md。

Reference index

参考索引

File	Use when
references/discover.md	Inspect recipes with just CLI
references/create.md	New justfile + opt-in gate
references/edit.md	Change existing recipes/settings
references/migrate.md	Makefile / npm → just
references/check.md	Lint / fmt-check / house-style audit
references/when-not-just.md	Scope refusals and redirects
references/pitfalls.md	Common Just footguns
references/patterns.md	House-style recipe patterns

文件	适用场景
references/discover.md	使用just CLI查看脚本
references/create.md	新建justfile + opt-in gate确认
references/edit.md	修改现有脚本/设置
references/migrate.md	Makefile / npm → just迁移
references/check.md	代码检查/格式检查/内部规范审计
references/when-not-just.md	范围拒绝与重定向
references/pitfalls.md	Just常见陷阱
references/patterns.md	符合内部规范的脚本模式

Validation Contract

验证协议

Run from this skill directory before declaring changes complete:

bash

uv run python scripts/check.py
uv run python skills/skill-creator/scripts/audit.py skills/justfile/
uv run python skills/skill-creator/scripts/package.py skills/justfile --dry-run

scripts/check.py

chains

validate_skill.py

validate_evals.py

, package dry-run, and audit. Completion criteria:

```
uv run python scripts/check.py
```
exits 0.
Audit grade A (≥90).
Package
```
--dry-run
```
reports portable with no errors.
No portable-CLI violations remain under this skill directory.

在标记修改完成前，从本技能目录运行以下命令：

bash

uv run python scripts/check.py
uv run python skills/skill-creator/scripts/audit.py skills/justfile/
uv run python skills/skill-creator/scripts/package.py skills/justfile --dry-run

scripts/check.py

会依次执行

validate_skill.py

validate_evals.py

, 包构建试运行和审计。完成标准：

```
uv run python scripts/check.py
```
执行后退出码为0。
审计等级为A（≥90分）。
包构建
```
--dry-run
```
报告可移植且无错误。
本技能目录下无违反可移植CLI规范的内容。

Example Blocks

示例命令

When

$ARGUMENTS

is empty, show:

```
/justfile
```
```
/justfile help
```
```
/justfile create <description>
```
```
/justfile edit <path|recipe>
```

/justfile migrate <Makefile|package.json>

```
/justfile check [path]
```
```
/justfile discover [query]
```

State the

write-scoped

boundary (justfile writes OK; ask before destructive recipe runs or Makefile deletion) and the validation command:

bash

uv run python skills/justfile/scripts/check.py

当

$ARGUMENTS

为空时，展示以下命令：

```
/justfile
```
```
/justfile help
```
```
/justfile create <description>
```
```
/justfile edit <path|recipe>
```

/justfile migrate <Makefile|package.json>

```
/justfile check [path]
```
```
/justfile discover [query]
```

说明

write-scoped

边界（可写入justfile；执行破坏性脚本运行或删除Makefile前需征得同意）及验证命令：

bash

uv run python skills/justfile/scripts/check.py

justfile

Original

Translation

Justfile

Justfile

Permission posture

权限策略

Dispatch

调度

Auto-detection heuristic

自动检测规则

Empty args

空参数

Canonical vocabulary

标准术语

Critical rules

核心规则

Operator contract

操作协议

`create`

`create`

`edit`

`edit`

`migrate`

`migrate`

`check`

`check`

`discover`

`discover`

When NOT to use

不适用场景

Reference index

参考索引

Validation Contract

验证协议

Example Blocks

示例命令