Skip to content
FuzzyFlags FuzzyFlags FuzzyFlags Docs

Engineering Handbook

This handbook defines how we build software across projects: simple architecture, reviewable changes, reliable delivery, and agent-assisted work that still depends on engineering judgment.

Core principles

Section titled “Core principles”

Keep architecture decisions practical and maintainable. Prefer small, focused changes over mixed concerns, and keep CI clean, maintained, and green.

Document complex business logic in docs/ near the relevant project or feature. Validate important behavior with tests, especially for user-facing flows and business-critical logic.

Architecture defaults

Section titled “Architecture defaults”

Start simple. We reject Next.js by default unless the project truly needs a marketing SEO-optimized site.

Preferred app stack:

Use Go where TypeScript is not a good fit. Use Biome for formatting and linting.

Repository structure

Section titled “Repository structure”

Every repository should make project context, scripts, and automation easy to find.

Expected baseline:

  • docs/ for project and business context
  • scripts/
  • scripts/run-e2e.sh
  • .dx/ for internal scripts or justfile helpers
  • justfile

Beware very small files that fragment context and very large files that become hard to maintain. Favor cohesive, understandable module boundaries.

Delivery and PR discipline

Section titled “Delivery and PR discipline”

Work should move from scoped request to production-ready merge through a predictable lifecycle:

  1. Align on the business goal, constraints, and acceptance criteria before making architectural decisions.
  2. Break implementation into independent, reviewable increments and define tests or documentation updates before coding.
  3. Build with clean commits focused on one concern each, then run the relevant validation.
  4. Open a PR with concise context, tradeoffs, and validation evidence.
  5. Address review feedback quickly, keep discussion traceable, and merge only when checks and approvals are satisfied.

The developer primarily assigned to a project is normally its Project Technical DRI unless another person is explicitly named. The DRI owns the technical approach, estimates, implementation quality, testing, and continuity of project context. They must surface feasibility changes and delivery risk early rather than waiting for the Technical Delivery Lead to discover or translate them. See Technical Delivery Ownership for the full responsibility split.

For every medium-to-large feature or fix, create a dedicated PR with sequential, clean, independent commits. The PR should tell a clear implementation story and make review easy.

Linear history and rebasing

Section titled “Linear history and rebasing”

Merge commits are generally forbidden across our repositories. Do not use git merge or accept Git’s default merge behavior when updating a branch. Rebase your work onto the latest target branch, and land PRs through a rebase or squash merge so repository history stays linear, readable, and easy to debug.

Configure Git once so git pull rebases instead of creating merge commits, and newly tracked branches inherit that behavior:

git config --global pull.rebase true
git config --global branch.autoSetupRebase always

These defaults do not remove your responsibility to inspect the resulting history and resolve conflicts carefully. If rebasing a shared branch would rewrite commits that other developers depend on, coordinate first rather than introducing a merge commit.

Rewriting PR history

Section titled “Rewriting PR history”

Only rewrite history on PR branches. Never rewrite shared protected branches like main, release branches, or any branch other people depend on without coordination.

Use interactive rebase to clean up WIP commits before review or before merge:

  1. Decide how many recent commits belong to the PR.
  2. Run git rebase -i HEAD~N, replacing N with that number.
  3. Reorder, squash, fixup, or reword commits until the PR history is clean.
  4. Push the rewritten PR branch with git push --force-with-lease.

Use --force-with-lease instead of --force because it refuses to overwrite remote changes you do not have locally.

Atlassian’s git rebase guide is a good helper for understanding interactive rebase and safe history rewriting.

Agentic coding workflow

Section titled “Agentic coding workflow”

Use agents to accelerate engineering work, not to replace engineering judgment. The developer remains responsible for architecture, tradeoffs, correctness, and review.

Recommended tools:

  • Warp for agentic development sessions, command execution, and multi-agent work.
  • OpenCode as a lightweight terminal coding-agent option.
  • OpenAI API (GPT) when direct API usage is useful and cost matters.
  • oyo for diff review.
  • Linear / Linear Guide for issue and PR review flows.

Recommended flow:

  1. Code locally with worktrees when parallel or isolated work is useful.
  2. Review the diff with oyo.
  3. Clean up PR history if needed.
  4. Push changes and create a PR.
  5. Review the PR with Linear Guide by replacing github.com in the PR URL with linear.review.

Agentic coding expectations:

  • We are not hiring people to only prompt LLMs.
  • Always review agent-generated code, diffs, and behavior before merge.
  • Learn to discriminate when to use agents and when to execute directly.
  • Prefer the fastest reliable path for simple deterministic actions, such as using gcmsg 'fix(...): ...' directly instead of delegating a commit prompt and waiting on a large model.

Coding-agent model guidance

Section titled “Coding-agent model guidance”
  • GPT 4.4: fast, cheap, and good enough for most tasks.
  • Gemini 3.1 Flash Lite: super fast for most fixes.
  • Claude: strong for bug fixing and debugging, but costly.
Section titled “Related pages”