Makefile Standard

makefile-standard

Naming and shape coach for Makefiles. Not a maximal generator: an operation with no evidence gets no target.

Scope

Not here: Compose file contents (compose-standard), image builds (dockerfile-standard), GitHub Actions wiring (ci-standard), Go layout and golangci (go-project-standard). This skill names the Make wrappers for all of them.

Workflow

1. Inspect needs, not possibilities

List the operations that exist or were requested: scripts, CI, README, Compose, deploy, DB tools, current targets. Ignore "nice to have" capabilities with no evidence.

2. Name each needed operation

Read references/profiles.md first. Full rules: references/makefile-standard.md.

For each needed operation, and only those:

1. Decide where it acts: production is prod-*, local is the plain name, shipping code from this machine is deploy (never prod-deploy). A production backup is prod-backup.
2. Map it to a canonical name via profiles or references/targets.yaml.
3. Apply shape: ## help text, .PHONY, kebab-case, ENV= where it applies.
4. Add or rename that one target. Adding deploy does not drag in prod-*.

Greenfield: start from assets/Makefile.template and replace every $(error Adapt…) with a real recipe. Append a snippet from assets/snippets/ only when that capability is evidenced (compose, deploy, prod, db).

Migrate: references/migration-guide.md. Rename to canonical names and drop targets with no callers unless the user wants them kept.

3. YAGNI

• No prod-* without production evidence.
• No backend-* / frontend-* unless two or more components are operated independently.
• Do not expose a leaf that only ever runs under check or ci.
• Prefer ./scripts/… over a long recipe.
• Leaving a catalog entry unused is correct. The catalog is vocabulary, never a to-do list.

4. Validate

Never run deploy, prod-*, or destructive targets to test your work. Use make help and targets you have read.

python3 scripts/validate_makefile.py /path/to/Makefile

Errors = fix. Warnings = human review. A missing optional target is not a failure.

5. Report

Targets added, renamed, or removed, with the evidence for each; aliases kept or deprecated; any target that touches production or destroys data; exceptions taken; validation result. Name what you deliberately left out.

Hard rules

• Never include an absolute developer-standards or home-directory path.
• Apps must not depend on this repo at runtime, in CI, or on a server.
• No personal terminal wrappers in a project Makefile.

Exceptions

# makefile-standard: except <target> — <reason>

Every ignored MUST needs an exception line with a reason. Prefer omitting an unused conditional target over excepting it.