Software Practices
Josh McKinney

Software-change guidance for humans and coding agents: scope, code structure, Rust APIs, documentation, tests, review, and source control.

Guides by work area
Guides

Work areas

01Change scope and handoffScope, review shape, validation depth, and handoff.02Rust reviewAPI shape, module ownership, docs, tests, dependencies, and release risk.03Code shapeLive context, cohesion, and behavior-preserving source moves.04DocumentationTask-first, lintable docs that stay close to the behavior they describe.05Coding-agent workObjectives, boundaries, context, tools, proof, and reusable feedback loops.06JJ workflowReviewable, recoverable local changes aligned with jj source control.
Reference

Guidance types

Guides

Change scope, code shape, Rust review, documentation, agent work, and jj.

Rules

Short instructions for documentation, Rust, testing, review, source control, and agents.

Patterns

Repeatable situations and moves that can be cited in review.

Principles

Rationale behind related rules and patterns.

Mechanisms

Commands, checks, generators, and workflows used by the rules and guides.

Agents

Copyable instruction packs and rule packs for coding agents.

Tags

Documentation, Rust, testing, review, jj, and other topic indexes.

References

Official documentation, engineering guidelines, design sources, and planning records.

Review comments and repository setup

Review comments

Link a named rule or pattern instead of re-explaining the same preference in every PR.

Project setup

Copy the downstream `AGENTS.md` template and rule pack, then adapt local checks and constraints.

Agent instructions

Agent snippets give coding tools compact instructions with enough context for tradeoffs.