Skip to content

Dev Environment & Conventions

Home / Guides & Runbooks / Dev Environment & Conventions

How to set up a local development environment and the conventions we follow once you're in the code. New engineers should pair this with Accounts & Access and the Developer Workstations spec.

Per-repo specifics live in the repo

This page captures the cross-cutting conventions. Repo-specific build steps belong in each repo's README and CLAUDE.md; link the canonical ones from Key Repositories. New repos get this baseline from the new-repo-bootstrap skill.

Local Setup

  1. Get provisioned — see Accounts & Access.
  2. Clone from the anvil-co GitHub organization.
  3. Follow the repo README for language toolchain and build steps; a repo's CLAUDE.md lists the canonical install / test / run commands.
  4. Set up your agent tooling once — skills and MCP connectors — per Claude Code & AI Tooling.
  5. For ModuleWorks / Windows-only builds, use the Shared Windows Debug Machine.

Branching & Pull Requests

  • Base branch is main. Branch off it and open a PR back into it; main stays releasable.
  • Branch naming: you/AREA-short-slug. Include the Linear issue identifier when there is one (avnish/ENG-123-fix-toolpath) — Linear then auto-links the branch and PR to the issue. The linear-link-pr skill adds the link when a branch predates its issue.
  • Size PRs by what the change needs. We don't require artificially small or single-purpose PRs — land a complete, coherent change rather than splitting it just to keep the diff small.
  • Open your PR with the pr-describe skill. It writes the PR description from your branch's diff and commits, follows the repo's PR template, and links the Linear issue when the branch names one. Use it instead of hand-writing the body — invoke it by describing the task or with /pr-describe.
  • Review: every PR needs at least one human approval before merge. Use the @claude review workflow for a fast first pass — comment @claude /review-all (or a specific /review-*) on the PR. Apply feedback with the pr-address-comments skill.
  • Merge: squash-merge so main keeps one commit per PR with a clean, conventional-commit-style subject. Delete the branch after merge.

Coding Standards

  • Match the surrounding code. Each repo sets its own formatter and linter (e.g. prettier/eslint, ruff/black, rustfmt, clang-format); run them before pushing — CI enforces them.
  • The repo's CLAUDE.md/AGENTS.md are the source of truth for style, structure, and commands. Update them when a convention changes.
  • Never commit secrets. Use environment variables, GitHub Actions secrets, or the shared password manager — see the security basics in Accounts & Access.

CI / CD

  • CI runs in GitHub Actions.
  • Required checks must pass before merge — lint, tests, and build. A PR that goes red blocks merge until it's green.
  • A failed build: open the failing job's logs from the PR's Checks tab, fix locally, and push again to re-run; or re-run a flaky job from the Actions UI. Re-running does not need a new commit.

Release Flow

  • Production release flow is still WIP — nothing ships to production yet. Once it does, the plan is tag-based releases off main, versioned with semver (vMAJOR.MINOR.PATCH).
  • Generate release notes from the merged PRs since the last tag with the release-notes skill, then publish the GitHub release.
  • Cadence is per artifact — services release when a meaningful change lands; libraries and SDKs cut a tagged release consumers can pin to.