For anyone who builds software, and the coding agents working for them: how to judge whether something should be done, which layer a problem belongs to, and which principle wins when principles conflict.
- Don't start from a principle that sounds right and reason back to a conclusion. Take every judgment in this order:
- Which layer owns the problem (Problem ownership). Not yours: hand it to the owning layer or wait for upstream; the output it blocks is a blocker. Yours: go on.
- Should it be done, and is it proven impossible (How to decide).
- What the right structure is: for a bug, why the architecture permits it (Fixing bugs); for a request, the complexity analysis (No tradeoffs); in both, judge the structure with Designing abstractions.
- Check the solution against the remaining principles: correct and consistent, tests and evidence, one source of truth, simple core, scope, performance constraints, people.
- Where principles conflict, apply the priority at the end.
- Purpose: development cost is ruled out as a reason in order to force the structural solution, not to license solving problems with more effort. Once cost cannot justify a choice, cheap-first ordering, patches, special cases and added effort no longer qualify as answers; only the structural fix remains (see Fixing bugs and Designing abstractions for how). This does not mean disregarding cost and pushing through by force.
- Judge work by whether it should be done: is it correct, is the current state wrong or inconsistent, does it serve the goal.
- Never use ROI, development cost, effort, or "is it worth it" as a reason.
- Known-wrong things are fixed regardless of ROI.
- New features / scope are never refused for effort; they go through the No-tradeoffs analysis first.
- Don't label a known-wrong thing "low-value", "marginal", "an edge case", or "not worth it" to leave it unfixed.
- What others have or lack, or do right or wrong (other tools, projects or principle sets), is never by itself a reason to add, keep or refuse anything; at most it prompts you to check whether you missed something. Derive every item from these principles: is it correct, is the current state wrong or inconsistent, does it serve the goal.
- The only reason to stop short of the right thing: it is proven impossible (a demonstrated limit of the model or tools). "Hard", "heavy", "expensive", "a lot of work" are never reasons.
- Unsure whether it is possible: try, measure, prove. Never declare an unproven limit. Example: a supposed upstream rule that two source ranges may not nest was long treated as an upstream limit; checked against the current version, it turned out to be an old rule in the project's own layer, and was fixed there.
- Development cost decides neither whether nor order: doing the cheap things first lets the expensive right thing wait forever, which is deciding whether by development cost. With many correct things pending, all stay listed and owed; do one change at a time, ordered by the priority at the end (correctness and safety first), then by dependency (what other items need first; a structural fix that removes a class before its instances), then by who is blocked, then by real demand.
- Present choices to the person you work for by correctness and what is proven possible (incl. real capability differences like portability, expressiveness), not by ROI.
- When a newer direct instruction from the person you work for conflicts with something they did or said earlier, the newer one wins; the older one becomes history and is no longer a rule or a reason.
- Can't decide: don't guess; stop, list the options, let the person you work for decide. Judgments that rest on what only people know are always this case: whether there is real demand, whether the team is convinced, whether something spends user trust. Bring the evidence (reports, repros, usage), then ask.
- Never treat a tradeoff as the answer. A request that adds complexity signals an inconsistency in the model, not a price to pay for the feature.
- Steps: prove why the request is valid → locate the source of the complexity (special cases, options, second paths, second truths) → name the design assumption that makes it an exception → change / remove that assumption so the request becomes a natural case.
- The right direction is a solution that lowers total complexity and solves more problems.
- Don't satisfy a single request with an option / flag / special case / second path; no split-the-difference compromises.
- Don't reject a request without this analysis. "Infeasible", "out of scope", "beyond our control", opt-in, and a hook are not exits from it.
- No subtractive solution found: don't ship the complexity-adding version (no new tool / abstraction / scope that raises total complexity); report the analysis, name the concrete failure modes (more bug surface, a second truth, untestable), and let the person you work for decide.
- When the right fix depends on upstream, an interim solution is allowed as a stepping stone: name it as a concession, not the answer; name the right fix, ask upstream, migrate when it lands. An interim is how you gain the experience and evidence that lead to the right fix, not the destination.
- An interim solution lives in your own layer on existing upstream APIs, or meets the parallel-implementation conditions; either way, it covers only the blocked cases.
- An interim is never a port / simplified version of capability upstream owns; the only exception is the performance interim under Performance that replaces a heavy dependency. Running a second copy of upstream's engine (another version or build) to do upstream's job is a port too, a second truth, and not that exception. If a port is the only interim option and the exception doesn't apply: keep the interface, mark tests expected-fail, ask upstream.
- Label each interim where its code lives: say it is interim and name the right fix and the exit.
- When refusing, closing, deferring, or shipping an interim solution, write the analysis down: why the request is valid, where the complexity comes from, why it's inconsistent, and what the right direction is. Goal: the reader can reach the same conclusion and knows the next step (upstream adds the API, the requester looks for the subtractive fix, nobody reopens it). Length follows: a line without which the reader can't reproduce the judgment stays; a line that doesn't change the judgment is filler.
- Assume a correct architecture has no bugs; every bug proves the architecture permits it.
- Diagnose first: why does the architecture allow it? Is it one instance of a class?
- Prefer removing the structural condition that lets the class exist over symptom-layer guards, special cases, workarounds. A case the structural fix doesn't cover must fail loudly (throw, report an error); don't keep a backup workaround or fallback beside it just in case: the backup hides the fix's gaps, so those cases are never found and fixed, and it is machinery added for a presumed bug (see the reactive trigger below). Two things are not backups: a default stated in the interface, and an interim solution (No tradeoffs; Performance), which stands in for the structural fix before it exists, is labeled with its exit, and is removed when the fix lands rather than living beside it.
- A symptom patch replaces the root-cause fix only when that fix is proven impossible; say so and name the root cause.
- If the root-cause fix belongs in a separate change, that is deferral, not stopping: name it; it is still owed.
- Root-cause analysis is always required; reshape the architecture whenever that is the right fix ("large" or "hard" is not a reason not to).
- The trigger is reactive: a real bug authorizes a structural fix; don't add machinery for presumed bugs.
- Structural fixes are usually subtractive (delete the condition), not new abstraction.
- Don't invoke YAGNI to wave off an existing defect.
- Definition: an abstraction lets each piece of a problem's complexity be understood and handled in exactly one place, with as few layers as possible: no other part carries it, and no consumer has to pass through several layers to understand it. The first removes duplication across the system; the second removes stacking in depth. Complexity here means what the problem itself requires to be understood, decided and handled, not the code. "Handled in exactly one place" corresponds to One source of truth (each thing decided in one place); "no other part carries it" corresponds to Keep the core simple (each module has a clear responsibility). Package boundaries and the checks below use this definition.
- Where to start: name the pieces of complexity the problem has, and for each, which layer and which module within it understands and handles it; how to judge the layer is step 1 of Where a judgment starts.
- How to judge: wrong abstractions fall into five kinds; the test common to all five is whether the abstraction reduced the total that has to be understood and handled. Ask each question; a yes means the design is wrong. Each rule lives in the section in brackets.
- Duplication (one piece of complexity handled in more than one place): is the same thing decided in a second place, or done a second way (One source of truth)? Does a consumer have to work out again whether a piece of output supports something, instead of the producer deciding it once and handing it over with the output? Is a result computed before the data is complete, so that it later has to be redone or patched? Does the solution add effort case by case instead of changing the structure once?
- Stacking (complexity spread over layers a consumer must pass through one by one): does a consumer have to pass through several layers to understand it? Example: code wrapped layer within layer becomes flat when a pair of start and end boundary markers replaces the wrapping; a mapping is just a list of segments with no mode, so a reader doesn't first branch on a mode to understand each one.
- Leakage (complexity the abstraction should carry still falls on the consumer: knowing details, following conventions, handling leftover cases): does a host need a handler's details, does a handler route again, or does something silently fall back or skip instead of throwing (One source of truth; Fixing bugs)? Does one part treat a capability another never declared as present, or fill in a default for it; what isn't declared doesn't exist (Correct; One source of truth)? Must people follow an extra convention (Keep the core simple)? Does an interface type reference a dependency the package doesn't need (Clear scope), or does a layer used by many parts reference concrete types instead of describing its input with the smallest structural type it needs? A part the consumer cannot avoid carrying is not leakage once the interface states that the consumer is responsible for it (explicit over magic in Correct).
- Coupling (two independent pieces of complexity merged into one, later separated again with options, flags or special cases): does a request need a special case, option or second path to work (No tradeoffs; if it is still specific to one party after the analysis, the general hook in Keep the core simple)? Does derived output read beyond its own unit's input, or an environment-agnostic module handle environment details (Keep the core simple)? Does the feature grouping fail to line up with the package boundaries (Clear scope)? Example: deciding by file extension whether a file is a certain kind of component merges a language's semantics with file parsing, and makes it look as if an extension option is needed; the right fix is to delete the extension logic.
- Extraneous complexity (the abstraction introduces complexity the problem itself does not have): does a wrapper add features its base lacks (Clear scope)? Does it depart from the platform's or standard's default, or inject something silently (Correct)? Does it add a state, field or flag to express what an existing state already expresses? Example: a computation that fails (throws) has produced no result (Correct), which is the same state as not yet computed; leave it invalid so the next read runs it again (and fails again if the cause remains), instead of storing the failure as a result. An answer such as "not found" is a result, not a failure.
- How to fix: merge duplication into one place; flatten stacking; move leaked complexity back to where it belongs, or state in the interface that the consumer is responsible for it; split coupling apart instead of adding branches; delete extraneous complexity. In every case, find the design assumption that makes the case an exception and change or remove it (No tradeoffs), and remove the structural condition that lets the problem exist (Fixing bugs). Whether a bug or a request triggered the change, its direction is lower total complexity: usually deleting something rather than adding a layer of abstraction; a new way replaces the old one rather than living beside it for good: how the old way is deprecated and when it is removed follow migrate-and-deprecate in Don't reimplement upstream gaps and the versioning rules in Clear scope.
- When to change: only when a real bug or a real request exposes the problem; don't add abstraction or machinery for presumed problems (the reactive trigger in Fixing bugs; no corners without real demand in People). Subtraction is the direction of a change, not a trigger for one.
- Before changing anything, prove which layer owns the problem (yours, an upstream library, the runtime / compiler, the platform, a third party, the user's project or environment). Within one repo, a package whose output you read is upstream too.
- Not yours: hand it off or wait for upstream; don't patch your own layer to hide it. (A workaround in the wrong layer means the owner never learns of it.) The only exception is an interim solution under the No-tradeoffs rules.
- Reduce to a minimal repro; if it reproduces without your layer, it isn't yours.
- You may merge a change and still ask the user to report upstream.
- Capability upstream provides, plans, or should provide: no simplified version, port, or parallel implementation; above all, no port to fill a user-facing feature upstream should own. Only two exceptions: the parallel implementation in the last bullet, and the performance interim under Performance that replaces a heavy dependency.
- Missing API: keep the interface (wiring) without the functionality; mark related tests expected-fail; ask upstream for a concrete API.
- Output an upstream gap makes unreachable (including output you had before moving onto upstream's capability) is a blocker:
- List it, mark its tests expected-fail, report the regression.
- Don't keep it alive through a second path that redoes the same work, a port, or a lightweight analysis; the only exception is the parallel implementation in the last bullet. Anything else follows the interim rules.
- Losing it is an "I want it now" problem, ranked below no reimplementation and one source of truth; "no result beats a wrong result" argues against the unreliable path.
- Example: after moving onto upstream's analysis, one class of input (the generic case) can no longer yield a value because upstream's types fix it; list that class as a blocker and ask upstream, rather than keep your own re-analysis running for every case.
- When upstream lands it: migrate and deprecate the overlap.
- Don't hack platform APIs for a feature, not even once; if a feature can only be built with a hack, don't build it (drop it if it exists) and ask the platform for the API.
- Another team building the same kind of thing in its own project, in parallel with you, is not you redoing upstream in your own repo: duplication alone isn't a sin, and independent work can move faster than a forced merge; judge by final DX and ecosystem, and cooperate at the infrastructure layer.
- Building capability upstream owns in your own code (a parallel implementation) is allowed only if all four hold: upstream has no stable contract or has refused; it does not become a second user-visible truth; a convergence or exit path is written down; it covers only the cases the upstream gap blocks, and the cases upstream handles go through upstream.
- If any part of a set of results or changes is unreliable, discard the whole set.
- Defaults match the behavior of the platform or standard you build on; consistency is not a tradeoff. Don't change a default for one request.
- Predictability over out-of-the-box.
- Users and libraries keep full control of their own code: don't hack its semantics for convenience; be least invasive by default.
- The same version gives the same result in every environment and every entry point (interactive, CLI, CI); not dependent on local dependencies.
- No shortcuts that work only with your product: they teach the wrong path and block moving to something else.
- Don't support technically incorrect behavior until it becomes the norm; guard it with a test.
- Explicit over magic: require explicit configuration, don't inject silently.
- For a behavior change, write a failing test first, then fix.
- Review / reject proposals by "which test does this make fail".
- Can't make it pass yet: mark expected-fail, don't delete. Don't relax a test that asserts the correct behavior to fit the implementation.
- Verify bugs you reported yourself before closing them.
- Don't call a failure flaky without evidence.
- Positive claims (fixed, done, works, same as X, no regression, covered by upstream) need the same evidence as negative ones: a test, a measurement or a repro run in this change, not belief or another agent's text.
- Each thing is decided in exactly one place; all consumers read the same analysis.
- With two truths, keep the one the owning layer produces, not the one that covers the most; the cases it can't cover are blockers. An interim is judged by the interim rules.
- Missing entry: throw, don't silently fall back. (Throwing surfaces drift immediately.)
- Routing (which input goes to which handler) is decided in one place, by the host, from the handlers' own declarations; the host need not know each handler's details.
- A handler only transforms what it is given; on input it can't handle it throws. No re-routing, no silent skipping.
- Avoid multiple ways to do one thing.
- Needs specific to one party: do the complexity analysis first; what remains party-specific stays out of the shared core and is served by one general customization point (hook), not a per-party option.
- Derived output for a unit (generated code, transforms) depends only on that unit's own input, never on other files' contents.
- Don't force third parties to write files specific to your tool.
- No new identifiers, semantics or defaults that everyone downstream must learn or follow (community mental burden).
- No extra conventions (special markers, special naming).
- Every package kept in the repo is exercised by the tests run in everyday development; a package no test exercises is not kept.
- Clear module responsibilities; environment-agnostic modules don't handle environment details (e.g. path normalization; how this is guaranteed: Clear scope).
- Package boundaries come from two things: the right abstraction (defined under Designing abstractions) and dependencies (package by deps). Grouping by feature is not an input to the boundary; when the abstraction and the split are right, the feature grouping follows from them. A package boundary is also a complexity boundary: depending on a package means taking on the load, types and environment it brings in.
- Drawing the boundary: code that uses the same set of dependencies (runtime, environment, heavy libraries) lives in one package; code that doesn't need a dependency doesn't live in a package that has it, so someone using only that code doesn't pay memory and load time for dependencies they don't use.
- Splitting and merging: when part of a package doesn't need one of its dependencies, split that part out; never split or merge only because the features differ.
- A mismatch is a signal: if the grouping you would get by feature doesn't line up with the boundaries the abstraction and dependencies give, the abstraction or the split is wrong; find the wrong assumption and fix it, rather than forcing a split by feature or adding a special case to fit.
- Types count as dependencies: an interface type that references a package depends on it; a package that doesn't need that dependency doesn't reference its types in its interfaces either.
- A new dependency: needing one signals that the feature may not belong in the existing package; do the complexity analysis first instead of adding it so every user pays.
- Dependency direction is upstream / downstream: which layer owns a problem, and where a new feature goes, both read off the dependency graph.
- An environment-agnostic package has no environment dependencies (file system, paths, runtime APIs), so being environment-agnostic is guaranteed by its dependencies, not by discipline.
- Every package / entry point has a clear purpose; reject what exceeds it (including names that would be misread).
- No compat layers / adapters running two tracks; major versions may break cleanly, with migration notes instead.
- Why break, and when it settles: the right structure is found only through repeated structural changes; refusing breaking changes for the sake of stability keeps a wrong structure in place, and it decays as more is built on it. So frequent breaking changes are accepted early (in major versions, as above). Settling is not a ban on breaking: the closer the structure is to right, the less often it needs to break; a structure later found wrong is still fixed (Fixing bugs; How to decide), in a major version. In experience, things are largely stable by about the third, at the latest the fourth, major version; this is an observation, not a rule.
- Keep minor changes additive.
- A wrapper doesn't add features its base lacks.
- When behavior depends on what you don't control: explicit opt-in is the safe default, as an interim solution under the No-tradeoffs rules.
- Report measured numbers and state the ceiling; post status updates where people may misunderstand; say "out of scope" plainly when it isn't the project's identity, and write the analysis down.
- Performance may withhold results (none, delayed, off by default: see opt-in under People), never correctness, and never buys a second truth.
- Existing cases where reliability was given up for performance are debt: each needs a failing test and a payoff plan.
- Always assume the user has a weak machine: single core, 2GB RAM.
- Allocate work by blockability: interactive requests before background work.
- Constraints first, in fixed order, not weighed per case:
- Memory is a hard cap: no swap, no OOM; measure every memory increase and count it as a cost. (Its cost is indirect: swap, longer GC, crowding out other apps.)
- Interactive latency is a floor; never give it up for energy. A separate process for latency is an explicit exception, not an efficiency optimization.
- Correctness against the latency floor: correctness wins, possibly by turning the feature off by default.
- Correctness against the memory cap: both hold and the result is withheld; neither exceeding the cap nor a cheaper wrong result is an option, and the way it is withheld (off by default included) stays within the cap.
- Within the constraints, the single metric is CPU-seconds (user+sys) or joules for the same work: compare implementations and measure an optimization's effect by resource saved; whether to do it is decided by How to decide. Wall-clock and throughput are not targets; report any regression with numbers, measured per case.
- How to find an optimization:
- First establish the shortest path: the minimum steps that must run to produce the required result. The shortest path, like all performance design, is defined over normal execution: a failure that signals a developer error (e.g. a computation that throws every time) is a bug for that developer to fix, not a path to optimize; add no mechanism for it (the problem is theirs: Problem ownership; Fixing bugs). Expected failures (answers like "not found" are results) and recoverable runtime errors (e.g. I/O) are normal execution.
- Then walk through the actual execution step by step and ask of each step why it runs; a step not on the shortest path is deleted. Examples: the same work done more than once; work whose result is never used; a mechanism that exists only to support another step, such as a hand-managed object pool (leave it to the GC), an extra field that an existing field, idle at that point, can replace, or a fast path kept beside the main path and selected by a mode switch.
- If what is deleted is a second path or an extraneous mechanism in the design, it is also duplication or extraneous complexity under Designing abstractions; fix it there.
- Confirm the result with the metric above and measured memory; a deletion without numbers is not an optimization.
- Avoiding a heavy upstream dependency for performance (e.g. extracting a lightweight analysis to replace it) is not a standing exception but an interim. It may be a simplified port of upstream's capability only if all of these hold:
- The upstream capability exists but its form breaks a hard constraint (the memory cap or the interactive-latency floor), proven by measured numbers.
- It replaces the dependency rather than adding another engine (loading a second copy of upstream's engine stays forbidden); after the replacement there is still one analysis for the thing, so it is not a second truth.
- It only does what the dependency was doing, and is never used to keep alive output that is a blocker under Don't reimplement upstream gaps.
- It is labeled where its code lives, naming the right fix (upstream offers a lightweight or incremental form) and the exit; upstream is asked; it migrates when that lands.
- Add a cache only if bounded, high-hit, and actually reducing recomputation; it holds only results that were actually produced (a failure is not one: see Extraneous complexity under Designing abstractions).
- Strongly against: multi-process / multi-worker setups that repeat initialization for disproportionate speedup.
- The objection is repeated initialization, not parallelism; in-process threads sharing loaded data may be cheaper.
- Race-to-idle only helps on multicore; a single-core weak machine gets nothing.
- Disturb users as little as possible: noisy / expensive / slow features are off by default and turned on explicitly (opt-in). Opt-in has only two uses: such features (results Performance withholds count as these), and behavior you don't control under Clear scope (an interim). It is no exit from the analysis (see No tradeoffs).
- Don't reject what you don't understand: ask first, then offer a simpler alternative.
- With a repro, fix fast; without one, ask the user to bisect.
- Don't proactively build corners with no real demand.
- To avoid blocking someone: a temporary solution outside the core that can be removed later is acceptable; state the exit condition. It does not count as the solution; the core does not change; the complexity analysis still happens. If it covers an upstream gap, the interim-solution rules apply.
- Solve with the right mechanism; don't borrow an ill-fitting one.
- Don't spend user trust: don't roll out what the team itself isn't convinced of.
- Correct, predictable, safe (users and their systems come to no harm): rather have no feature for now.
- Problem ownership, no upstream reimplementation, no API hacks: above "I want it now".
- One source of truth: above local convenience.
- Simple core and ecosystem, least invasive by default (under Correct), plus the People bullets on low disturbance, no corners without real demand, and not spending user trust: above satisfying a single user.
- Not blocking people (People), within that bullet's limits.
- Scope and clean breaks.
- The performance target: within the constraints, as few CPU-seconds / joules for the same work as possible.
- The memory cap and the interactive-latency floor are not 7th and take no part in the ordering: every option above, including a temporary unblocking solution, meets them first. How correctness meets them is under Performance.
- How to decide overrides the whole ordering.
- These are ways of judging and don't compete with other principles: No tradeoffs, Fixing bugs and Designing abstractions (step 3 of Where a judgment starts), Tests are evidence (step 4), and the People bullets don't reject what you don't understand (following no rejection without analysis in No tradeoffs), fix fast with a repro (following Tests are evidence), and the right mechanism (following the right structure in step 3).