go-makefile-writer

Go Makefile Writer

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

Quick Reference

If you need to…	Go to
Create a Makefile from scratch for a new Go project	§Execution Modes → Create + §Workflow
Refactor or update an existing Makefile (minimal-diff)	§Execution Modes → Refactor
Decide which targets to include (build, test, lint, ci…)	§Workflow (Plan targets)
Get a complete working Makefile example to start from	Load references/golden/simple-project.mk or complex-project.mk
Check quality rules, variable conventions, .PHONY requirements	Load references/makefile-quality-guide.md
Review a Makefile PR quickly	Load references/pr-checklist.md
Handle a monorepo or multi-module Go repo	§Monorepo Support

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

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

2. Inspect project structure:

   • discover entrypoints (package main, wherever it lives) 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)
   • read the script's exit status before its output. 0 means the query was complete and what you got is the whole answer — including an empty answer, which then genuinely means "library, no programs". 4 means the query was incomplete: empty output is unknown, not library. 2 is a bad root, 3 (with --modules) is zero modules. The stderr diagnostic names the toolchain error to fix
   • the script emits 5 tab-separated fields — kind name target_name dir confidence. confidence is not decoration. confirmed means go list reported the package's name as main, and can become a build target directly. candidate means the toolchain could not be asked about that subtree and the row is a filename guess — list those to the user for confirmation instead of generating targets from them, and say in your output that they are unconfirmed
   • if the script cannot run at all, fall back to find cmd -name main.go -type f, but treat every result as a candidate: a file named main.go may declare any package, and a program's file may be named anything
   • 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 real path means a go.work workspace (its modules are go list -m), while the literal string off means workspace mode was disabled and must be treated as "no workspace", not as a path. 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.