Makefile Discipline (Symfony)

Use when

• The project's CLAUDE.md says "all commands via Make" (and the session hook confirmed runner_type = make).
• Adding a new target (test scenario, deploy step, scaffold helper, etc.).
• Renaming or removing an existing target.
• make help shows weird/duplicate targets and you need to know which file owns them.
• A custom target was lost after a boilerplate update.

Default workflow

1. Inspect the orchestration root for Makefile and Makefile-solution.
2. Determine which file is the framework (read-only) and which is solution (editable). Heuristic:
   • If boilerplate_recipe.yml exists at the root → it's a boilerplate; Makefile is framework, Makefile-solution is solution.
   • If Makefile includes Makefile-solution → same split.
   • If only Makefile exists → it's both. Edit freely but follow conventions.
3. Walk $(MAKEFILE_LIST) (read the includes — typically docker/<service>/Makefile) to see all aggregated sources.
4. Add new targets to Makefile-solution (when present) or to a thematic section of Makefile. Always with ##@ Group headers and ## helptext per target.
5. Run make help after the change — your target must appear with the right group + helptext.
6. Run make -n <target> to dry-run before committing.

Guardrails

• Never edit the framework Makefile when Makefile-solution exists — the boilerplate regenerates it.
• Never use cd <dir> && cmd as a target body — use the project's idiomatic Docker wrapper ($(call run_in_php_project,...) or $(php) <cmd> or make console <cmd> recursively).
• Never hardcode service names (docker compose exec php ...) — read them from conf/.env.* variables that the Makefile already exports.
• Targets that mutate state (migrations, fixtures, prod ops) must be idempotent and never assume a fresh container.

Progressive disclosure

• This file = editing posture + checklist.
• reference.md = full pattern catalog (help-target awk script, MAKECMDGOALS parsing, wildcard $(ENV_DIR).env* env injection, COMPOSE_FILE aggregation, worktree-aware COMPOSE_PROJECT_NAME, $(call run_in_php_project,$1) idiom, anti-patterns).

Output contract

• New/modified target in the right file (solution if split, otherwise the main Makefile).
• make help reflects the change with the right group + helptext.
• make -n <target> shows a sensible plan; make <target> runs green.
• The change does not edit the framework Makefile when a solution file exists.

References

• reference.md
• gerard:runner-selection — sister skill (which file/runner to call)
• hooks/session-start.sh — surfaces makefile.primary, makefile.solution_file, makefile.targets, makefile.is_boilerplate_smile