makefile

Makefile Skill

Overview

Makefile template generation and validation tool. Supports two modes:

1. Generate — Generate a standardized Makefile template based on the project type
2. Validate — Check whether an existing Makefile conforms to the specification

Core principles:Comments are documentation,make is the entry point.

Mode Selection

用户说 "创建/生成 Makefile" → Generate 模式
用户说 "validate/检查/lint Makefile" → Validate 模式
用户未明确 → 询问选择

---

Generate mode

Template Selection

Select a template based on the project type. If the user does not specify one, auto-detect by the following means:

1. Check go.mod → Go template
2. Check package.json → Node template
3. Check pyproject.toml or setup.py → Python template
4. Check docker-compose.yml → Docker template
5. Check pnpm-workspace.yaml or lerna.json → Monorepo template
6. Cannot detect → ask the user to choose

Available Templates

Template	File	Applicable scenario
Go	assets/Makefile.go.tmpl	Go project, includes build/test/lint/docker
Node	assets/Makefile.node.tmpl	Node.js/TypeScript, auto-detects the package manager
Python	assets/Makefile.python.tmpl	Python project, includes venv/pytest/ruff
Docker	assets/Makefile.docker.tmpl	Docker Compose project, includes up/down/logs
Monorepo	assets/Makefile.monorepo.tmpl	Multi-package repository, supports filter for single-package operations

Generate Workflow

1. Detect or ask for the project type
2. Read the corresponding template assets/Makefile.<type>.tmpl
3. Adjust variables according to the project's actual situation (APP_NAME, ports, etc.)
4. Write to Makefile
5. Prompt the user to run make to verify the help output

Convention

## 描述 is written on the same line as the target,make(no arguments) automatically outputs all targets and descriptions.

.DEFAULT_GOAL := help

help: ## 显示帮助信息
	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | sed 's/:.*##/:/' | awk -F: '{gsub(/^ /, "", $$2); printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'

build: ## 编译项目
	go build ./...

Rules

1. .DEFAULT_GOAL := help — no arguments make is equivalent to make help
2. .PHONY Declare all non-file targets
3. ## The comment must be on the same line as the target, format:target: deps ## 描述
4. Use Chinese or English for descriptions, keep it consistent within the project
5. help Do not change the grep/awk pipeline at will
6. Targets with dependencies:setup-db: create-network ## 启动数据库

---

Validate mode

Trigger

用户说: "validate Makefile" / "检查 Makefile" / "lint Makefile"

Workflow

1. Read the target Makefile (default is the current directory, or a user-specified path)
2. Check item by item according to references/validation-rules.md rules
3. Output a formatted report

Validation Rules Summary

ERROR (must be fixed):

• E01: .DEFAULT_GOAL := help exists
• E02: help target exists
• E03: help uses ## parsing
• E04: every non-file target has a ## comment
• E05: ## comment is on the same line
• E06: ## has a space after
• E07: .PHONY declaration is complete
• E08: indentation uses Tab

WARNING (recommended to fix):

• W01: explicitly declare SHELL
• W02: clean target exists
• W03: variables use :=
• W04: long commands are reasonably wrapped
• W05: help pipeline includes ANSI highlighting
• W06: targets grouped by function

INFO (best practices):

• I01: common target coverage (build/test/lint/clean)
• I02: VERSION obtained from git
• I03: Docker target naming is consistent
• I04: avoid hardcoded paths

Output Format

Makefile Validation Report
══════════════════════════

ERROR (2)
  E01  .DEFAULT_GOAL := help 未设置
  E04  target 'deploy' 缺少 ## 注释

WARNING (1)
  W01  未声明 SHELL 变量

INFO (1)
  I01  建议添加 lint target

Result: FAIL (2 errors, 1 warning, 1 info)

Validate Completion

After Validate completes:

1. Display the report
2. If there are ERRORs, ask the user whether to auto-fix
3. After auto-fixing, re-validate to confirm it passes

---

Common Mistakes

Error	Correct
## Comment on a separate line above the target	## Written on the same line as the target
Missing .DEFAULT_GOAL := help	must be set
## no space after	## 描述，## there must be a space after
help pipeline uses awk -F: split into 3 fields	use sed 's/:.*##/:/' normalize first
recipe indented with spaces	must use Tab
.PHONY missing target	all non-file targets must be declared