shell-conventions

Shell 规范

当 Shell 工作是主要任务时，应用这些规范。

**范围：**Shell 脚本、Shell 代码片段、Makefile 和 justfile 的规范执行。不适用于脚本生成、大型 Shell 重构、Python 或 CI 工作流 YAML。

分派

$ARGUMENTS	操作
Active（编辑 .sh、.bash、.zsh、Makefile 或 justfile 时自动调用）	应用下方的主动操作契约
Empty	显示模式摘要和触发边界
check	仅验证规范

适用场景

• 编辑现有 Shell 脚本、Shell 代码片段、Makefile 或 justfile
• 规范化可移植性、引号、shebang、env 用法或任务命名
• 审查 Shell 变更是否符合基本安全要求和仓库的 Shell 习惯
• 检查 Shell 代码是否遵循仓库要求的规范

规范术语

规范术语	含义
shell-primary	主要任务是编辑或审查 Shell、Make 或 just 代码，而非顺带涉及这些内容
conventions-only	在不重新设计自动化的前提下，验证或收紧风格、可移植性和安全性
env-based shebang	通过环境解析解释器，而非使用硬编码路径的 shebang
incidental shell	Shell 仅作为较大型非 Shell 任务中的少量辅助细节出现
target hygiene	任务名称清晰、行为可预测，并明确处理破坏性操作

操作契约

主动自动调用

1. 确认 Shell 工作是主要任务，而非更广泛任务中的附带事项。
2. 对正在编辑的文件应用 Shell 专属规范。
3. 对 Shell 脚本和代码片段，阅读 references/script-baseline.md。
4. 对 Makefile 或 justfile 工作，阅读 references/make-just.md。
5. 如果任务涉及 Shell 与 CI、部署或代码生成，请阅读 references/redirection-boundaries.md。
6. 将工作限制在规范执行范围内；不要扩展到脚本设计或自动化架构。

Empty / 帮助

1. 展示三个公开入口：主动自动调用、空参数摘要和 check。
2. 概述此技能涵盖的内容：Shell 可移植性、引号、env 用法，以及 Make 或 just 规范。
3. 列出主要的不触发情形：CI YAML、发布自动化设计、Python 和脚本生成。
4. 如果请求超出规范执行范围，请指引至 shell-scripter 或 devops-engineer。

Check

1. 阅读 references/check-mode.md。
2. 仅检查相关的 Shell、Make 或 just 文件是否符合规范。
3. 报告违规项、风险和建议的修复方案，不要扩大范围进行全面重写。
4. 如果请求实际涉及生成、转换或 CI 工作流，请改为引导至相应流程，而非执行仅限规范的审查。

自动调用触发逻辑

• 主要工作是编辑或审查现有 .sh、.bash、.zsh、Makefile 或 justfile 时触发。
• 用户要求 Shell 可移植性、引号、shebang、env、.PHONY、$ 转义或任务名称规范时触发。
• Shell 仅作为较大型 Python、JS 或基础设施任务中的附带内容时，不触发。
• CI 工作流 YAML、部署流水线或发布自动化设计不触发；这些工作由 devops-engineer 负责。
• 创建新脚本、转换 Shell 方言或进行深度 Shell 重构时不触发；这些工作由 shell-scripter 负责。

渐进式披露

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

核心规范

Shell 脚本与代码片段

• 对于不需要数组、[[ ]] 或进程替换的简单自动化，优先使用 POSIX sh。
• 只有在脚本明显能从 bash 专属功能中受益时才使用 bash。
• 使用基于 env 的 shebang，而不是硬编码解释器路径。
• 对于 bash，除非有明确理由，否则以 set -euo pipefail 开头。
• 对于可移植的 sh，使用 set -eu，并避免使用 pipefail。
• 除非有意进行分词，否则应为变量展开加上引号。
• 依赖不能保证存在的工具前，使用 command -v tool >/dev/null 2>&1 检查。
• 添加依赖前，优先使用内置功能和标准工具。
• 保持 shell 函数简短且用途单一。

Make 与 Just

• Make 目标必须以任务为导向；如果文件内容较多，应通过 help 目标提供说明。
• 对非文件类 Make 目标使用 .PHONY。
• 尽可能确保配方具有幂等性。
• 在 Makefile 中，配方内的 $ 应写为 $$。
• 在 justfile 中，只有当参数能显著简化重复任务时才使用参数。
• 不要将破坏性操作隐藏在含糊的目标名称后。

命名与结构

• 使用小写且描述明确的函数名。
• 优先使用 project_root、target_path 或 output_file，而不是单字母名称。
• 环境变量名使用大写。
• 优先进行提前验证并提供明确的用法说明，避免静默失败。

参考文件索引

文件	用途	何时阅读
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 模式时

关键规则

1. 始终使用基于 env 的 shebang，不要使用硬编码的解释器路径。
2. 除非有意进行分词，否则应为变量展开加上引号。
3. 只有在需要 bash 时才使用 bash；否则优先使用可移植的 sh。
4. 除非没有更安全的替代方案且已说明风险，否则不要使用 eval。
5. 在首次使用前验证所需的外部命令。
6. 会修改状态的 Make 或 just 任务必须采用清晰且可预测的名称。
7. 将脚本生成和重大重构交由 shell-scripter 处理；此技能仅涉及规范。

范围边界

适用于： Shell 风格、可移植性、shebang、引号、env 用法、Make 或 just 规范，以及仅针对规范的审查。

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