Makefile Automation

Makefile Automation AI Skill Guide

Overview

Make is a dependency-aware task runner. A Makefile declares targets, prerequisites, and recipes so agents and humans share stable entrypoints (make test, make build, make fmt). Good Makefiles are self-documenting, use .PHONY for non-file targets, fail on errors (set -e semantics via flags), and avoid hiding destructive operations behind innocent names.

make <target>
     |
     v
dependency graph -> recipes (shell lines)
     |
     +--> tools: go test, npm, docker, terraform, ...

When to use

• Standardizing repo commands across local and CI
• Encoding multi-step build/lint/test/release flows
• Generating help text for onboarding
• Wrapping messy tool invocations behind stable names

Operational directives

1. Mark non-file targets .PHONY so Make does not skip them when a file/folder shares the name.
2. Use SHELL := bash and .SHELLFLAGS := -eu -o pipefail -c for safer recipes.
3. Provide a help target as the default goal.
4. Keep recipes idempotent where practical; name destructive targets explicitly (destroy, reset-db).
5. Prefer variables for versions and paths; allow overrides (make build IMAGE_TAG=...).

Concrete examples

Self-documenting Makefile

SHELL := bash
.SHELLFLAGS := -eu -o pipefail -c

APP      ?= api
IMAGE    ?= ghcr.io/example/$(APP)
GIT_SHA  := $(shell git rev-parse --short HEAD)
TAG      ?= $(GIT_SHA)

.DEFAULT_GOAL := help

.PHONY: help
help: ## Show available targets
	@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_-]+:.*?##/ {printf "  %-16s %s\n", $$1, $$2}' $(MAKEFILE_LIST)

.PHONY: fmt
fmt: ## Format code
	go fmt ./...

.PHONY: test
test: ## Run unit tests
	go test ./...

.PHONY: build
build: test ## Build container image
	docker build -t $(IMAGE):$(TAG) .

.PHONY: run
run: ## Run API locally
	go run ./cmd/api

.PHONY: clean
clean: ## Remove build artifacts
	rm -rf dist/

Pattern rules and generated files

dist:
	mkdir -p dist

dist/app: $(shell find . -name '*.go') | dist
	go build -o $@ ./cmd/api

Include env-specific fragments

-include .env.mk
# .env.mk is gitignored; developers may set REGISTRY=...

Parallelism note

make -j4 test build   # only when targets are safe concurrently

Design table

Best practices

1. Keep recipes short; call scripts under scripts/ for complex logic.
2. Mirror CI job names to Make targets so docs stay accurate.
3. Quote variables and paths with spaces carefully; prefer no spaces in artifact paths.
4. Document required tools (make doctor that checks versions).

Limitations

• Make is not a full DAG workflow engine for cloud pipelines (still useful as a local facade).
• Windows users may need GNU Make via Git Bash/WSL - note that in README when relevant.
• Hidden recursive Make can obscure failures - keep nesting shallow.

Related skills

• docker - common make build / make compose-up wrappers
• pulumi - make preview / make up guarded targets
• trivy - make scan gate before push
• sqlite / mysql - make db-migrate database helpers