Justfile Development

Workflows for authoring, reviewing, planning, and updating justfiles with the just command runner.

When to Use

• Creating a new justfile for a project
• Adding or modifying recipes
• Reviewing a justfile for quality issues
• Planning which recipes a project needs
• Upgrading a justfile as a project matures
• Converting a Makefile to a justfile
• Setting up monorepo module structure

Workflows

Author

When creating a new justfile or adding recipes.

New Justfile Scaffold:

set shell := ["bash", "-cu"]

default:
    @just --list

# =============================================================================
# Development
# =============================================================================

# Build the project
[group('dev')]
build:
    <build-command>

# =============================================================================
# Testing
# =============================================================================

# Run test suite
[group('test')]
test:
    <test-command>

# =============================================================================
# Code Quality
# =============================================================================

# Format code
[group('lint')]
fmt:
    <fmt-command>

# Run linter
[group('lint')]
lint:
    <lint-command>

# =============================================================================
# Utilities
# =============================================================================

# Remove build artifacts
[group('util')]
[confirm('Remove all build artifacts?')]
clean:
    <clean-command>

Recipe Writing Rules:

Adding Recipes to Existing Justfiles:

1. Identify the correct group (see Standard Groups below)
2. Place recipe near related recipes in the same section
3. Add doc comment
4. Add [group] attribute
5. If destructive, add [confirm]

Review

Use this checklist when reviewing justfiles.

## Justfile Review

- [ ] `set shell` declared at top
- [ ] All recipes grouped with `[group('name')]`
- [ ] Every recipe has a doc comment
- [ ] No ungrouped recipes (except `default`)
- [ ] Private helpers prefixed with `_`
- [ ] Destructive recipes use `[confirm]`
- [ ] No `cd` usage (use `[working-directory]`)
- [ ] No `&&` chaining (use dependencies or separate lines)
- [ ] No secrets in justfile (env vars or `op://`)
- [ ] `default` recipe shows `just --list`
- [ ] Section separators between groups
- [ ] Recipe names are kebab-case
- [ ] No monolithic recipes (compose from focused ones)
- [ ] Parameters preferred over env vars for inputs

Common Issues:

Plan

Use when deciding what recipes a project needs.

3-Question Assessment:

Recipe Sets by Project Type:

Decision: Single File vs Modules:

Convert

When migrating from a Makefile to a justfile.

Steps:

1. Map targets to recipes (all recipes are phony — no .PHONY needed)
2. Add set shell := ["bash", "-cu"] at top
3. Add default recipe with @just --list
4. Group recipes with [group('name')] and add section separators
5. Add doc comments above each recipe
6. Fix anti-patterns (see translations below)
7. Add [confirm] to destructive recipes
8. Validate: just --list shows grouped, documented recipes

Makefile → just Translations:

Update

When upgrading an existing justfile.

Maturity Progression:

YAGNI: Only add levels you currently need. Reassess when project scope changes.

Module Migration:

When a justfile exceeds ~20 recipes, consider splitting:

1. Create just/ directory
2. Move related recipes to just/<group>.just
3. Add import? "just/<group>.just" to root justfile
4. Or use CDN: mod name "https://just.arusty.dev/modules/<name>.just"

Quick Reference

Standard Groups

Essential Syntax

Common Functions

aRustyDev Conventions

• Shell: always set shell := ["bash", "-cu"]
• CDN modules from just.arusty.dev
• Local modules in just/ with import?
• Gist templates via just apply-gist (see gist-templates rule)
• KuzuDB recipes follow graph-data-pattern rule

Language Patterns

Quick lookup — see references/recipe-patterns.md for full details.

See Also

• references/syntax-quick-ref.md — full syntax reference
• references/recipe-patterns.md — recipe patterns by category and language
• references/module-system.md — module system deep dive
• references/maturity-model.md — maturity assessment details
• examples/rust-project.just — complete Rust CLI/lib justfile
• examples/monorepo-root.just — monorepo router pattern
• examples/arustydev.just — aRustyDev conventions with gist templates
• tables/standard-groups.md — group definitions and ordering
• tables/language-recipes.md — Rust/Go/TS/Python recipe matrix