Your Agent Needs a Justfile
Make is from the 1970s. It works, but the syntax has that special flavor of "designed before we knew what we were doing." Tab sensitivity. Implicit rules. The .PHONY incantation. Every new repo, I'd write another Makefile, fight the same battles, forget the same footguns.
Then I found just — a command runner that's like Make but, you know, from this century. Written in Rust, fast, with a sane syntax that doesn't punish you for using spaces. You write a justfile, define recipes for the commands you use all the time, and just build does what you'd expect.
But here's where it gets interesting for agent workflows.
Every repo has its own incantations. This one uses npm run build. That one is cargo build --release. The Go project has a ./scripts/deploy.sh that nobody documented. When Claude starts working on a repo, it has to discover all this. It explores. It guesses. Sometimes it guesses wrong, and now you're debugging a bad deploy command instead of shipping features.
The justfile solves discovery. One file, one location, just --list shows everything the repo knows how to do. I tell Claude to check the justfile first, use existing recipes, and add new ones when it finds commonly-needed commands that aren't there yet. The justfile becomes a living index of repo operations — curated by both human and agent. In your AGENTS.md file, tell your agent to "Discover available commands with just --list."
This is the same desire paths principle from Beads: agents already want a single place to discover what a repo can do. The justfile is that place. You're not fighting the model's intuitions — you're paving them.
The benefits compound:
- Consistency: same command every time, no drift
- Discoverability:
just --listis self-documenting - Token efficiency: agent doesn't explore or guess, just executes
- Human DX too: new team members run
just --listinstead of reading stale docs
Documentation drifts. Your README says npm run build but someone added a lint step last month and forgot to update it. The justfile can't drift the same way — if the recipe is wrong, it breaks, and you fix it. It stays accurate out of necessity. Onboarding docs are aspirational; justfiles are operational.
There's more to my repo setup now — mise for tool versioning, direnv for environment injection — but that's another post. For now: standardize the discovery surface. Give your agent (and yourself) one place to look.