Makefiles and Taskfiles skill for Codex

Done well means: a newcomer (or Codex) runs one command to list every task, each task fails loudly on the first error, tasks that produce files skip work when inputs are unchanged, and nothing destructive runs without a confirmation.

Before writing anything

1. Read AGENTS.md, README, CONTRIBUTING.md, CI workflow files and package.json scripts. The runner must call the same commands CI calls, or the two drift.
2. Check what already exists: Makefile, GNUmakefile, justfile/.justfile, Taskfile.yml/Taskfile.yaml. Extend the existing runner; do not add a second one.
3. Check tool availability: make --version (macOS ships GNU Make 3.81 at /usr/bin/make, which lacks .ONESHELL, --output-sync and $(file ...)), just --version, task --version. Installing just or Task needs network and may need approval in the Codex sandbox; note it rather than assuming it is present.

Pick the runner

Situation	Default	Why
Builds real files from other files (C, protobuf codegen, docs)	GNU Make	Timestamp-based rebuilds are its core strength
Only command aliases (test, lint, dev, deploy), team wants readable syntax	just	No tabs, no .PHONY, real arguments, just --list built in
Cross-platform team incl. Windows without WSL, YAML is accepted	Task (go-task v3)	Single static binary, checksum-based up-to-date checks, includes for monorepos
JS-only repo with a handful of scripts	package.json scripts	Do not add a runner for five commands
Already has a working Makefile	Keep Make	Migration costs more than syntax pain

Make is installed almost everywhere; just and Task are one binary each but still an extra install. In repos used by agents, pick the one whose install is already documented.

GNU Make

Header every Makefile should have

SHELL := bash
.SHELLFLAGS := -eu -o pipefail -c
.DEFAULT_GOAL := help
.DELETE_ON_ERROR:
MAKEFLAGS += --warn-undefined-variables --no-builtin-rules

.PHONY: help
help: ## List available targets
	@grep -E '^[a-zA-Z0-9_.-]+:.*?## ' $(MAKEFILE_LIST) | \
	  awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'

• .SHELLFLAGS with pipefail makes cmd | tee log fail when cmd fails.
• .DELETE_ON_ERROR removes a half-written target so the next run does not treat it as up to date.
• Every recipe line starts with a literal tab. Spaces give missing separator.

Command targets vs file targets

.PHONY: test lint fmt dev
test: ## Run unit tests
	go test ./...

lint: ## Static checks
	golangci-lint run

# File target: rebuilt only when a .proto file is newer than the output
gen/api.pb.go: $(wildcard proto/*.proto)
	protoc --go_out=gen proto/*.proto

build: bin/app ## Build the binary
bin/app: $(shell find . -name '*.go' -not -path './vendor/*') go.mod go.sum
	go build -o $@ ./cmd/app

• Mark every non-file target .PHONY, otherwise a file or folder named test makes make test report “up to date”.
• Use $@ (target), $< (first prerequisite), $^ (all prerequisites).
• Shell variables need $$: for f in *.sql; do echo $$f; done.
• Each recipe line runs in a new shell. cd dir on one line does not affect the next; write cd dir && cmd or use .ONESHELL: (GNU Make 3.82+ only).

Variables and arguments

ENV ?= dev                      # override: make deploy ENV=staging
VERSION := $(shell git describe --tags --always --dirty)
IMAGE := ghcr.io/acme/app:$(VERSION)

• := evaluates once; = re-evaluates on every use (slow with $(shell ...)).
• ?= sets a default the caller can override from the command line or environment.
• Make has no positional arguments. Use VAR=value, never the $(MAKECMDGOALS) hack.

just

set dotenv-load
set shell := ["bash", "-euo", "pipefail", "-c"]

# List recipes (first recipe is the default)
default:
    @just --list

# Run tests, optionally filtered: just test ./pkg/...
test *args:
    go test {{args}}

# Build and tag an image
image tag=`git rev-parse --short HEAD`:
    docker build -t ghcr.io/acme/app:{{tag}} .

[confirm("Drop and recreate the local database?")]
db-reset:
    dropdb --if-exists app_dev && createdb app_dev && just migrate

[private]
migrate:
    goose -dir migrations postgres "$DATABASE_URL" up

• Comments directly above a recipe become its just --list description.
• Recipes run each line in a fresh shell, like Make. For multi-line logic use a shebang recipe (first line #!/usr/bin/env bash plus set -euo pipefail).
• {{args}} is substituted unquoted. If arguments may contain spaces, add set positional-arguments and use "$@" inside the recipe instead.
• [confirm] requires a reasonably recent just; check just --version and fall back to an explicit read -p prompt in a shebang recipe on old versions.
• [group('db')] organises long lists; just --list --unsorted keeps file order.

Task (go-task v3)

version: '3'

dotenv: ['.env']

vars:
  VERSION:
    sh: git describe --tags --always --dirty

tasks:
  default:
    cmds: [task --list]
    silent: true

  test:
    desc: Run unit tests (extra args after --)
    cmds:
      - go test ./... {{.CLI_ARGS}}

  build:
    desc: Build the binary
    sources: ['**/*.go', go.mod, go.sum]
    generates: [bin/app]
    cmds:
      - go build -ldflags "-X main.version={{.VERSION}}" -o bin/app ./cmd/app

  db:reset:
    desc: Drop and recreate the local database
    prompt: This deletes all local data. Continue?
    preconditions:
      - sh: '[ "$APP_ENV" != "production" ]'
        msg: Refusing to reset a production database
    cmds:
      - dropdb --if-exists app_dev
      - createdb app_dev

• task --list shows only tasks with a desc; task --list-all shows everything.
• sources/generates use checksums by default (stored in .task/, add it to .gitignore); method: timestamp switches to mtime.
• {{.CLI_ARGS}} receives everything after --: task test -- -run TestLogin.
• deps run in parallel; use sequential cmds: [{task: a}, {task: b}] when order matters.
• includes: pulls in per-package Taskfiles in monorepos (task api:test).
• --yes auto-confirms prompts. Never put it in CI for destructive tasks.

Hard rules

• The runner calls the same scripts CI calls. Better still, CI calls the runner (make ci, just ci, task ci) so local and CI cannot diverge.
• Destructive or outward-facing tasks (deploy, db-reset, release, publish, clean that deletes outside build dirs) need a confirmation gate and an environment guard. When Codex is asked to run one, it asks the user first even if the task has --yes.
• No secrets in the runner file. Read them from the environment or .env (gitignored).
• Keep recipes thin: more than ~10 lines of shell belongs in scripts/<name>.sh with set -euo pipefail, called from the runner.
• Do not shadow real tools: a Make target named docker or go confuses everyone.
• One naming scheme: verbs (test, lint, build), namespaced with : in Task or - in Make/just (db-migrate).

Gotchas

Symptom	Cause	Fix
missing separator. Stop.	Spaces instead of a tab	Re-indent recipe lines with tabs; check editorconfig
make test says nothing to do	File/dir named test and no .PHONY	Add .PHONY: test
$f is empty in a loop	Make expanded $f	Escape as $$f
Pipeline failure ignored	Default sh -c without pipefail	SHELL := bash plus .SHELLFLAGS
Works on Linux, breaks on macOS	GNU Make 3.81 or BSD sed -i	Avoid .ONESHELL; use sed -i.bak or a script
Task never re-runs build	generates missing or wrong glob	Run task build --force, fix globs, task --status build
just recipe ignores .env	dotenv-load not set	Add set dotenv-load

Verification

make -n deploy ENV=staging     # dry run: print commands without executing
make help && make test
just --list && just --dry-run image
task --list && task --dry build && task build && task build   # 2nd run: "up to date"

• Run each new task once (non-destructive ones) and confirm the exit code is non-zero when you break the underlying command on purpose.
• For file targets, run twice: the second run must do nothing.
• Update AGENTS.md with the runner commands so Codex and humans use them.

Output contract

When adding or rewriting a runner, report:

**Runner:** justfile (just 1.x required; install documented in README)
**Tasks:** default (list), test, lint, fmt, dev, build, image, db-reset (confirm)
**CI:** .github/workflows/ci.yml now calls `just ci`
**Checked:** `just --list`, `just test`, `just lint` pass; `just --dry-run image` shown
**Not run:** db-reset, deploy (destructive; need your go-ahead)