go-makefile-writer

Go Makefile Writer

Design a practical root Makefile that is readable, reproducible, and aligned with repository layout.

Quick Reference

Execution Modes

Select a mode before starting and state it in the output report.

Create (new Makefile from scratch)

• Full target set generated from project inspection.
• Use golden templates (simple-project.mk / complex-project.mk) as starting points.
• No backward-compatibility concerns.

Refactor (modify existing Makefile)

• Minimal-diff edits — change only what is needed; do not rewrite the entire file.
• Backward compatibility: if target names change, keep aliases for at least one transition period and document them in the output report.
• Preserve existing useful targets unless user explicitly asks to remove them.
• Before editing, snapshot the current target list via make -qp | awk -F: '/^[a-zA-Z0-9_-]+:/ {print $1}' | sort -u for comparison.
• Validation must include verifying that previously used critical targets still work (or their aliases do).

Workflow

0. Select mode (Create or Refactor) and record rationale.

1. Inspect project structure:

   • discover cmd/**/main.go entrypoints by running this skill's discovery script against the target repo: bash <skill-dir>/scripts/discover_go_entrypoints.sh <project-root> (the script lives in the skill directory, not in the target repo — pass the repo root as its argument)
   • if the script cannot run, fall back to find cmd -name main.go -type f (or rg --files cmd | grep '/main\.go$' when rg is available)
   • detect quality tools and conventions (go test, golangci-lint, swag)
   • detect code generation usage (go generate, protobuf, wire, mockgen, etc.)
   • detect containerization (Dockerfile, docker-compose.yml)
   • read go.mod for Go version (go directive) and module path
   • inspect existing Makefile if present (Refactor mode)
   • detect workspace / multi-module layout via the toolchain first: go env GOWORK (a non-empty path means a go.work workspace → its modules are go list -m). Only when there is no go.work fall back to a scoped go.mod search (bash <skill-dir>/scripts/discover_go_entrypoints.sh --modules <project-root>, which excludes vendor/, testdata/, examples/). See §Monorepo Support.

2. Plan target set:

   • core targets: help, fmt, tidy, test, cover, lint, clean
   • version targets: version (print embedded version info)
   • CI target: ci (fmt-check + lint + test + cover-check in one pass)
   • optional targets: swagger, generate, install-tools, test-integration, bench
   • build targets: build-all plus per-binary targets (with -ldflags version injection)
   • run targets: per-binary run-* targets
   • container targets (when Dockerfile present): docker-build, docker-push
   • cross-compile targets (when needed): build-linux, build-all-platforms
   • Go version-aware decisions (see Go Version Awareness)

3. Compose and write root Makefile:

   • keep targets explicit and predictable
   • use variables (GO, BIN_DIR, VERSION, COMMIT, BUILD_TIME) for repeated paths and build metadata
   • inject version info via -ldflags in all build targets
   • include .PHONY
   • fail early with clear tool checks for optional dependencies
   • use target templates from makefile-quality-guide.md
   • Refactor mode: apply minimal-diff strategy and backward-compatibility rules from the mode definition above

4. Validate:

   • run make help
   • run make test
   • run one representative build-* target
   • build, then run the binary's --version to verify injection reached the artifact (make version only prints the Make variables, not what the binary embeds)
   • if possible, run one representative run-* target in a safe environment
   • Refactor mode: verify previously used critical targets still work (or provide aliases); compare target list before vs after

Rules

Target Design

• Prefer explicit targets over complex metaprogramming unless the user asks for DRY-heavy style.
• Keep artifact outputs deterministic (under bin/).
• Keep help output self-documenting via ## comments with .DEFAULT_GOAL := help.
• Map target names to cmd/ path semantics: cmd/<name> → build-<name>, cmd/<kind>/<name> → build-<kind>-<name>.
• Declare all non-file targets in .PHONY.
• Output executable bare Makefile by default (tabs for recipes, not spaces).

Build Quality

• Inject version metadata via -ldflags in build targets:

  LDFLAGS := -s -w -X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.buildTime=$(BUILD_TIME)
  

  -X only sets an existing package-level string var — -X main.version assumes var version string in package main; discover the real package/name first and use its import path if it lives elsewhere (a wrong path silently no-ops). -s -w strips the symbol table and DWARF (release builds only; keep a debug build without it).
• Default the test target to -race — it catches real data races. But -race requires CGO_ENABLED=1, a supported OS/arch, and adds ~5–10× memory / 2–20× time. Offer a genuine race-free equivalent, test-norace (go test ./... — the full suite, no race), for cgo-disabled builds and platforms without race support. Do not conflate this with test-short (go test -short ./...): -short skips testing.Short()-gated cases, so it runs a smaller set — it turns off race only as a side effect and is not a substitute for the full suite.
• CGO_ENABLED=0 is the default for pure-Go static builds and containers. For cgo projects (import "C", mattn/go-sqlite3, …) keep CGO_ENABLED=1 — and note the two collide: a -race test target cannot run under CGO_ENABLED=0.
• For reproducible release builds add -trimpath (strips local paths so the binary is checkout-location-independent) and drive buildTime from SOURCE_DATE_EPOCH. This raises reproducibility but is not absolute: git describe --dirty makes VERSION depend on tree state, so only a clean checkout with a fixed toolchain is bit-for-bit reproducible.
• Pin tool versions in install-tools for CI reproducibility.

Safety

• Fail early with clear tool-presence checks (command -v <tool>) for optional dependencies.
• ci target must mirror actual CI pipeline — developers should catch issues before push.
• Check for code generation staleness (generate-check) when go generate is used.

Go Version Awareness

Read go.mod for the go directive before composing the Makefile. Record as Go version: X.Y in the output report.

If go.mod is not found or not readable, record Go version: unknown and use conservative defaults (no version-specific features).

Monorepo Support

When the repo is a Go workspace or multi-module layout (step 1 Inspect), adapt for monorepo:

• Detect via the toolchain, not a bare file search: prefer go.work (go env GOWORK); when it exists, the modules are its use directives (go list -m run inside the workspace). Only fall back to searching for go.mod files when there is no go.work, and then exclude vendor/, testdata/, examples/, and tool-only modules.
• Per-module targets: generate test-<module>, lint-<module>, build-<module> for each module that has entrypoints
• Aggregate targets: test-all, lint-all, build-all that iterate over the workspace modules
• Per-module go mod tidy: tidy operates on a single main module — run it inside each module (for m in $(MODULES); do (cd $$m && go mod tidy); done), never once at the workspace root
• Root Makefile pattern:

# Workspace-aware: use go.work's module list when present, else a SCOPED go.mod
# search (a bare `rg go.mod` sweeps in vendor/testdata/examples).
GOWORK := $(shell go env GOWORK 2>/dev/null)
ifeq ($(GOWORK),)
MODULES := $(shell rg --files -g 'go.mod' 2>/dev/null | xargs -I{} dirname {} | grep -Ev '(^|/)(vendor|testdata|examples?)(/|$$)' | sort)
else
MODULES := $(shell go list -m -f '{{.Dir}}' 2>/dev/null)
endif

test-all: ## Run tests for all modules
	@for mod in $(MODULES); do \
		echo "=== testing $$mod ==="; \
		(cd $$mod && go test -race ./...) || exit 1; \
	done

lint-all: ## Lint all modules
	@for mod in $(MODULES); do \
		echo "=== linting $$mod ==="; \
		(cd $$mod && golangci-lint run) || exit 1; \
	done

• When the project is a single-module repo, this section does not apply — use the standard single-module workflow.
• Record Layout: monorepo (N modules) or Layout: single-module in the output report.

Anti-Patterns (DO NOT generate these)

Before writing or reviewing a Makefile, check against these common mistakes. If your output matches any of these patterns, fix it before delivering.

Missing fundamentals:

• No help target or missing ## self-documenting comments
• No .PHONY declaration for non-file targets
• No race testing at all — the default test should use -race; provide test-norace (full suite, no race) as the cgo-off / unsupported-platform equivalent. test-short runs a smaller quick set and is not a substitute.
• No -ldflags version injection in build-* targets

Naming and layout:

• Target names not matching cmd/ path semantics (e.g., cmd/consumer/sync but target is build-sync instead of build-consumer-sync)
• run-* targets leaving ad-hoc binaries in source directories instead of bin/

Reproducibility:

• install-tools using @latest for all tools in CI (pin specific versions for reproducibility; @latest is acceptable only for local dev convenience)
• Hardcoding a tool version without discovering the repo's existing pin — check CI workflows, .golangci.version / .tool-versions (asdf/mise), and any existing install-tools first; use a current compatible version (golangci-lint is now v2, module path .../v2/cmd/golangci-lint) and prefer the tool's official installer where it documents one (go install from source is explicitly not guaranteed for golangci-lint)
• ci target that diverges from the actual CI pipeline — make ci should mirror CI exactly
• Hidden assumptions about local paths or OS-specific tools (e.g., sed -i without considering macOS vs GNU differences)

Cross-compilation:

• Cross-compiling a pure-Go binary without CGO_ENABLED=0 — produces dynamically linked binaries that fail on target machines (cgo projects instead need CGO_ENABLED=1 and a cross C toolchain)
• Hardcoded GOOS/GOARCH without variable override

Code generation:

• Generated code not checked for staleness before build (missing generate-check target)

Over-engineering:

• Overly dynamic Make metaprogramming (eval/call/define) that reduces readability when explicit targets would be clearer
• Tab-vs-space issues in Makefile recipes (recipes MUST use tabs, not spaces)

Quality Improvements to Offer

• Add .DEFAULT_GOAL := help.
• Add cover-check target with a configurable threshold.
• Add tidy target for go mod tidy + go mod verify.
• Keep run-* from polluting source directories; prefer go run ./cmd/... or run from bin/.
• Pin tool versions in install-tools for CI reproducibility (see quality-guide §11).

Load References Selectively

When starting any Makefile creation or refactor task: → Run this skill's discovery script against the target repo first — bash <skill-dir>/scripts/discover_go_entrypoints.sh <project-root> — to discover cmd/**/main.go binary locations and infer project shape (single-binary vs multi-binary). Add --modules to list workspace/multi-module directories.

When writing or reviewing specific targets (build, test, lint, run, install-tools), or checking quality rules: → Load references/makefile-quality-guide.md for canonical target templates, variable conventions, .PHONY rules, self-documenting help output, and the 15-item review checklist.

When reviewing a PR that touches a Makefile: → Load references/pr-checklist.md for the fast Makefile-specific PR review checklist (target naming, portability, idempotency, CI compatibility).

When you need a complete working Makefile as a starting point or reference: → Load references/golden/simple-project.mk for a single-binary project with minimal tooling. → Load references/golden/complex-project.mk for a multi-binary project with Docker, code generation, and cross-compilation targets.

Output Contract

When generating or refactoring a Makefile, always return:

1. Mode: Create or Refactor with rationale
2. Project info: Go version (from go.mod), layout (single-module or monorepo (N modules)), entrypoints discovered
3. Changed files
4. New/updated targets
5. Deprecated/aliased targets (Refactor mode — list old name → new name mappings)
6. Assumptions or missing tools
7. Validation commands executed with pass/fail status

Example Output (Create mode, single-binary)

### Mode
Create — no existing Makefile found

### Project info
- Go version: 1.23 (from go.mod)
- Layout: single-module
- Entrypoints: cmd/api

### Changed files
- `Makefile` (created)

### New targets
help, build-api, build-all, run-api, fmt, fmt-check, tidy,
test, cover, cover-check, lint, ci, version, install-tools,
check-tools, clean

### Deprecated/aliased targets
(none — new Makefile)

### Assumptions
- golangci-lint will be installed via `make install-tools`
- Version info injected into `main.version`, `main.commit`, `main.buildTime`

### Validation
✓ make help       — 16 targets listed
✓ make test       — all tests pass with -race
✓ make build-api  — binary at bin/api
✓ ./bin/api --version — version=v0.1.0-dirty commit=abc1234 buildTime=… (injection reached the artifact)

Self-Validation

Run scripts/run_regression.sh to verify skill integrity:

• Contract tests: structure of SKILL.md, quality guide, golden examples, discovery script
• Golden review tests: all defect/FP fixtures' rules covered in docs
• Coverage matrix: see scripts/tests/COVERAGE.md