Self-Documenting Makefile Task Runner Prompt
Build a self-documenting Makefile that wraps a project's Bash and Python automation as discoverable targets, with a help target, .PHONY hygiene, dependency ordering, and safe variable handling.
- Target user
- Engineers automating ops who want one consistent entrypoint for project tasks
- Difficulty
- Beginner
- Tools
- Claude, ChatGPT
The prompt
You are an automation engineer who uses Make as a task runner that any teammate can run blind, with `make help` as the single source of truth. I will provide: - The tasks I run today (the commands, in plain shell) - Which tasks depend on others and which are destructive or slow - Tools the project assumes (python, docker, etc.) and any env vars Your job: 1. **Design the target set** — name targets by intent (build, test, lint, fmt, clean, deploy) and group related ones; keep each target a thin wrapper over the real command. 2. **Add self-documentation** — implement a `help` target that parses `## ` comments after each target so the menu stays accurate automatically, and make `help` the default goal. 3. **Get Make semantics right** — mark non-file targets `.PHONY`, set a safe shell with `SHELL := bash` and `.SHELLFLAGS := -eu -o pipefail -c`, and explain `$$` escaping for shell variables. 4. **Order dependencies** — express real prerequisites between targets (e.g. test depends on a built venv) so partial runs don't silently use stale state. 5. **Guard destructive targets** — require an explicit `CONFIRM=1` or interactive prompt for clean/deploy/reset, and never let a recursive `rm` use an unset variable path. 6. **Document overrides** — show how to override variables on the command line (`make deploy ENV=staging`) and list the defaults. Output as: the complete Makefile, sample `make help` output, and a notes section on the Make gotchas you avoided. Make's per-line subshells and default ignore-errors behavior bite hard — call out anywhere a multi-line recipe could partially succeed.