Abstraction Has a Cost
Every abstraction creates a debt of understanding.
Abstractions save repetition only when their purpose remains legible.
32 teachings · 8 disciplines
The Scrolls
Maxims for memory. Interpretations for judgment. Practices for real engineering work.
Filter scrolls
Networked Assumptions
A distributed system is a collection of assumptions connected by a network.
Design around latency, partial failure, ordering, and ownership—not the happy-path diagram.
Complexity Leaves Slowly
Complexity enters quietly and leaves with a migration plan.
Small exceptions accumulate; removing them requires ownership and a staged path.
Choose the Pain
Architecture is the art of choosing which future pain to accept.
Every design trades one kind of cost for another; make that bargain visible.
Commit with Intent
Commit with intent.
A commit should capture one coherent decision and explain why it exists.
The Chainsaw
The force-push is powerful. So is the chainsaw.
Rewrite shared history only with awareness, coordination, and protection.
History Tells the Truth
A clean history should tell the truth, not rewrite reality.
Curate history for comprehension without concealing decisions, reversals, or risk.
Branch Archaeology
A branch without an owner becomes archaeology.
Long-lived branches need a purpose, a steward, and a clear end condition.
Confident Code
Untested code is merely confident code.
Confidence is a feeling; tests are repeatable evidence about behavior.
Preserve the Lesson
Tests do not prove wisdom. They preserve lessons.
A strong suite records what the team learned from requirements and failures.
Understand the Mock
Mock what you must. Understand what you mock.
Every substitute encodes assumptions about a dependency that may drift from reality.
Ignored Warnings
A flaky test teaches the team to ignore warnings.
Intermittent failures erode trust in the entire feedback system.
The Final Reviewer
Production is the final reviewer.
Real traffic, data, dependencies, and timing reveal what controlled environments cannot.
Rollback Is Not Defeat
Rollback is not defeat. It is mastery over attachment.
Recovery protects users; pride protects only the story we tell ourselves.
Boring Deployments
Deployments should be boring. Incidents provide enough excitement.
Automation, small batches, and clear signals turn release into routine.
Friday Is a State of Mind
Friday is a state of mind. The rollback plan is not.
Calendar rules are proxies; readiness and recovery are the real controls.
Silence Is Not Health
The absence of alerts is not evidence of health.
Silence can mean success, missing coverage, broken telemetry, or thresholds set too high.
Observe to Understand
What cannot be observed cannot be understood.
Instrumentation makes runtime behavior available to engineering judgment.
Logs Remember
Logs remember what developers forget.
Useful events preserve context long after the deployment conversation has ended.
Decision, Not Decoration
A dashboard without a decision is decoration.
Every visualization should answer a question or support a specific action.
Verify the Boundary
Trust is not a security control.
Relationships and good intentions do not constrain what credentials or systems can do.
Respect Future Mistakes
Least privilege is respect for future mistakes.
Limit authority so ordinary errors remain small, explainable, and recoverable.
Git Never Forgets
Secrets do not belong in Git, even private Git.
Repository privacy does not provide rotation, access scoping, or reliable erasure.
Someone Else’s Input
Every exposed interface becomes someone else’s input.
Anything reachable will receive malformed, surprising, and adversarial data.
Successful Enough
Legacy code is code that succeeded long enough to become inconvenient.
Age often signals delivered value and accumulated constraints, not incompetence.
Discover What It Knows
Before rewriting the old system, discover what it knows.
Undocumented behavior is still behavior, especially to customers and operations.
Refactor with Humility
Refactor with humility.
Improve structure while respecting behavior you may not yet understand.
The Strangest Line
The strangest line may be holding back the oldest incident.
Odd code deserves investigation before deletion; context may have outlived its comment.
Share the Knowledge
Knowledge hoarded is a single point of failure.
Expertise becomes resilience only when others can find, question, and practice it.
Review the Work
Review the code, not the coder.
Specific, evidence-based feedback improves the change without reducing the person.
Brilliance Must Travel
A brilliant solution nobody understands is an operational liability.
A solution is only complete when the team can safely change and operate it.
Message to the Future
Documentation is a message to the teammate who arrives during the incident.
Write for a capable reader with little context and no spare attention.
404 // FILTER
No teaching found
Try another term or reset the filters.