# Makefile Standard

> Use when the user asks to create or edit a Makefile, add or rename a make target, or review Make target names.

- Skill: `painhardcore/makefile-standard` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add painhardcore/makefile-standard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/painhardcore/makefile-standard/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: painhardcore (https://skillmd.com/u/painhardcore)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/painhardcore/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`](references/profiles.md) first. Full rules: [`references/makefile-standard.md`](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`](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`](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`](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.

```bash
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
# makefile-standard: except <target> — <reason>
```

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