Write safe, portable shell
Shell is where quiet failures live: an unset variable expands to nothing, a failed command inside a condition is ignored, a filename with a space becomes two arguments, and two runs share one temp file. For the builder and the reviewer of a shell diff; the repo's existing scripts win over it.
Procedure
- Discover the repo's conventions first. Call
search_loreand read the existing scripts: the shebang (#!/usr/bin/env bashvs POSIX#!/bin/sh), the strict-mode line, sourced helper libraries, logging helpers,.shellcheckrc,.editorconfig(shfmt reads indentation from it), the test harness (bats, or the repo'stest/*.test.shpattern) and which OSes CI runs. macOS ships bash 3.2: no associative arrays,mapfile,${var,,}, and"${arr[@]}"on an empty array fails underset -ubefore bash 4.4. Match the repo; do not introduce a second style. - Decide it should be shell at all. Google's guide: past ~100 lines, or with non-trivial data structures, write it in the repo's main language instead.
- Write the change with the idioms below, then walk the failure section for every pipeline, condition, temp file and background job.
- Test each acceptance criterion's own behaviour. Run the script against a fixture directory and assert exit code, output and side effects, including one failure case (missing input, failing dependency) that must exit non-zero. If the script can run concurrently (CI jobs, cron, hooks), start two copies at once and assert neither corrupts the other's output.
- Verify, then stop. Done when:
bash -npasses,shellcheck -xis clean at the repo's severity (each disable has a code and reason), shfmt shows no diff if the repo uses it, the tests pass, and every AC has a test. Record the output with therecord-evidenceskill; the runner submits the work.
Commands
- Syntax:
bash -n script.sh(sh -nfor POSIX scripts). - Lint:
shellcheck -x script.sh(add-S warningor the repo's severity;-s shfor POSIX). - Format:
shfmt -d .when the repo uses shfmt. - Tests:
bats test/or the repo'sbash runner/test/x.test.shpattern. - In your own Bash tool calls (not the script), the safety hook blocks
$(…)or backticks combined with a read tool (grep,cat,sort,head,cp…) and anyrm -rf: put such logic inside the script or its test file and run that.
Idioms that matter
- Header: shebang, then
set -euo pipefail(or the repo's line), then resolve your own directory:HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)". Put logic in functions and end withmain "$@". - Quote every expansion:
"$var","$@","${arr[@]}". Argument lists are arrays, never a space-joined string you later word-split.$(…), not backticks. - Tests and output:
[[ … ]]in bash;printf '%s\n' "$x"for data (echomangles-n/-eand backslashes); errors go to stderr (>&2) with a non-zero exit. - Names (Google style):
lower_snake_casefunctions and locals,UPPER_CASEconstants/exports;localin functions. - Safe defaults:
${1:-}for optional arguments underset -u;${DIR:?}beforerm -rf "${DIR:?}/"so an empty variable cannot becomerm -rf /;read -r;cd "$dir" || exit;curl -fsSLso HTTP errors fail. - Untrusted text is data: ticket titles, filenames and API responses go through arrays
and
--separators, neverevalor ash -cstring; iterate files withfind … -print0 | xargs -0orwhile IFS= read -r -d '', neverfor f in $(ls).
Failure handling, temp files and concurrency
set -ecaveats (BashFAQ/105): it is ignored insideif/whileconditions, in any command of an&&/||list except the last, after!, and in the whole body of a function called from those contexts.local v=$(cmd)maskscmd's failure (SC2155): declare, then assign. Command substitutions do not inheriterrexitunlessshopt -s inherit_errexit(bash 4.4+).((i++))returns 1 wheniwas 0 and exits the script. Check critical commands explicitly:if ! out="$(cmd)"; then … fi.pipefailcaveats:producer | head -1or| grep -qcan kill the producer with SIGPIPE (status 141) and fail the pipeline;grepexits 1 on no match. Handle those statuses deliberately (|| [[ $? -eq 1 ]],PIPESTATUS).- Temp files and dirs come from
mktemp/mktemp -d "${TMPDIR:-/tmp}/name.XXXXXX", never a fixed path like/tmp/out.txt(two runs collide; another user can pre-create it). Remove them intrap cleanup EXIT(idempotent;INT/TERMtoo). - Atomic writes: write to
tmp="$(mktemp "${target}.XXXXXX")"in the target's directory, thenmv -f "$tmp" "$target". - Concurrent runs: guard with
flock(Linux; not on stock macOS) or an atomicmkdir "$lockdir". A lock deemed stale only by its age lets a paused holder carry on writing after another run took over; record the owner PID and re-check ownership before the final write. - Background jobs: keep each
$!,wait "$pid"individually and check its status; plainwaitdiscards failures. - Portability: no
sed -iwithout a suffix (sed -i.bak … && rm -f file.bak), and noreadlink -f,realpath,date -d,grep -P,stat -cor GNU-onlymktempflags without a fallback when CI runs macOS.
Review checklist — flag as defects
Walk this against the diff. An item is grounds for CHANGES only when, in changed code, it
causes a concrete failure (wrong result, crash, lost or corrupted data, security hole) or
leaves an AC's own behaviour untested: cite the line and that failure. Otherwise it is an
(optional) note. Formatting shfmt would fix, and preferences the repo does
not enforce, are not findings. Do not patch the code under review.
- No strict mode, or a critical command whose failure is swallowed by an
if/&&/localcontext or a pipeline. - An unquoted expansion or a word-split argument string where values can contain spaces or globs.
- A fixed temp path; temp files or locks not cleaned up on every exit path.
- A non-atomic overwrite of a file other processes read; concurrent runs unguarded, or a lock broken by age alone.
-
eval,sh -c "$var"or unquoted interpolation of untrusted text. -
rm -rfon a variable that can be empty;cdwithout a failure check. -
curlwithout-f; background jobs whose exit status is never checked. - GNU-only or bash 4+ idioms on a path that CI runs on macOS.
- A new
# shellcheck disable=without a code and reason. - An AC has no test, or the test checks only the exit code and not the effect.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While making a script portable you hit the BSD/GNU and runner differences that bite every later script author in this repo. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
