Heuristics

A heuristic is a mental shortcut that lets you make a good-enough decision without analyzing every variable. It is not a rule — rules are rigid and always apply. It is not a guess — guesses have no basis. A heuristic is a pattern extracted from experience that works most of the time, with known exceptions.

"If the function is longer than your screen, split it." That is a heuristic. It is not always right (some long functions are clear). But it is right often enough that following it by default and overriding it when you have a reason produces better code than having no guideline at all.

The word comes from the Greek "heuriskein" — to discover. Heuristics are discovered, not invented. They emerge from doing the work enough times that the pattern becomes visible. The best heuristics feel obvious in hindsight and counterintuitive before you have the experience.

A rule is absolute: "Never commit secrets to version control." No exceptions. No judgment required. Rules exist for situations where the cost of violation is catastrophic and the decision should not require thinking.

A heuristic is probabilistic: "Prefer composition over inheritance." Usually right. Sometimes wrong. Requires judgment about when to follow and when to deviate. Heuristics exist for situations where the right answer depends on context.

An SOP (Standard Operating Procedure) is a documented sequence of steps for a recurring process. "When deploying to production: pull main, run tests, build, deploy to staging, smoke test, deploy to production, verify, announce in Slack." SOPs encode the how — the specific steps to follow, in order, every time. They reduce variance and ensure consistency.

The relationship: rules define what you must never/always do. Heuristics guide decisions where judgment is required. SOPs standardize execution of recurring tasks. A mature team has all three, and every team member knows which category each guideline belongs to.

Do the work. Heuristics cannot be learned from a book. They are extracted from experience — specifically, from the moment when you realize "this is the third time this pattern has caused a problem." That third time is when the heuristic crystallizes. You need the reps.

Name the pattern. An unnamed pattern is an instinct. A named pattern is a heuristic. When you find yourself saying "I just feel like we should..." stop and articulate why. What happened last time? What pattern are you recognizing? Give it a name. "The last time we added a database for this, we over-engineered it. Let's use a file." The heuristic: "Use a file before you use a database."

Test it against counterexamples. A heuristic that works in every situation is a rule. A heuristic with no exceptions is probably wrong — you just have not found the exception yet. Actively look for cases where your heuristic fails. The exceptions define the boundaries of the heuristic, which makes it more useful, not less.

Write it down. A heuristic that lives only in one person's head dies when that person leaves the team, forgets it, or is not in the room for the decision. Written heuristics compound. Unwritten heuristics evaporate. A team's CLAUDE.md, CONTRIBUTING.md, or decision log is where heuristics should live.

Revise it. Heuristics are not permanent. The heuristic "always write tests before code" might evolve to "write tests before code for business logic; skip tests for prototypes." As your experience deepens, your heuristics should become more nuanced, not more rigid. Rigid heuristics are just rules pretending to be flexible.

Share the story, not just the rule. "Prefer composition over inheritance" is a heuristic. "Last year we used inheritance for the payment system and it took three months to untangle when the requirements changed" is the story that makes the heuristic stick. Stories encode the why. Without the why, heuristics feel arbitrary.

Code reviews are the classroom. Every code review is an opportunity to share a heuristic in context: "This works, but I've seen this pattern cause problems when X changes. Here's a heuristic I use: [heuristic]. What do you think?" Frame it as a suggestion with reasoning, not a decree.

Build a decision log. When the team makes a significant decision (chose Postgres over MongoDB, decided to use server components, picked a monorepo structure), write down the decision and the heuristic that guided it. Over time, the decision log becomes a heuristic library — a searchable record of "when we faced this kind of choice, here is how we thought about it."

Encourage respectful deviation. A team where nobody ever deviates from the heuristics is a team that has confused heuristics with rules. The right culture: "I know our heuristic is X, but in this case I think Y is better because Z." That sentence should be welcomed, not punished. Deviation with reasoning is how heuristics evolve.

Bake them into tooling. Heuristics that can be automated should be. "Functions should be under 50 lines" → a linter rule. "Every PR needs a description" → a PR template. "No direct pushes to main" → branch protection. Automated heuristics require zero willpower to follow. Reserve human judgment for the heuristics that cannot be automated.

A Standard Operating Procedure is a documented, step-by-step process for completing a recurring task. SOPs exist to make execution consistent, transferable, and auditable.

Consistent: the deployment process works the same way whether the senior engineer or the new hire is running it. Transferable: a new team member can follow the SOP on day one without shadowing someone for a week. Auditable: if something goes wrong, you can trace which step failed.

A good SOP has: a trigger (when to start), numbered steps (what to do, in order), expected outcomes per step (how to know it worked), error handling (what to do if a step fails), and an owner (who maintains and updates the SOP). SOPs that lack any of these become stale, incomplete, or followed only by the person who wrote them.

The relationship between SOPs and automation is direct: an SOP is a human-executable automation. Once an SOP is documented and validated, it is a candidate for scripting. The SOP becomes the spec for the automation. This is why the Tasks page flows into the Automations page — SOPs are the bridge.

The most important heuristic about heuristics: a heuristic you follow without understanding is a superstition. Every heuristic on this page has a reason. If you cannot articulate the reason, you do not own the heuristic — it owns you. Learn the why. Then follow or deviate with intention.