03 — Dev Workflow

Low ceremony, high signal. We’re a small team — heavy process is a tax we can’t afford.

Git, branching, commits, and pull-request mechanics live in their own chapter — see Git Workflow. This page covers everything else about how we write and ship code day-to-day: CI, environments, style, dependencies.

CI (GitHub Actions)

Every repo runs these on every PR:

1. Typecheck — tsc --noEmit or pyright / mypy.
2. Lint — ESLint flat config, or Ruff (Python).
3. Test — see 04-testing.
4. Build — catches broken imports and bad types in edge cases.

All four required to merge. No “I’ll fix it in the next PR.”

Environments

• .env.local per dev — gitignored. Never commit.
• .env.example checked in — lists every var with a placeholder. This is the source of truth for “what env does this project need.”
• Secrets live in Vercel env / Azure Key Vault — never in git, never in Teams, never in screenshots.
• Three env tiers: local (dev machine), preview (per-PR on Vercel or staging slot on Azure), production.
• Never reuse prod credentials in preview/local.

Code style

• Prettier + ESLint (flat config) for TS/JS. Biome is acceptable for new repos if you prefer speed.
• TypeScript strict: true — no any unless justified in a comment.
• Ruff + Black for Python.
• Stylistic arguments go in the config, not the PR. If the tool accepts it, it’s fine.
• Formatter runs on save (editor config) and in pre-commit — never in CI to “fail” a PR. CI runs lint, not format.

Pre-commit hooks

• lint-staged runs Prettier/ESLint on staged files only.
• Typecheck on changed files (fast with tsc --incremental).
• That’s it. No unit tests in pre-commit — they belong in CI, not blocking every commit.

Dependencies

• pnpm for TS/JS. Not npm, not yarn.
• uv for Python (fast, modern). pip + venv acceptable for legacy projects.
• Lockfile committed. Always.
• renovate or dependabot for weekly updates. Merge patches + minors on green CI; majors get a reviewer.
• Don’t add a dependency for a 10-line function. A dependency is a liability; write the function.

Branch protection settings

Detailed in § Git Workflow — Branch protection. TL;DR: main requires a PR, 1 approval, green CI, up-to-date branch. No force push, ever.

Editor & local setup

• VS Code is the default — most shared tooling (EditorConfig, recommended extensions) assumes it.
• JetBrains fine if you prefer — make sure formatting on save matches.
• .editorconfig in every repo. Controls line endings, indent, trailing newlines.
• .vscode/extensions.json with recommended extensions per repo (ESLint, Prettier, Tailwind IntelliSense, etc.) — VS Code prompts new cloners to install them.

New engineers

First-week onboarding checklist lives in § Onboarding. Read that first.