主题 / 语言
Shell 和 PowerShell 脚本、任务入口（just、Task、Make）、YAML/JSON/TOML 配置、.env 文件、Dockerfile、SQL 文件和 CI 配置文件怎么写、用什么工具检查。
#! 解释器声明）；sh 脚本里不用 Bash 专有语法；PowerShell 单独一套工具。.sh 后缀的可执行文件。set -euo pipefail 是护栏，不是异常处理。dev/test/lint/format/check/build/clean 这些名字，不统一工具；check 不改文件，失败不能被吞掉。.env.example；生产环境由部署平台注入。.dockerignore。run:。#!/bin/sh 的脚本里不写 Bash 专有语法#!/usr/bin/env bash；需要在最小镜像或系统初始化阶段运行的才写 POSIX sh。.sh 后缀的可执行文件）在 CI 上跑 ShellCheck，有告警即失败shfmt -f . 按后缀和 shebang 列出全部 Shell 文件，交给 shellcheck 检查scripts/*.sh 会漏掉 bin/ 下没有后缀的脚本，而那往往是最常被执行的。个别告警确实不适用时，在该行上方用 # shellcheck disable=SCxxxx 指明规则并写理由（见 COD-039），不整文件关闭。
shfmt -d 检查；缩进等选项写在 .editorconfig 里shfmt -d .，有差异即失败.editorconfig，编辑器和 CI 用同一份设置。格式化只管排版，不能替代 ShellCheck 的正确性检查。
"$@" 或数组，不拼成一个字符串$@）等规则只有确实要做通配符展开时才不加引号，并写注释说明。遍历文件不用 for f in $(ls)，用 find -print0 配合 while read -r -d ''，或直接用通配符。
set -euo pipefail；预期可能失败的命令用 if 或显式检查退出码，不把 -e 当异常处理-e 在 if 条件、&&/|| 链、部分函数调用里不会触发退出，指望它兜底会漏掉错误。pipefail 让管道里任何一段失败都算失败；但 grep -q 这类提前退出的命令会让上游收到 SIGPIPE，此时要显式处理，而不是全局关掉。pipefail，写 POSIX sh 时要在目标 shell 上实测，或逐步检查返回码。eval、bash -c、sh -c 或拼接出的命令字符串；命令和参数分开传eval、-c 调用作为候选，评审其参数来源mktemp 创建并用 trap 清理；rm -rf 用到的路径变量先确认非空且在受控目录内${var:?} 防止变量为空时删到根目录；评审删除路径的来源rm -rf "$dir/"* 会删到意想不到的地方。tmp_dir=$(mktemp -d)
trap 'rm -rf -- "$tmp_dir"' EXIT
只是读取或小改 JSON/YAML 时用 jq、yq 这类解析工具，不用 sed、grep 按文本改结构化数据。
.ps1Invoke-ScriptAnalyzer -Recurse，有错误级问题即失败脚本开头写 Set-StrictMode -Version Latest 和 $ErrorActionPreference = 'Stop'，让未定义变量和非终止错误也能暴露出来。测试用 Pester。
just --list、task --list 等能列出任务；贡献说明里写明所需工具lint：静态检查，不改文件。format：格式化，会改文件。check：lint、类型检查、快速测试等只读检查的合集，CI 和本地都跑它。clean：只删本项目生成的文件。check、lint、test 任务不得修改工作区里的文件check 后执行 git status --porcelain，输出非空即失败|| true、Make 的 - 前缀、Task 的 ignore_error、CI 的 allow_failure 吞掉检查失败deploy-staging、reset-db），不挂在默认任务、check 或 test 之下.PHONY；配方用到 Bash 语法时显式设置 SHELL 和 .SHELLFLAGS.PHONY 中.PHONY 时，仓库里恰好有同名文件或目录，目标就会被跳过；Make 默认用 /bin/sh，Bash 语法会在部分系统上失败。例如 SHELL := bash 和 .SHELLFLAGS := -euo pipefail -c。配方行必须用 Tab 缩进，在 .editorconfig 里给 Makefile 设 indent_style = tab。
环境变量只放部署时会变的简单值和密钥引用，不把整段 JSON 塞进一个变量。
check-jsonschema --schemafile schemas/xxx.json <配置文件>required、类型、枚举和取值范围；未知字段默认拒绝（additionalProperties: false），要扩展时再放开。key-duplicates 规则（默认开启）；JSON 用能检出重复键的工具，如 pre-commit-hooks 的 check-json 或 Biome 的 noDuplicateObjectKeys1.10、带前导零的数字、12:30 这类时间truthy 和 octal-values 规则调成 error 级别；像版本号的浮点值靠评审和反序列化测试no 可能变成 false，1.10 可能变成 1.1，结果是配置被悄悄改了。GitHub Actions 的 on: 是键不是值，给 truthy 规则设 check-keys: false 避免误报。
yamllint -s .（-s 让告警也失败）同时用 Prettier 时，yamllint 的缩进、行宽等排版规则交给 Prettier，避免两个工具互相打架。
prettier --check "**/*.{json,yml,yaml}"tsconfig.json、编辑器设置），不把它当标准 JSON 交给其他解析器。tombi format --check 和 tombi lint）已经在用 Taplo 的项目可以继续用，但它已转为个人维护、发布很少，新项目不再选它。工具通过不代表目标程序的 TOML 解析器行为一致，关键配置要用目标程序实际加载一次。
.env 等本地环境文件写进 .gitignore，不入库；入库的 .env.example 只列变量名、说明和非敏感默认值.env.example 以外的 .env、.env.* 文件，并对仓库跑密钥扫描（工具见 25）.env 里通常有真实密码和令牌，一旦提交就进了历史，删文件也删不掉。代码新增或删除了环境变量，同一个改动里同步更新 .env.example；可以用脚本比对代码读取的变量名和示例文件。
ORDER_SVC_DB_URL.env.example 和配置定义里的变量名格式KEY=value。source 来路不明的 .env：它会被当成 Shell 代码执行。docker build --check，并实际构建一次hadolint Dockerfile 和 docker build --check .，再执行真实构建SHELL ["/bin/bash", "-o", "pipefail", "-c"]（hadolint DL4006），否则管道前段失败会被忽略。.hadolint.yaml 入库，忽略某条规则要写理由。latest 或不带标签的基础镜像；用标签加 digest 固定，由依赖更新机器人提 PR 升级@sha256:固定 digest 不等于构建可复现：包下载、时间戳、编译器、架构都可能让两次构建结果不同。基础镜像怎么选见 26。
id 确认docker build --check 的 SecretsUsedInArgOrEnv 检查；对 Dockerfile 跑密钥扫描.dockerignore，至少排除 .git、.env*、密钥文件、依赖和构建缓存目录.dockerignore 存在并包含这些条目极简的单阶段镜像（如只拷一个静态二进制）可以例外。
--no-install-recommends）；docker build --check 的 JSONArgsRecommended系统包是否锁具体版本（DL3008）看基础镜像的更新策略；锁了要有人定期升级，否则会因旧版本被源删除而构建失败。
.sqlfluff 入库并写明目标方言sqlfluff lint；.sqlfluff 里必须有 dialect 设置SELECT *；EXISTS (SELECT 1 ...) 这类不取列的写法除外.sqlfluff 中启用 AM04（结果列数不确定）actionlint 和 zizmor .github/workflows/；GitLab 调用项目的 CI Lint 接口GitLab 的 include、rules、变量要在项目上下文里才能完整校验，所以用实例自带的 CI Lint，而不是只跑 yamllint。
@v4、@mainunpinned-uses 检查SHA 后面加注释写明对应的版本号，交给 Renovate 或 Dependabot 升级（见 03）。GitHub 的 workflow 依赖锁文件（.github/workflows/actions.lock）是新功能，确认所用方案支持后再用。
permissions，只给需要更高权限的 job 单独提升excessive-permissions 检查来自 fork 的 PR 代码不和能读密钥或写权限的 job 混跑。GitLab 的敏感变量设为 protected 和 masked。
run: 脚本，先放进环境变量再引用template-injection 检查${{ }} 表达式会在脚本执行前被原样替换进去，PR 标题里的一段 Shell 代码就会被执行。- env:
PR_TITLE: ${{ github.event.pull_request.title }}
run: printf '%s\n' "$PR_TITLE"
timezone 指定 IANA 时区；最短间隔 5 分钟，高峰时可能延迟。没有符合条件的规则。
| 类别 | 默认 | 备选（何时用） | 不推荐 |
|---|---|---|---|
| Shell 静态检查 | ShellCheck · GPL-3.0（作为独立命令行工具在 CI 里运行；要随产品分发时见 27） | bash -n（只想快速查语法错误；不能替代 ShellCheck） | 只靠人工评审：引号、方言这类问题肉眼很难看全 |
| Shell 格式化 | shfmt · BSD-3-Clause | — | — |
| Shell 脚本测试 | bats-core · MIT 脚本有分支逻辑、被多处调用，需要回归测试时 | — | — |
| PowerShell 检查与测试 | PSScriptAnalyzer（静态检查）+ Pester（测试） · PSScriptAnalyzer 为 MIT，Pester 为 Apache-2.0 | — | 用 ShellCheck 查 .ps1：不是同一门语言 |
| 任务入口 | just · just 为 CC0-1.0；Task 为 MIT；GNU Make 为 GPL-3.0 或更高版本 多语言仓库，主要是给一组命令起好记的名字 | Task（需要任务依赖、按输入输出跳过已完成的任务，或希望在 Windows 上不依赖 Bash 时） GNU Make（C/C++ 项目要按文件增量构建，或已有成熟的 Makefile） npm scripts（只有一个 Node 包的项目） | 一层套一层的包装脚本：出错时找不到真正执行的命令 为几条命令写复杂的 Makefile：Tab、变量展开、隐式规则带来额外的坑 |
| JSON Schema 校验 | check-jsonschema · check-jsonschema 为 Apache-2.0 | 应用内的 JSON Schema 校验库（配置在程序启动时校验，各语言的校验库见 10–14） | 只检查文件是合法的 JSON 或 YAML：挡不住拼错的键和错误的类型 Sourcemeta JSON Schema CLI（集成或分发时）：许可证为 AGPL-3.0，分发或作为服务提供前要按 27 审查；只在 CI 里独立运行时影响较小 |
| YAML 检查 | yamllint · GPL-3.0（独立命令行工具） | — | 拿 yamllint 当 CI 编排的校验：它不懂 GitHub Actions 或 GitLab CI 的语义，见 CFG-036 |
| JSON 与 YAML 格式化 | Prettier · MIT | Biome（TypeScript 项目已经用 Biome，JSON 交给它，YAML 仍用 Prettier） | 同一种文件用两个格式器：互相改写 |
| TOML 格式化与检查 | Tombi · Tombi、Taplo 均为 MIT | Taplo（存量项目已在用且没遇到问题；两者的配置不兼容，迁移要改配置） | 用 YAML 或通用格式器处理 TOML：不懂 TOML 语法 |
| Dockerfile 检查 | hadolint + docker build --check · hadolint 为 GPL-3.0（独立命令行工具） | — | 只 lint 不构建：证明不了能构建成功 |
| SQL 检查与格式化 | SQLFluff · SQLFluff 为 MIT；pgFormatter 为 PostgreSQL License | pgFormatter（只用 PostgreSQL、只需要格式化，不需要 lint） | 把 SQLFluff 当成 SQL 注入检查：它只看 SQL 文件本身，注入防护见 25 |
| GitHub Actions 配置检查 | actionlint（语法）+ zizmor（安全） · actionlint、zizmor 均为 MIT | GitLab CI Lint（用 GitLab CI 时） | 只跑 actionlint：它不查权限和注入这类安全问题 |
set -e 当 try/catch，以为任何失败都会让脚本退出for f in $(ls) 和不加引号的变量find -print0curl ... | bash 安装工具check 任务里顺手跑了格式化FROM xxx:latest 用于正式发布run: echo "${{ github.event.pull_request.title }}""$PR_TITLE" 引用下面的内容还没核实或待补调研，不要当成规则执行。
set -o pipefail 的支持情况，未逐个核实