Engineering Guidelines: First Principles

The Problem

First Principle: Zero Friction

If a new engineer can’t ship code on day one, your process is broken.

Not “read the wiki.” Not “ask John, he knows how it works.” Not “we’ll pair with you for a week.”

Clone. Run one command. Ship.

Everything else is organizational debt you’re paying interest on every single day.

git clone <repo>
cd project
./setup.sh
# Done. Ship code.

The Algorithm

Each requirement has a person behind it. Find them. Ask why.

The most dangerous requirements are the ones nobody questions because “that’s how we’ve always done it.”

The best code is no code. The best config is no config. The best process is no process.

Before you optimize anything, ask: can I delete it instead?

Only after you’ve deleted everything possible.

Simplification without deletion is just rearranging complexity.

Speed up what remains.

But only what remains after deletion and simplification.

Only at the end.

Most teams do this backwards. They automate complexity instead of eliminating it.

On Setup

Your setup process reveals everything about your engineering culture.

The goal is one command that works everywhere. Mac. Linux. Docker. CI/CD. No exceptions.

On Configuration

Configuration is where projects go to die.

Every config file is a decision someone didn’t want to make. Every environment variable is complexity exported from code.

If you need a config management tool to manage your config, you have too much config.

On State

State is the enemy of scale.

The application should be disposable. Kill any instance. Nothing is lost.

On Failure

Every system fails. Plan for it.

Not “what if it fails” but “when it fails.”

Graceful degradation isn’t a feature. It’s the default behavior. The system works with reduced capability, never zero capability.

Circuit breakers. Fallbacks. Timeouts. These aren’t optional. They’re the architecture.

“Design for failure, and you’ll rarely experience it. Design for success, and failure will surprise you.”

On Security

Security isn’t a sprint at the end. It’s how you build.

Most security vulnerabilities are known and preventable. The same injection attacks from 2003 still work because teams still concatenate strings.

Don’t add security. Build with security. There’s a difference.

On Observability

You can’t fix what you can’t see.

If you’re debugging production by adding print statements, you’ve already lost.

Observability isn’t overhead. It’s the difference between engineering and guessing.

On Automation

Humans review architecture. Machines enforce standards.

Formatting, linting, type checking - these aren’t review comments. They’re automated gates.

Code review should be: “Is this the right approach?”

Not: “You forgot a semicolon.”

On Documentation

Documentation in wikis dies. Documentation in code lives.

The README is the product. If someone can’t understand what this does in 5 minutes, the README has failed.

ADRs (Architecture Decision Records) aren’t bureaucracy. They’re why future-you won’t repeat past mistakes.

If it’s not in the repo, it doesn’t exist.

On Decisions

The hierarchy:

Developer experience is a means, not an end. Good DX that compromises security is bad engineering.

On Technology

The best technology is boring technology.

New frameworks are experiments. Battle-tested tools are foundations.

Use the new thing for side projects. Use the proven thing for production.

Your job isn’t to evaluate technology. It’s to ship product.

The Point

Every line of code is a liability. Every config is a decision to maintain. Every process is friction.

Delete. Simplify. Accelerate. Automate.

In that order.

Software Engineering 3.0

AI handles the tedious parts.

But AI without principles is just faster chaos.

These are the principles.

“The best engineers don’t write the most code. They delete the most code while shipping the most value.”