go-makefile-writer Skill Design Rationale¶

go-makefile-writer is a design and refactoring framework for root-level Makefiles in Go repositories. Its core idea is: a Makefile is not just a pile of go build and go test commands; it is the layer that turns repository entrypoints, target naming, version injection, tool installation, CI alignment, and compatibility constraints into a stable, readable, evolvable command surface. That is why the skill links Create/Refactor mode selection, repository discovery, target planning, Go-version awareness, validation, and structured reporting into one explicit path.

1. Definition¶

go-makefile-writer is used for:

• creating a new root Makefile for a Go repository,
• refactoring an existing Makefile with minimal disruption,
• standardizing entrypoints for build, run, test, lint, cover, ci, version, and clean,
• planning predictable per-binary targets from the cmd/ layout,
• bringing tool installation, code generation, Docker, and cross-compilation into a single convention set,
• preserving compatibility aliases during refactors so existing usage does not break abruptly.

Its output is not only the Makefile content. It also includes:

• the selected mode and its rationale,
• Go version, repository layout, and discovered entrypoints,
• new or updated targets,
• deprecated or aliased targets,
• assumptions and missing tools,
• validation commands actually executed and their results.

From a design perspective, it is closer to a Go repository command-surface designer than to a tool that merely emits Make syntax.

2. Background and Problems¶

The main problem this skill addresses is not "people do not know how to write Makefiles." The deeper issues in Go-repository Makefiles are usually these:

• target naming drifts away from repository entrypoint structure,
• local commands, CI behavior, tool installation, and version injection all evolve separately,
• refactors optimize the file but break the people and scripts that already depend on it.

Without a clear framework, the most common failures cluster into eight categories:

The design logic of go-makefile-writer is to make "what are this repository's real entrypoints and compatibility constraints?" explicit before deciding "how should the Makefile be organized?"

3. Comparison with Common Alternatives¶

It helps to compare the skill with a few common alternatives:

Its value is not only that it can generate a runnable Makefile. Its value is that it turns Makefile design from a loose command collection into a standardized repository entrypoint layer.

4. Core Design Rationale¶

4.1 It Separates Create and Refactor Up Front¶

The first step in go-makefile-writer is not writing content. It is selecting Create or Refactor.

This is a very important design choice because:

• a new Makefile has no compatibility burden, so a complete target system can be generated,
• an existing Makefile introduces a different problem: not "can this be made prettier?" but "can this be improved without breaking the ways people already use it?"

That is why Refactor mode explicitly requires:

• minimal diffs,
• preserving useful existing targets,
• keeping aliases when names change,
• comparing target lists before and after.

This shows that the skill does not treat generation and refactoring as the same task. It treats compatibility cost as part of the design itself.

4.2 Entrypoint Discovery Is the Preferred First Step¶

The skill prefers scripts/discover_go_entrypoints.sh as the first discovery path, and falls back to rg-based inspection when the script cannot run. Its goal is to extract:

• kind,
• name,
• target_name,
• dir,

from cmd/**/main.go.

The value of this design is that target naming becomes repository-driven instead of improvised. In particular, layouts such as:

• cmd/api/main.go,
• cmd/consumer/sync/main.go,
• cmd/cron/cleanup/main.go,

map systematically to:

• build-api,
• build-consumer-sync,
• build-cron-cleanup.

The evaluation's largest single-item delta came from exactly this layer: without-skill, the single-binary case easily collapses back to generic build / run; with-skill, naming remains aligned with cmd/ structure.

4.3 Naming Convention Is a Core Rule, Not a Style Preference¶

go-makefile-writer explicitly maps target names from cmd/ semantics:

• cmd/<name> → build-<name> / run-<name>,
• cmd/<kind>/<name> → build-<kind>-<name> / run-<kind>-<name>.

This is not merely a stylistic preference. It is an expansion strategy. If a single-binary repository starts with build / run, then once the repo grows into multiple binaries, two problems appear:

• the old names lose semantic value,
• CI scripts, shell usage, and team habits all have to be renamed.

So the naming rule does not mainly solve "cleaner style." It solves "the repository can grow from simple to complex without forcing a naming reset."

4.4 The Core Target Set Is Standardized¶

During target planning, the skill establishes a core target set such as:

• help,
• fmt,
• tidy,
• test,
• cover,
• lint,
• ci,
• version,
• clean,

and then adds common enhancements when the repository actually needs them, such as:

• fmt-check,
• cover-check,
• install-tools,
• check-tools,
• generate / generate-check,
• swagger,
• test-integration,
• bench,
• docker-build / docker-push,
• build-linux / build-all-platforms.

The value of this layer is that it turns Makefiles from "whatever commands this repo happened to collect" into "predictable team entrypoints." The evaluation advantage around ci, tidy, and install-tools is fundamentally a result of this standardized target set.

4.5 It Emphasizes install-tools and Version Pinning So Strongly¶

In many baseline Makefiles, the lint target either:

• omits tool installation entirely,
• or auto-installs with go install ...@latest during execution.

go-makefile-writer is deliberately strict about reproducibility, so it strongly prefers patterns such as:

• a separate install-tools entrypoint,
• exact version pinning in CI or other reproducibility-sensitive paths,
• a check-tools target or equivalent clear failure guidance for missing tools.

This matters because it solves CI reproducibility, not just one-off local usability. The evaluation report shows clear separation in this area in most scenarios, which also reveals one of the skill's biggest strengths: it knows that some targets exist primarily to support repeatable engineering workflows, not just runnable commands.

4.6 The ci Target Is Treated as a First-Class Entry Point¶

The skill treats ci not as an optional alias, but as the canonical local mirror of the real CI pipeline.

That usually means it should include at least:

• fmt-check,
• lint,
• test,
• cover-check,

and sometimes also:

• generate-check.

This is a mature design choice because make ci solves a concrete problem: can a developer reproduce the CI gate locally before pushing? It is not decorative. It is the bridge between local development and CI enforcement.

4.7 Version Injection Must Exist in All Build Targets¶

go-makefile-writer explicitly requires -ldflags version injection for:

• version,
• commit,
• buildTime,

and requires this to apply across build targets.

This solves binary traceability. Many baseline Makefiles can build a runnable program, but still fail to produce artifacts that are easy to trace during release and incident work. The point here is not to make the build command more elaborate; it is to make the output artifact accountable.

4.8 Refactor Mode Preserves Aliases and Target Diffs¶

When operating on an existing Makefile, the skill requires:

• snapshotting the old target list first,
• verifying that critical old targets still work or have aliases,
• reporting deprecated or aliased targets explicitly.

This is a strong sign of evolution-aware design. Many Makefile refactors fail not because the new design is bad, but because:

• shell scripts still call old targets,
• CI jobs still reference old names,
• documentation and habits lag behind.

So in Refactor mode, the skill protects more than file contents. It protects the repository's surrounding execution ecosystem.

4.9 Go Version Awareness Is a Separate Rule Layer¶

The skill requires reading the go directive from go.mod and making conservative decisions based on it. For example:

• < 1.16 changes tool-install strategy,
• < 1.18 means no go build -cover,
• >= 1.21 may justify integration-coverage-related targets,
• >= 1.22 has no direct Makefile behavior change but should still be recorded in output.

This layer is worth preserving even though the evaluation scenarios did not fully stress it. The reason is simple: Makefiles are long-lived assets, and version-sensitive assumptions become costly later if they are baked in incorrectly. The skill is showing maintenance awareness here, not just immediate task completion.

4.10 Monorepo Support and Explicit Targets Coexist¶

go-makefile-writer supports monorepo or multi-module layouts, yet also explicitly resists over-dynamic Make metaprogramming.

These two ideas are not in conflict. The real design position is:

• when the repository gets more complex, add aggregate targets and module-level targets,
• but when explicit targets are clearer, do not sacrifice readability for DRY-heavy eval/call/define tricks.

The complex evaluation scenario validated this: without-skill naturally drifted toward dynamic templating, while with-skill stayed more stable around explicit per-binary targets. The optimization target is readability and debuggability, not Make cleverness.

4.11 Validation-Bound Output Contract¶

go-makefile-writer requires reporting:

• mode,
• Go version / layout / entrypoints,
• changed files,
• new / updated targets,
• deprecated / aliased targets,
• assumptions / missing tools,
• validation commands executed.

It also requires actually running:

• make help,
• make test,
• one representative build-*,
• make version,

and, when reasonable:

• a run-* target,
• make lint,
• make ci.

The value here is that "write a Makefile" becomes a validated engineering change, not just a text-generation task. The evaluation also shows this clearly: baseline models can often produce a decent Makefile, but they usually do not add the auditable delivery layer around it.

5. Problems This Design Solves¶

Combining the current SKILL.md, quality guide, golden examples, discovery script, and evaluation report, the skill addresses the following problems:

6. Key Highlights¶

6.1 It Treats the Makefile as the Repository's Standard Entry Surface¶

This is the core positioning of the skill. A Makefile is not just a command container; it is the shared contract for build, test, lint, run, and ci entrypoints.

6.2 cmd/-Semantic Naming Is One of Its Strongest Differentiators¶

The evaluation's largest single-item delta came from this layer. The rule is simple, but its long-term scaling value is high.

6.3 Its Compatibility Discipline in Refactor Mode Is Strong¶

Minimal diffs, target aliases, and before/after target comparisons show that it is not "rewriting" in refactor scenarios; it is doing controlled convergence.

6.4 It Has Strong Engineering Awareness of CI Reproducibility¶

install-tools, version pinning, ci alignment, and check-tools work together to ensure the Makefile is not merely locally usable, but reproducible over time.

6.5 The Combination of Golden Examples and Anti-Patterns Is Effective¶

The skill gives positive templates and also clearly says which Make techniques to avoid. That dual-sided constraint is stronger than providing templates alone.

6.6 The Current Version Adds Value Mainly Through Constraints, Not Just Generation¶

The evaluation most strongly validates its value in naming convention, tool pinning, ci targets, and Output Contract structure. At the same time, the current skill also incorporates Go-version awareness, monorepo support, and backward compatibility. That makes it closer to a Makefile design standard than to a simple generator.

7. When to Use It — and When Not To¶

8. Conclusion¶

The real strength of go-makefile-writer is not that it can produce a Makefile with .PHONY. It is that it systematizes the engineering judgments most often skipped in Go repository command design: identify entrypoints and layout first, then choose naming rules, a standard target set, version-injection and tool-installation strategy, and in refactor scenarios also preserve minimal diffs and backward compatibility, and finally explain the result through structured output plus real validation.

From a design perspective, the skill embodies a clear principle: a good Makefile is not one that contains the most commands; it is one whose entrypoints stay stable, whose semantics stay clear, whose CI usage stays reproducible, and whose structure does not collapse when the repository evolves. That is why it is especially well suited to creating and converging Go Makefiles.

9. Document Maintenance¶

This document should be updated when:

• the Execution Modes, Workflow, Rules, Go Version Awareness, Monorepo Support, Output Contract, or Anti-Patterns in skills/go-makefile-writer/SKILL.md change,
• key rules in skills/go-makefile-writer/references/makefile-quality-guide.md change around target sets, tool pinning, ci behavior, version injection, or backward compatibility,
• the standard structure reflected in skills/go-makefile-writer/references/golden/simple-project.mk or golden/complex-project.mk changes,
• the output fields, classification logic, or target-suffix generation logic in skills/go-makefile-writer/scripts/discover_go_entrypoints.sh change,
• key supporting conclusions in evaluate/go-makefile-writer-skill-eval-report.md or evaluate/go-makefile-writer-skill-eval-report.zh-CN.md change.

Review quarterly; review immediately if the naming rules, refactor compatibility strategy, or golden examples of go-makefile-writer change substantially.

10. Further Reading¶

• skills/go-makefile-writer/SKILL.md
• skills/go-makefile-writer/references/makefile-quality-guide.md
• skills/go-makefile-writer/references/golden/simple-project.mk
• skills/go-makefile-writer/references/golden/complex-project.mk
• skills/go-makefile-writer/scripts/discover_go_entrypoints.sh
• evaluate/go-makefile-writer-skill-eval-report.md
• evaluate/go-makefile-writer-skill-eval-report.zh-CN.md