Justfiles

Justfiles

Purpose

Use this skill to design Justfiles that make project workflows discoverable, repeatable, safe, and easy for humans and AI agents to run.

just is a command runner, not a build system. Use it to name and orchestrate project commands such as setup, test, lint, format, build, run, docs, database, container, CI, release, and deployment workflows. Do not use it as a replacement for Make-style file freshness, a package manager, a secret store, a production orchestrator, or large application logic.

Prefer a Justfile when the project needs a small, inspectable command surface that works across tools and languages. Prefer external scripts when logic is long, stateful, hard to quote, or needs unit tests. Prefer package-manager scripts for package-local workflows that should remain inside that package.

Source and version rules

• Treat the official manual, upstream repository, and local just --version as authoritative. Use community examples only as heuristics.
• Do not invent syntax. Verify uncommon features against current docs before using them.
• Prefer stable, widely available syntax. Before using modules, [script], argument metadata, alternate-shell attributes, or other advanced behavior, load references/version-and-advanced-syntax.md and confirm the repository's declared or installed minimum version.
• Inspect shell() expressions before --dry-run; support for non-executing dry runs is version-sensitive.

Agent workflow

1. Inspect before editing:
   • Root Justfile, .justfile, justfile, and files under just/**.
   • External scripts wrapped by recipes, commonly scripts/** or scripts/just/**.
   • Current command surface with just --list --unsorted and just --summary.
   • Local version with just --version when using version-sensitive syntax.
2. Clarify the workflow contract: recipe users, expected inputs, prerequisites, side effects, environment variables, safety level, and verification command.
3. Keep public recipes human-first: names should describe workflows, doc comments should explain intent, and defaults should help users discover commands.
4. Use the smallest safe implementation:
   • Simple one-liners stay inline.
   • Shell-specific or multi-line logic uses a shebang/script recipe or external script.
   • Reusable or testable logic moves to an external script with a thin recipe wrapper.
5. Preserve behavior while refactoring. Prefer aliases, wrapper recipes, or documented deprecations over silent renames of established commands.
6. Validate parse, listing, formatting, dry runs, and affected recipes before reporting completion.

Structure and organization

• Put high-value public workflows near the top or make them prominent through groups and doc comments.
• Use lowercase kebab-case recipe names such as test-backend, db-reset, or release-preview. Prefer verbs for actions and nouns for information recipes: build, test-web, docs-open, db-status.
• Use short variables for shared constants, not hidden configuration systems. Keep names lowercase with underscores, for example root := justfile_directory().
• Use parameters for deliberate user choices. Give safe defaults when they are genuinely safe.
• Use aliases for common abbreviations only when they improve ergonomics without hiding intent: alias t := test.
• Mark helpers private with [private] or a leading _; keep them out of normal listings unless users should call them directly.
• Avoid surprising side effects in default, list, status, check, or info recipes. Destructive, remote, production, or credentialed recipes must be explicit.

Comments, docs, and listings

• A comment immediately above a recipe appears in just --list. Use concise imperative summaries: # Run backend tests.
• When combining doc comments with attributes, put the doc comment first and the attributes immediately above the recipe.
• Use [doc('...')] only when the visible description should differ from nearby source comments. Use [doc] to suppress noisy helper documentation.
• Mention parameters, examples, prerequisites, environment variables, side effects, and safety concerns near the recipe when they affect correct use.
• Keep just --list scannable. Put long tutorials in project docs and link or reference them from a short recipe comment.
• Make the default useful. For broadly compatible Justfiles, use a default recipe that lists workflows. If the project pins just 1.52+, set default-list := true is also available.

Groups

Use groups for non-trivial Justfiles unless there is a clear reason not to. They make just --list, just --groups, and agent inspection more navigable.

• Group by workflow or domain: setup, quality, dev, docs, db, containers, ci, release, deploy, maintenance, internal.
• Keep group names stable, short, and user-facing. Avoid clever names.
• Put helper recipes in internal or mark them private.
• A recipe may belong to multiple groups when it is useful in both views, but do not over-tag.

root := justfile_directory()

# List available workflows.
[group('help')]
default:
    @just --list --unsorted

alias t := test

# Format source files.
[group('quality')]
fmt:
    cargo fmt --all

# Run lints.
[group('quality')]
lint: fmt
    cargo clippy --all-targets --all-features -- -D warnings

# Run tests; pass extra Cargo arguments after `--`.
[group('quality')]
test *args='':
    cargo test {{ args }}

# Run the local verification lane.
[group('quality')]
verify: lint test

# Preview deployment without changing remote state.
[group('ops')]
deploy-plan env='staging':
    "{{ root }}/scripts/just/deploy" plan '{{ env }}'

# Deploy to the selected environment.
[confirm]
[group('ops')]
deploy env='staging': (deploy-plan env)
    "{{ root }}/scripts/just/deploy" apply '{{ env }}'

[group('internal')]
[private]
_need tool:
    command -v '{{ tool }}' >/dev/null

Advanced Structure And Shells

Start with one root Justfile and portable one-line recipes. Load references/version-and-advanced-syntax.md when splitting with imports/modules, changing shells, adding shebang recipes, or using version-sensitive syntax. Keep complex, stateful, or testable logic in an external script with a thin recipe wrapper.

Safety and human-agent collaboration

• Public recipes should be deterministic, minimally interactive by default, and safe to run in local development.
• Add dry-run, preview, check, status, or info recipes before destructive apply recipes: deploy-plan before deploy, db-reset-preview before db-reset-danger.
• Use [confirm] for destructive or remote operations, but do not rely on a prompt as the only safety control. Also validate environment, target, branch, credentials, and production safeguards in scripts or recipe logic.
• Never print secrets. Dotenv-loaded values are environment variables referenced as $NAME, not Just variables like {{NAME}}.
• Treat just --evaluate output as sensitive because it prints variable values, including values derived from the environment or command expressions. Evaluate only named, known non-sensitive variables when needed; otherwise skip it and report why. Redact captured output.
• Make CI and agent workflows explicit: recipes for setup, fast checks, full verification, formatting, linting, generated-code refresh, and drift checks should be easy to discover.

Workflow ownership routing

• Load script-engineering when interpreter availability, script-language selection, external script design, or script testing is material; keep this skill focused on recipe syntax, discoverability, parameters, orchestration, and Just-specific validation.

• Load ci-release-engineering when a change affects hosted pipeline triggers, jobs, permissions, artifacts, or automated release behavior; keep this skill focused on the Just recipe the pipeline invokes.

• Load container-engineering when a change affects Dockerfile, OCI image, or Compose semantics; keep this skill focused on container command wrappers and recipe design.

Security and supply-chain routing

• Load dependency-supply-chain-review when recipes change dependency updates, package-manager setup, install scripts, curl-piped commands, one-off CLIs, CI/bootstrap tooling, generated code, container/toolchain pins, or other provenance/advisory surfaces.
• Load threat-modeling when recipes introduce new credentialed remote operations, deployment/release/data-export flows, background jobs, external-service trust boundaries, or privileged/destructive command surfaces that need actors, assets, and data flows mapped.
• Load security-review for concrete recipe logic that handles secrets, auth, command execution, paths, production targets, or other implemented trust boundaries.
• Use security-review-evidence when recipe validation collects sensitive command output, logs, or artifacts.

Refactoring and maintenance

Audit an existing Justfile for:

• Duplicate commands that should become variables, helper recipes, or scripts.
• Ambiguous names such as run2, new-test, or fix.
• Hidden dependencies on local tools, directories, services, or environment.
• Unsafe defaults, unguarded destructive operations, production targets, or secret exposure.
• Recipe bodies that should be external scripts.
• Missing doc comments, groups, aliases, or default/list discoverability.
• Quoting bugs, unportable shell assumptions, and path assumptions.
• Recursive just calls that accidentally recompute variables or rerun setup.

Refactor in behavior-preserving steps. Keep command names stable when other docs, CI, hooks, or users may call them. After edits, inspect list output because that is the user and agent interface.

Methodology alignment

• BDD: organize public recipes around observable workflows users ask for, such as setup, test, release-preview, or deploy-plan.
• DDD: when workflows map to domain concepts, group them by bounded context or domain lifecycle rather than by implementation detail.
• TDD: make test, lint, format, and verification recipes fast, repeatable, and easy to run while iterating. Prefer narrow recipes plus a documented full lane.

Apply these pragmatically; do not force methodology labels into simple command runner maintenance.

Common pitfalls

• Treating Justfiles like Makefiles with file targets or freshness semantics.
• Forgetting ordinary recipes execute line-by-line, so multi-line shell state may not persist unless using continuations, shebang/script recipes, or a script.
• Leaving {{parameter}} unquoted when spaces or shell metacharacters are possible.
• Using .env values as {{JUST_VARIABLES}} instead of shell $VARIABLES.
• Hiding important workflows in private helpers or external scripts without public wrapper recipes.
• Adding interactive prompts to default CI or agent recipes.
• Depending on newest just features without checking the local/pinned version.
• Letting imports/modules make the command surface harder to discover.
• Refactoring recipe names without updating docs, CI, hooks, and scripts.

Acceptance checklist

Before finishing Justfile work, verify:

• just --version is compatible with any syntax you added.
• just --list --unsorted, just --groups, and just --summary show a clear, navigable command surface.
• just --show <recipe> and, after checking version and shell() expressions, just --dry-run <recipe> [args...] match intended behavior for changed recipes.
• Named, known non-sensitive variables resolve with just --evaluate <variable> when that check is needed; blanket evaluation is avoided when values may be sensitive.
• just --fmt --check passes when the repository uses just formatting; note that formatting behavior is not part of just's compatibility guarantee.
• Affected recipes or their wrapped scripts were actually run when safe, or their non-execution is explicitly justified.
• Documentation, CI, hooks, and references to renamed or moved recipes are updated.
• Destructive, remote, production, and secret-sensitive workflows have preview, confirmation, environment validation, and redacted output.