Skip to content

Engineering Practice

What you’ll learn. The non-code half of software engineering: how teams use version control (trunk-based development vs branching models, good commits, safe rollout), how to write design docs and architecture decision records, how to think about and manage technical debt, why estimation is hard and what to do about it, how to work effectively and safely with AI coding assistants (a fast-moving area, treated here in terms of durable principles), and the habits that characterize engineers who grow into senior and staff roles.

Git is the near-universal tool, and its data model is worth knowing: a repository is a directed acyclic graph of immutable commits (snapshots plus parent pointers); branches and tags are movable/fixed pointers into it. Understanding this makes rebase, cherry-pick and reflog (your safety net for recovering “lost” commits) intuitive.

Strategy Idea Fits
Trunk-based development Everyone integrates to main at least daily via very short-lived branches (hours to a day or two); incomplete work hidden behind feature flags Teams practicing CI/CD; high-performing delivery per DORA research
GitHub Flow Short-lived feature branch, PR, review, merge to main, deploy Web apps and services with continuous deployment
Git Flow develop, release/*, hotfix/*, feature/* branches Versioned, scheduled releases (installed software, multiple supported versions); heavier than most teams need
Release branches Cut a branch per supported release, cherry-pick fixes Libraries, on-premise products

The key empirical finding (DORA / Accelerate, Forsgren, Humble, Kim, 2018): teams with small, frequent merges, trunk-based development and strong automated testing deploy more often with fewer failures. Long-lived branches cause painful merges and integration risk (the longer code stays unmerged, the larger the divergence). Decouple deploy (code is in production) from release (users see it) with feature flags, dark launches and progressive rollouts; delete flags after rollout to avoid flag debt.

  • Atomic commits: one logical change, passing tests, so git bisect and git revert work.
  • Commit messages: a short imperative subject (about 50 characters: “Fix race in cache refill”), a blank line, then a body explaining why (the diff shows what). Conventional Commits (feat:, fix:) enable changelog and version automation if you want it.
  • Small PRs: aim for hundreds of lines at most; stack PRs for large work. See review guidance in Testing & Code Quality.
  • Merge strategies: merge commits (preserve history), squash (one commit per PR, clean main), rebase (linear history). Pick one convention per repo. Never rewrite history that others have pulled (shared branches); --force-with-lease is safer than --force on your own branches.
  • Protect main: required reviews and passing CI, no direct pushes.
Terminal window
# Useful everyday commands
git switch -c fix/cache-race # new branch
git add -p # stage hunks interactively -> atomic commits
git commit # write a meaningful message
git fetch && git rebase origin/main # replay your work on top of latest main
git push --force-with-lease # update your own PR branch safely
git bisect start HEAD v1.4.0 # binary-search for the commit that introduced a bug
git reflog # recover from "I lost my commits"

Continuous integration: every change is automatically built and tested on merge/PR, giving fast feedback (target minutes, not hours). Continuous delivery: main is always releasable; continuous deployment: every passing change ships automatically. Supporting practices: reproducible builds, trunk with required checks, automated rollback, deployment pipelines as code, artifact immutability (“build once, deploy the same artifact to every environment”), and monitoring-driven rollout (Reliability). In monorepos (Google, Meta) tooling (Bazel, Nx, Turborepo) builds only what changed; in polyrepos, versioned APIs and contracts carry more weight (API Design).

Writing is the cheapest way to find design flaws. A design doc is a short document written before major implementation to align stakeholders, expose trade-offs, and catch problems when change is cheapest. Google’s guidance: write one when the design is non-trivial, when it affects other teams, or when there are real alternatives; skip it for trivial changes.

  1. Context and problem: what’s wrong or needed, for whom, why now.
  2. Goals and non-goals: non-goals are as valuable as goals; they bound the scope explicitly.
  3. Background: only what a reader needs.
  4. Proposed design: overview (diagram), components, data model, APIs, key flows; enough detail to evaluate, not to implement line by line.
  5. Alternatives considered: and why rejected; the section reviewers care about most.
  6. Cross-cutting concerns: security, privacy, reliability/SLOs, observability, cost, migration and rollback, testing strategy, operational burden.
  7. Risks and open questions.
  8. Milestones/rollout plan.

Tips: lead with the conclusion for busy readers; quantify (use the estimation skills from System Design Fundamentals); put diagrams to work; get review early from people who will disagree; time-box review, then decide (a doc that never converges is a failure). Keep docs short; length is not rigor. A design doc is a snapshot, so record the outcome and update or mark it as superseded as reality diverges. RFC-style processes (Rust RFCs, Python PEPs, internal RFCs) apply the same idea at community scale.

Michael Nygard (2011) proposed lightweight records of individual architecturally significant decisions, stored in the repository (docs/adr/0007-use-postgres-for-orders.md), numbered and immutable once accepted (superseded by a new ADR rather than edited). Template:

# 7. Use PostgreSQL for the orders service
Status: Accepted (supersedes ADR 3) Date: 2026-03-14
## Context
Orders need transactional consistency across order + inventory rows; team has Postgres experience;
expected load 500 writes/s peak; we considered DynamoDB and MySQL.
## Decision
Use PostgreSQL 16 managed service, single primary with a read replica.
## Consequences
+ Strong consistency, rich queries, mature tooling.
- Vertical scaling limit (revisit above 5k writes/s); we operate backups and failover via provider.
- Team must learn partitioning if the orders table exceeds ~1 TB.

The value is the context and consequences: months later, nobody remembers why. ADRs make decisions discoverable, reduce re-litigation, and help new joiners. Write one when a decision is hard to reverse (see Architecture Styles) or the trade-offs were non-obvious. Keep them short (half a page).

Ward Cunningham’s metaphor (1992): shipping code with known shortcuts is like taking a loan; you gain speed now and pay interest (slower future changes) until you repay the principal (the cleanup). The metaphor is useful because debt can be a rational, deliberate choice; it fails when used to describe all bad code.

Martin Fowler’s technical debt quadrant distinguishes:

Reckless Prudent
Deliberate “We don’t have time for design” “We must ship now and deal with the consequences”
Inadvertent “What’s layering?” “Now we know how we should have done it”

Prudent debt (taken knowingly, tracked, repaid) is a tool; reckless debt is just mess. Also distinguish debt (known shortcuts), bit rot (the environment moved: deprecated dependencies, outdated frameworks), and design erosion (a once-sound design that no longer fits).

  • Make it visible: keep a lightweight debt register (issues labeled tech-debt with impact in business terms: “adds ~2 days to every payments change”, “causes 1 incident per quarter”).
  • Prioritize by interest, not ugliness: fix debt in code you change frequently (high interest); ignore ugly code nobody touches. Hotspot analysis (change frequency x complexity from version control history, as in Adam Tornhill’s Your Code as a Crime Scene) finds the expensive spots.
  • Pay continuously: the Boy Scout Rule and “make the change easy, then make the easy change” (Kent Beck); reserve a steady fraction of capacity (commonly cited 10-20%) rather than hoping for a “refactoring quarter” that gets cancelled.
  • Tie repayment to product work: refactor as part of the feature that needs it, with tests (Testing & Code Quality).
  • Replace incrementally with the strangler fig pattern, not rewrites. Big-bang rewrites usually fail: they take longer than estimated, re-introduce old bugs, and freeze feature delivery (Joel Spolsky’s “things you should never do”).
  • Prevent: automated linting, dependency updates (Dependabot/Renovate), architectural fitness functions in CI (e.g. import-boundary checks), definition of done that includes tests and docs.
  • Communicate in the language of the audience: to product and leadership, translate debt into cost, risk and delay, not “the code is ugly”.

Not every shortcut is debt: a prototype meant to be thrown away, code with a known short lifespan, and the cost of YAGNI-compliant simplicity are fine (Core Principles). The risk is the prototype that quietly becomes production.

Software estimation is notoriously unreliable because the work is novel (if it had been done before, you would reuse it), requirements shift, hidden complexity surfaces, and people estimate the happy path. Findings: the planning fallacy (Kahneman and Tversky) shows people underestimate even when they know similar tasks overran; the cone of uncertainty (Boehm; McConnell) shows early estimates can be off by 4x in either direction, narrowing as the project progresses; estimates are commonly treated as commitments, which creates pressure and padding games.

Principles that help:

  1. Estimate ranges, not points. “Two to five weeks, most likely three” communicates uncertainty. Three-point estimation (optimistic aa, most likely mm, pessimistic bb) gives an expected value E=(a+4m+b)/6E = (a + 4m + b)/6 and standard deviation roughly (b−a)/6(b - a)/6 (PERT).
  2. Decompose work into pieces of a day or two; large undecomposed items hide risk. Small tasks have less variance, and errors partly cancel in aggregate. But beware: sums of independent small estimates understate systematic bias (all estimates optimistic).
  3. Use reference classes (outside view): how long did comparable projects actually take? Historical throughput beats gut feel.
  4. Estimate relative size (story points) only if it helps; then use velocity/throughput (items per week) from history for forecasting. Many teams find simply counting items completed per week (#NoEstimates-flavored flow metrics, cycle time percentiles, Monte Carlo forecasting from historical throughput) at least as accurate as point estimation, with less ceremony.
  5. Separate estimate, target, and commitment. An estimate is a probabilistic prediction; a target is a desire; a commitment is a promise. Negotiate scope against a fixed date rather than pressuring the estimate.
  6. Surface unknowns early: spikes (time-boxed investigations), prototypes, and tackling the riskiest part first. The biggest overruns come from unknown unknowns, so buy information first.
  7. Include everything: testing, review, deployment, migration, documentation, on-call, meetings, and the interruptions that make an “8-hour day” yield ~4-5 productive hours. Hofstadter’s Law: it always takes longer than you expect, even when you take into account Hofstadter’s Law.
  8. Re-estimate as you learn and communicate changes early; bad news does not improve with age.
  9. Slice scope so something valuable ships early; deliver in increments, so schedule risk is bounded.
# Python: Monte Carlo forecast from historical weekly throughput
import random
history = [4, 6, 3, 5, 7, 4, 2, 6] # items completed in past 8 weeks
remaining = 30
def weeks_to_finish():
done, weeks = 0, 0
while done < remaining:
done += random.choice(history) # resample a past week
weeks += 1
return weeks
sims = sorted(weeks_to_finish() for _ in range(10_000))
print("50%:", sims[5000], "weeks; 85%:", sims[8500], "weeks") # give a range, not a point

Answering “when will it be done?” with “85% likely by week 9, 50% by week 7” is more honest and more useful than “7 weeks”.

AI assistants (chat, inline completion, and increasingly autonomous coding agents that read a repository, run commands and tests, and open pull requests) have become a normal part of engineering work by 2026. The tools, models and best practices change quickly, so what follows are durable principles rather than product specifics; verify details against current docs.

Boilerplate and glue code, tests and test scaffolds, unfamiliar APIs and languages, translating between formats and languages, writing first drafts of documentation, explaining legacy code, repetitive refactors across many files, scripts, and exploring options quickly. They are weaker where context is missing or rare: subtle concurrency and distributed-systems correctness, domain-specific invariants not written anywhere, performance-critical code, security-sensitive logic, and novel design. They can produce plausible, confident, wrong code, invent APIs or package names that do not exist, silently drop edge cases, or “fix” a failing test by weakening it.

  1. You remain the author and are accountable. Whatever you commit is yours. “The AI wrote it” is never an acceptable answer in review or in an incident. Read every line you accept; if you cannot explain it, do not merge it.
  2. Verification is the bottleneck. Generation is cheap; confidence is not. Invest in what lets you verify fast: strong types, a fast test suite, linters, property tests, CI, small diffs. A codebase with good tests multiplies the value of an assistant; one without tests multiplies risk.
  3. Specify before you generate. Good prompts resemble good tickets: goal, constraints, interfaces, examples, non-goals, how to verify. Write the test or acceptance criteria first and let the assistant make it pass (TDD pairs naturally). For nontrivial tasks, ask for a plan first, review it, then implement in small steps.
  4. Give context. Point the tool at relevant files, conventions, and architecture notes. Persist durable guidance in repository instruction files (e.g. an AGENTS.md or tool-specific equivalent) covering build/test commands, style, architecture boundaries, and “never do” lists; this also benefits human newcomers. ADRs and design docs (above) become more valuable, since they are context for both humans and agents.
  5. Keep changes small and reviewable. Ask for one change at a time; large machine-generated diffs encourage rubber-stamping. Commit frequently so you can revert, and keep AI-generated refactors separate from behavior changes.
  6. Treat output as untrusted input. Review for security (injection, authz gaps, hard-coded secrets, unsafe deserialization), license issues, and dependency choices: verify packages exist and are legitimate (slopsquatting/typosquatting attacks exploit hallucinated names). Run code in sandboxes; scope agent permissions narrowly (least privilege), require approval for destructive commands, and never paste secrets or sensitive customer data into tools not approved by your organization’s policy. Beware prompt injection: an agent reading untrusted content (web pages, issues, dependencies’ files) can be steered by instructions hidden in it.
  7. Check for tests that lie. Agents may modify tests to pass or write tests that assert the current (buggy) behavior; apply mutation-testing thinking (Testing) and review test changes especially carefully.
  8. Use it to learn, not to avoid learning. Ask for explanations and alternatives; predict before you look. Skills you stop exercising decay, and the judgment needed to review AI work comes from having done the work. Early-career engineers in particular should build fundamentals deliberately.
  9. Debug with it, but keep the scientific method. Provide failing output and minimal repro; ask for hypotheses, then test them yourself; beware fix-by-guess that makes symptoms vanish without finding the cause.
  10. Match autonomy to risk. Let agents run unattended on well-tested, low-blast-radius tasks (dependency bumps, mechanical migrations, test generation behind PR review); keep humans tightly in the loop for security, data migrations, infrastructure changes, and anything irreversible.

Agree on norms: disclosure of AI-assisted changes if your team wants it, review standards (AI-authored PRs need at least the same scrutiny), data and IP policies, licensing and provenance concerns, and how to evaluate tools with your own tasks rather than benchmarks. Measure outcomes (lead time, change failure rate, review load, defects) rather than lines produced; evidence on productivity effects has been mixed and context-dependent, with the largest benefits on well-specified, well-tested work and potential slowdowns when verifying plausible-but-wrong output on complex codebases. Expect the shape of engineering to shift toward specification, architecture, review, testing and systems thinking, which are exactly the topics of this section.

Healthy loop:
intent/spec --> small generated change --> automated checks (types, tests, lint)
^ |
| v
learn, adjust <-- human review & judgment <-- run it, observe it

Being excellent as an individual contributor over many years is less about knowing more frameworks and more about a small set of compounding habits.

Technical judgment

  • Understand the problem before the solution: ask “what outcome do we want and how will we know?” Challenge requirements politely; often the cheapest feature is the one you do not build.
  • Choose boring technology (Dan McKinley) for most of the stack; spend a small “innovation budget” deliberately.
  • Reason in trade-offs: every decision gives something up; state it. Prefer reversible decisions made quickly and invest care in irreversible ones (“two-way vs one-way doors,” a framing popularized by Amazon).
  • Optimize for the reader: code is read far more than written; clarity beats cleverness (Core Principles).
  • Make it work, make it right, make it fast, in that order, with measurement.
  • Learn the layer below where you work (networking, OS, database internals); abstractions leak, and debugging skill is mostly knowledge of what is underneath.
  • Debug systematically: reproduce, shrink, form falsifiable hypotheses, bisect, change one thing at a time; keep notes; do not guess.
  • Own operations: build it, run it. Carry the pager, write runbooks, look at dashboards and logs. Production teaches what design cannot.

Communication and collaboration

  • Write clearly: concise design docs, PR descriptions, status updates and postmortems. Writing scales you.
  • Disagree and commit: argue the merits, then support the decision. Keep decision records.
  • Give and receive feedback kindly and directly; assume good intent; separate code from person.
  • Make work visible without self-promotion: short updates, demos, documented results.
  • Manage up and across: surface risks early, propose options with recommendations rather than just problems, and understand your stakeholders’ goals.
  • Teach and mentor: explaining deepens your own understanding and raises the team.
  • Be easy to work with: reliable on commitments; say “I don’t know” and “I was wrong” readily.

Growth

  • Deliberate practice: seek tasks slightly beyond your ability; build side projects; read other people’s high-quality code (open source) and postmortems; read the classics (list below).
  • Depth plus breadth (“T-shaped”): deep in one area, conversant across the stack.
  • Scope grows with seniority: junior engineers deliver tasks; mid-level engineers deliver features independently; senior engineers deliver projects and raise the team’s capability; staff-plus engineers set direction across teams, create leverage (tools, standards, mentorship), and navigate ambiguity. Will Larson’s Staff Engineer and Tanya Reilly’s The Staff Engineer’s Path describe these tracks. Impact, not output, is the currency; increasingly it comes from making others effective.
  • Sustainable pace: burnout destroys judgment. Protect sleep, focus time, and rest; guard against heroics as a pattern.
  • Keep a log of decisions and learnings (a “brag document” for performance reviews, a personal wiki for knowledge, like this one).
  • Be skeptical of hype cycles: evaluate new tools against concrete problems; learn fundamentals that outlast frameworks (data structures, networking, databases, distributed systems, concurrency, testing, communication).
  • Long-lived branches and big-bang merges.
  • Design docs written after the code, or never reviewed; ADRs nobody can find.
  • “Tech debt” used as a synonym for code you dislike; no one tracks its cost.
  • Single-point estimates treated as promises; estimating only the coding part.
  • Merging AI-generated code you cannot explain; letting an assistant weaken tests; granting agents broad credentials.
  • Rewrites instead of incremental replacement.
  • Heroism as a substitute for process; ignoring operational ownership.
  • Small, frequent integration (trunk-based, feature flags, CI/CD) beats long-lived branches; write atomic commits with messages that explain why.
  • Write design docs for non-trivial changes (goals, non-goals, alternatives) and ADRs for hard-to-reverse decisions; they are context for people and AI agents alike.
  • Technical debt is a deliberate-or-not loan; track its interest, repay it continuously where change is frequent, and replace incrementally.
  • Estimate with ranges and historical data, separate estimates from commitments, and de-risk unknowns early.
  • AI assistants multiply output, but verification is the bottleneck: spec first, small diffs, strong tests, least privilege, human accountability.
  • Career growth compounds from judgment, clear writing, operational ownership, and increasing leverage over time.
  1. Hands-on (git). In a scratch repo, create a bug across several commits, then use git bisect to find the culprit commit. Then recover a “lost” commit using git reflog.
  2. Hands-on. Write an ADR for a past technical decision you made (for example, choosing a database or framework), including alternatives and consequences. What did you realize while writing?
  3. Conceptual. Pick a messy part of a codebase you know. Classify its debt using Fowler’s quadrant and estimate its interest (hours lost per month). Decide whether to repay it and how.
  4. Hands-on (Python). Adapt the Monte Carlo forecaster to produce a histogram or percentile table, then compare its forecast to a point estimate from story points on your own project’s history.
  5. Hands-on. Use an AI assistant to implement a small feature test-first: write the tests yourself, let the assistant make them pass, then review its diff critically and list three things it got wrong or risky. Add mutation or property tests to check it.
Solutions (sketch)
  1. git bisect start; git bisect bad; git bisect good <rev>, then git bisect run ./test.sh automates it. git reflog lists previous HEAD positions; git branch rescue <sha> restores a commit.
  2. Prudent and inadvertent (“now we know how it should have been”) is common; interest = hours per month lost x team; repay if the area is high-churn and the payback period (cost to fix / monthly interest) is under a few months.
  3. Typical issues: missing edge cases, tests weakened or tautological, over-engineered abstractions, subtle security gaps, unnecessary dependencies, and unused code.
  • Nicole Forsgren, Jez Humble, Gene Kim, Accelerate (2018), and the annual DORA reports.
  • Jez Humble and David Farley, Continuous Delivery (2010).
  • Scott Chacon and Ben Straub, Pro Git (free online).
  • Michael Nygard, “Documenting Architecture Decisions” (2011 blog post).
  • Titus Winters, Tom Manshreck, Hyrum Wright, Software Engineering at Google (2020).
  • Frederick Brooks, The Mythical Man-Month (anniversary ed., 1995).
  • Steve McConnell, Software Estimation: Demystifying the Black Art (2006).
  • Adam Tornhill, Your Code as a Crime Scene (2nd ed., 2024).
  • Will Larson, Staff Engineer (2021); Tanya Reilly, The Staff Engineer’s Path (2022).
  • Andrew Hunt and David Thomas, The Pragmatic Programmer (20th anniversary ed., 2019).
  • Dan McKinley, “Choose Boring Technology” (2015).
  • Martin Fowler, “TechnicalDebtQuadrant” (martinfowler.com, 2009).
  • Documentation of whichever AI coding tools you use; treat them as living documents.