Lessons / Rule 2
🔍 Understand Before You Change
Trace the architecture, data flow and dependencies first.
Look before you leap — and before you edit.
Imagine rearranging wires in a machine you have never opened. Before changing anything, you look at how it is wired and what each part does.
💡 Key ideas
- Find out how the thing works today
- Follow where the data goes
- Small careful changes beat big risky rewrites
🛠️ How to apply it
- Draw the flow before you change it.
- Change one small thing at a time.
Reading level: 🐣 Simple
A change is only safe relative to what it touches.
Before modifying code, understand the architecture, trace the complete data flow, and identify dependencies, side effects, transactions, queues, retries and existing error handling.
💡 Key ideas
- Map modules, services, APIs and data stores involved
- Find existing auth, transaction boundaries and scheduled jobs
- Check backward-compatibility requirements before you touch a contract
🛠️ How to apply it
- Prefer targeted, incremental changes over unnecessary rewrites
- Write down assumptions and unknowns before editing
⚠️ Common pitfalls
- Rewriting working code because it "looks messy" without understanding why it is shaped that way
Reading level: 🚀 Standard
Most outages are caused by a change made without a map.
Systems carry hidden coupling: a field written by one service, read by three; a retry that assumes idempotency downstream; a cache keyed on something that changes. Understanding means knowing these invisible threads.
💡 Key ideas
- Data flow beats org chart — follow the write path end to end
- Identify side effects: emails, events, cache invalidations, analytics
- Classify compatibility: additive vs breaking, and who consumes it
🛠️ How to apply it
- Produce a short impact analysis (components, data, contracts) before large changes
- Smoke-test the blast radius after the change, not just the changed path
⚠️ Common pitfalls
- Assuming a function is unused because grep found few references
- Ignoring asynchronous consumers of an event or queue payload
Reading level: 🧠 Deep
Community
Ask a question, share your own analogy, or help someone else get it.