shell-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shell Conventions

Shell规范

Apply these conventions whenever shell work is the primary task.

Scope: Shell scripts, shell snippets,

Makefile

, and

justfile

convention enforcement. NOT for script generation, major shell refactors, Python, or CI workflow YAML.

进行Shell相关工作时，请遵循以下规范。

适用范围： Shell脚本、Shell代码片段、

Makefile

和

justfile

的规范强制执行。不适用于脚本生成、大规模Shell重构、Python或CI工作流YAML文件。

Dispatch

触发规则

$ARGUMENTS	Action
Active (auto-invoked when editing `.sh` , `.bash` , `.zsh` , `Makefile` , or `justfile` )	Apply the active operator contract below
Empty	Display the mode summary and trigger boundaries
`check`	Verify conventions only

参数	操作
自动触发（编辑 `.sh` 、 `.bash` 、 `.zsh` 、 `Makefile` 或 `justfile` 时自动调用）	应用下方的主动操作约定
无参数	显示模式概述及触发边界
`check`	仅验证规范合规性

When to Use

使用场景

Editing an existing shell script, shell snippet,
```
Makefile
```
, or
```
justfile
```
Normalizing portability, quoting, shebangs, env usage, or task naming
Reviewing shell changes for baseline safety and repo shell habits
Checking whether shell code follows the repo's required conventions

编辑现有Shell脚本、Shell代码片段、
```
Makefile
```
或
```
justfile
```
统一可移植性、引用规则、shebang、环境变量使用或任务命名规范
审查Shell代码变更，确保基线安全性及仓库Shell代码习惯
检查Shell代码是否符合仓库要求的规范

Canonical Vocabulary

标准术语定义

Canonical Term	Meaning
shell-primary	The main task is editing or reviewing shell, `Make` , or `just` code rather than touching it incidentally
conventions-only	Verify or tighten style, portability, and safety without redesigning the automation
env-based shebang	A shebang that resolves the interpreter through the environment rather than a hardcoded path
incidental shell	Shell appears only as a small supporting detail inside a larger non-shell task
target hygiene	Clear task names, predictable behavior, and explicit treatment of destructive operations

标准术语	含义
shell-primary	主要任务是编辑或审查Shell、 `Make` 或 `just` 代码，而非附带性操作
conventions-only	仅验证或收紧风格、可移植性和安全性规范，不重新设计自动化逻辑
env-based shebang	通过环境变量解析解释器路径而非硬编码路径的shebang
incidental shell	Shell仅作为大型非Shell任务中的小型辅助细节出现
target hygiene	清晰的任务名称、可预测的行为，以及对破坏性操作的显式处理

Operator Contract

操作约定

Active Auto-Invoke

主动自动触发

Confirm shell work is primary, not incidental to a broader task.
Apply shell-specific conventions to the file being edited.
Read
```
references/script-baseline.md
```
for shell scripts and snippets.
Read
```
references/make-just.md
```
for
```
Makefile
```
or
```
justfile
```
work.
Read
```
references/redirection-boundaries.md
```
if the task mixes shell with CI, deployment, or code generation concerns.
Keep the work limited to convention enforcement; do not broaden into script design or automation architecture.

确认Shell相关工作是主要任务，而非更广泛任务的附带操作。
对正在编辑的文件应用Shell专属规范。
阅读
```
references/script-baseline.md
```
以获取Shell脚本和代码片段的规范。
阅读
```
references/make-just.md
```
以获取
```
Makefile
```
或
```
justfile
```
相关工作的规范。
如果任务涉及Shell与CI、部署或代码生成的混合场景，阅读
```
references/redirection-boundaries.md
```
。
工作范围仅限规范强制执行，不得扩展至脚本设计或自动化架构层面。

Empty / Help

无参数 / 帮助

Show the three public entry paths: active auto-invoke, empty summary, and
```
check
```
.
Summarize what this skill covers: shell portability, quoting, env usage, and
```
Make
```
or
```
just
```
conventions.
Name the main non-trigger cases: CI YAML, release automation design, Python, and script generation.
Point to
```
shell-scripter
```
or
```
devops-engineer
```
when the request is outside convention enforcement.

展示三个公开入口：主动自动触发、无参数概述、
```
check
```
模式。
总结本技能覆盖范围：Shell可移植性、引用规则、环境变量使用，以及
```
Make
```
或
```
just
```
规范。
列出主要不触发场景：CI YAML、发布自动化设计、Python、脚本生成。
若请求超出规范强制执行范围，引导至
```
shell-scripter
```
或
```
devops-engineer
```
。

Check

检查模式

Read
```
references/check-mode.md
```
.
Review the relevant shell,
```
Make
```
, or
```
just
```
file for convention compliance only.
Report violations, risks, and recommended fixes without widening scope into full rewrites.
If the request is really generation, conversion, or CI workflow work, redirect instead of performing a conventions-only review.

阅读
```
references/check-mode.md
```
。
仅审查相关Shell、
```
Make
```
或
```
just
```
文件的规范合规性。
报告违规情况、风险及建议修复方案，不得扩展至完全重写。
若请求实际涉及脚本生成、转换或CI工作流相关工作，应进行重定向而非仅执行规范审查。

Auto-Invocation Trigger Logic

自动触发逻辑

Trigger when the main work is editing or reviewing an existing
```
.sh
```
,
```
.bash
```
,
```
.zsh
```
,
```
Makefile
```
, or
```
justfile
```
.
Trigger when the user asks for shell portability, quoting, shebang, env,
```
.PHONY
```
,
```
$
```
escaping, or task-name hygiene.
Do not trigger when shell appears only incidentally inside a larger Python, JS, or infrastructure task.
Do not trigger for CI workflow YAML, deploy pipelines, or release automation design; those belong to
```
devops-engineer
```
.
Do not trigger for creating new scripts, converting shell dialects, or deep shell refactors; those belong to
```
shell-scripter
```
.

当主要工作是编辑或审查现有
```
.sh
```
、
```
.bash
```
、
```
.zsh
```
、
```
Makefile
```
或
```
justfile
```
时触发。
当用户请求Shell可移植性、引用规则、shebang、环境变量、
```
.PHONY
```
、
```
$
```
转义或任务名称规范相关内容时触发。
当Shell仅作为大型Python、JS或基础设施任务中的附带内容出现时，不触发。
不适用于CI工作流YAML、部署流水线或发布自动化设计；这些场景属于
```
devops-engineer
```
的范畴。
不适用于创建新脚本、转换Shell方言或深度Shell重构；这些场景属于
```
shell-scripter
```
的范畴。

Progressive Disclosure

渐进式加载

Read reference files as indicated instead of loading everything at once.
Load
```
references/script-baseline.md
```
on demand for shell scripts and snippets.
Load
```
references/make-just.md
```
on demand for
```
Makefile
```
and
```
justfile
```
work.
Load
```
references/redirection-boundaries.md
```
on demand when shell work overlaps CI, release automation, or script generation.
Load
```
references/check-mode.md
```
on demand for
```
check
```
.

根据指示读取参考文件，而非一次性加载所有内容。
处理Shell脚本和代码片段时，按需加载
```
references/script-baseline.md
```
。
处理
```
Makefile
```
和
```
justfile
```
相关工作时，按需加载
```
references/make-just.md
```
。
当Shell工作涉及CI、发布自动化或脚本生成场景时，按需加载
```
references/redirection-boundaries.md
```
。
处理
```
check
```
模式时，按需加载
```
references/check-mode.md
```
。

Core Conventions

核心规范

Shell Scripts and Snippets

Shell脚本与代码片段

Prefer POSIX
```
sh
```
for simple automation that does not need arrays,
```
[[ ]]
```
, or process substitution.
Use
```
bash
```
only when the script clearly benefits from bash-only features.
Use env-based shebangs rather than hardcoded interpreter paths.
For
```
bash
```
, start with
```
set -euo pipefail
```
unless there is a clear reason not to.
For portable
```
sh
```
, use
```
set -eu
```
and avoid
```
pipefail
```
.
Quote variable expansions unless word splitting is intentionally required.
Use
```
command -v tool >/dev/null 2>&1
```
before depending on a non-guaranteed tool.
Prefer built-ins and standard utilities before adding dependencies.
Keep shell functions short and single-purpose.

对于不需要数组、
```
[[ ]]
```
或进程替换的简单自动化任务，优先使用POSIX
```
sh
```
。
仅当脚本明确需要bash专属特性时，才使用
```
bash
```
。
使用基于环境变量的shebang，而非硬编码的解释器路径。
对于
```
bash
```
脚本，除非有明确理由，否则开头应添加
```
set -euo pipefail
```
。
对于可移植的
```
sh
```
脚本，使用
```
set -eu
```
，避免使用
```
pipefail
```
。
除非有意需要分词，否则应对变量扩展进行引用。
在依赖非默认工具前，使用
```
command -v tool >/dev/null 2>&1
```
进行检查。
优先使用内置命令和标准工具，再考虑添加外部依赖。
保持Shell函数简短且单一职责。

Make and Just

Make与Just

Make targets must be task-oriented and documented through a
```
help
```
target when the file is substantial.
Use
```
.PHONY
```
for non-file Make targets.
Keep recipes idempotent where possible.
In Makefiles, escape
```
$
```
as
```
$$
```
inside recipes.
In justfiles, use parameters only when they materially simplify repeated tasks.
Do not hide destructive behavior behind vague target names.

Make目标必须以任务为导向，当文件内容较多时，需通过
```
help
```
目标进行文档说明。
对于非文件类型的Make目标，使用
```
.PHONY
```
声明。
尽可能保持脚本的幂等性。
在Makefile的脚本中，需将
```
$
```
转义为
```
$$
```
。
在justfile中，仅当参数能切实简化重复任务时才使用参数。
不得将破坏性操作隐藏在模糊的目标名称后。

Naming and Structure

命名与结构

Use lowercase, descriptive function names.
Prefer
```
project_root
```
,
```
target_path
```
, or
```
output_file
```
over one-letter names.
Keep environment variable names uppercase.
Favor early validation and explicit usage text over silent failure.

使用小写、描述性的函数名。
优先使用
```
project_root
```
、
```
target_path
```
或
```
output_file
```
等名称，而非单字母名称。
环境变量名使用大写。
优先选择早期验证和显式使用说明，避免静默失败。

Reference File Index

参考文件索引

File	Purpose	When to Read
`references/script-baseline.md`	Baseline shell portability, safety, quoting, and structure rules	Script or snippet work
`references/make-just.md`	`Makefile` and `justfile` conventions, idempotence, `$` escaping, and target hygiene	`Makefile` or `justfile` work
`references/redirection-boundaries.md`	Redirection rules for CI YAML, release automation, script generation, and major refactors	Mixed-scope or ambiguous shell work
`references/check-mode.md`	Exact expectations for conventions-only verification	`check` mode

文件	用途	阅读时机
`references/script-baseline.md`	Shell可移植性、安全性、引用规则和结构规则的基线规范	处理脚本或代码片段时
`references/make-just.md`	`Makefile` 和 `justfile` 的规范、幂等性、 `$` 转义及目标命名规范	处理 `Makefile` 或 `justfile` 时
`references/redirection-boundaries.md`	CI YAML、发布自动化、脚本生成及大规模重构的重定向规则	处理跨场景或模糊的Shell工作时
`references/check-mode.md`	仅验证规范合规性的具体要求	使用 `check` 模式时

Critical Rules

关键规则

Always use env-based shebangs, not hardcoded interpreter paths.
Quote variable expansions unless intentional splitting is required.
Use
```
bash
```
only when you need bash; otherwise prefer portable
```
sh
```
.
Do not use
```
eval
```
unless there is no safer alternative and the risk is explained.
Validate required external commands before first use.
Make or just tasks that mutate state must be named clearly and predictably.
Route script generation and major refactors to
```
shell-scripter
```
; this skill is conventions only.

始终使用基于环境变量的shebang，而非硬编码的解释器路径。
除非有意需要分词，否则应对变量扩展进行引用。
仅当需要bash特性时才使用
```
bash
```
；否则优先使用可移植的
```
sh
```
。
除非没有更安全的替代方案且已说明风险，否则不得使用
```
eval
```
。
在首次使用前验证所需的外部命令是否存在。
修改状态的Make或just任务必须命名清晰且可预测。
脚本生成和大规模重构任务应转交
```
shell-scripter
```
处理；本技能仅负责规范强制执行。

Scope Boundaries

范围边界

IS for: shell style, portability, shebangs, quoting, env usage,

Make

just

conventions, conventions-only review.

NOT for: Python, CI workflow YAML, deploy automation design, script generation, or major shell rewrites.

适用场景： Shell风格、可移植性、shebang、引用规则、环境变量使用、

Make

或

just

规范、仅规范审查。

不适用场景： Python、CI工作流YAML、部署自动化设计、脚本生成或大规模Shell重写。