| name | software-laws |
| description | Reference guide for 56 canonical laws, principles, and heuristics of software engineering — Conway's Law, Brooks's Law, Hyrum's Law, YAGNI, DRY, SOLID, CAP theorem, and more. Triggers when discussing architectural trade-offs, team scaling, process design, code quality principles, or decision-making heuristics, to provide succinct historically-grounded guidance. |
| argument-hint | audit |
| metadata | {"priority":4,"docs":["https://lawsofsoftwareengineering.com/"]} |
| retrieval | {"aliases":["software laws","engineering principles","software heuristics","famous laws","programming principles"],"intents":["apply software engineering principle","reference a famous law","architectural trade-off","team scaling decision","explain a design heuristic"],"entities":["Conway","Brooks","Hyrum","YAGNI","DRY","KISS","SOLID","CAP","Postel","Murphy","Amdahl","Metcalfe","Pareto","Occam","Goodhart","Parkinson"]} |
Software Laws
A curated collection of 56 established laws, principles, and heuristics that shape software engineering practice. Each law lives in its own markdown file with frontmatter (category, level, summary, source), organized to inform architectural choices, team design, quality practices, and decision-making.
Command: "audit"
When invoked with the audit argument, do a full audit of the user's codebase and engineering practices through the lens of all 56 laws in this skill, and produce actionable, concrete feedback and recommendations. Inspect the architecture, code quality, team/process signals visible in the repo (CI, ownership, branching), and decision-making artifacts. Identify specific violations or opportunities tied to named laws, and prioritize the findings by impact. Each recommendation should reference the law, point to the exact file/module/process, and propose a concrete change — not generic advice.
When to Apply
Reference these guidelines when:
- Making architectural or design decisions that will be hard to reverse
- Scaling a team or reorganizing around a system
- Writing or reviewing code where simplicity vs. flexibility is at stake
- Estimating, planning, or assessing why a project is late
- Weighing cognitive biases or heuristics during a technical decision
- Explaining trade-offs to collaborators with a named, well-established principle
Categories by Priority
| Priority | Category | Focus | Count |
|---|
| 1 | Design | Daily coding principles | 6 |
| 2 | Architecture | System-shaping trade-offs | 10 |
| 3 | Quality | Code stewardship over time | 11 |
| 4 | Teams | Org dynamics & communication | 9 |
| 5 | Planning | Estimation & process | 6 |
| 6 | Decisions | Mental models & biases | 12 |
| 7 | Scale | Performance & network effects | 3 |
Quick Reference
1. Design (6)
yagni — Don't build features until you actually need themdry-principle — Every piece of knowledge has one authoritative representationkiss-principle — Keep it simple; complexity is the enemysolid-principles — Five OO design rules for maintainable classeslaw-of-demeter — Only talk to immediate collaborators (principle of least knowledge)principle-of-least-astonishment — Components should behave the way users expect
2. Architecture (10)
hyrums-law — With enough users, every observable behavior becomes a contractgalls-law — Complex systems that work evolved from simple systems that workedlaw-of-leaky-abstractions — All non-trivial abstractions eventually leakteslers-law — Complexity is conserved — you can only shift it, not remove itcap-theorem — Pick two of consistency, availability, partition tolerancesecond-system-effect — Second designs over-engineer everything the first one lackedfallacies-of-distributed-computing — 8 assumptions about networks that always bite youlaw-of-unintended-consequences — Actions in complex systems produce effects you didn't plan forzawinskis-law — Every program expands until it can read emailconways-law — Systems mirror the communication structure of the organization
3. Quality (11)
boy-scout-rule — Leave the code better than you found itmurphys-law — Anything that can go wrong, willpostels-law — Be conservative in what you send, liberal in what you acceptbroken-windows-theory — Small visible decay invites more decaytechnical-debt — Shortcuts accrue interest; pay them down deliberatelylinuss-law — Given enough eyeballs, all bugs are shallowkernighans-law — Debugging is twice as hard as writing code, so don't be too clevertesting-pyramid — Many unit tests, some integration, few end-to-endpesticide-paradox — Repeated tests stop finding new bugs; evolve themlehmans-laws — Software either evolves continuously or becomes irrelevantsturgeons-law — Ninety percent of everything is crud
4. Teams (9)
brooks-law — Adding people to a late project makes it laterdunbars-number — Humans maintain stable relationships with ~150 peopleringelmann-effect — Per-person productivity drops as team size growsprices-law — Half the output comes from the square root of contributorsputts-law — Tech is dominated by people who understand what they do not manage and vice versapeter-principle — People rise to their level of incompetencebus-factor — How many people can be hit by a bus before the project diesdilbert-principle — Incompetent employees get promoted to management to limit their damageconways-law — (Also relevant to architecture; see above)
5. Planning (6)
premature-optimization — Premature optimization is the root of all evil (Knuth)parkinsons-law — Work expands to fill the time availableninety-ninety-rule — The first 90% takes 90% of the time; the last 10% takes the other 90%hofstadters-law — It always takes longer than you expect, even accounting for Hofstadter's Lawgoodharts-law — When a measure becomes a target, it ceases to be a good measuregilbs-law — Anything you need to quantify can be measured well enough to beat not measuring at all
6. Decisions (12)
dunning-kruger-effect — Low competence correlates with over-confidencehanlons-razor — Never attribute to malice what is explained by ignoranceoccams-razor — Prefer the explanation with fewer assumptionssunk-cost-fallacy — Past investment shouldn't dictate future decisionsmap-is-not-the-territory — Your model is not the real systemconfirmation-bias — You seek evidence that confirms what you already believehype-cycle-amaras-law — We overestimate tech short-term, underestimate it long-termlindy-effect — The longer something has survived, the longer it likely willfirst-principles-thinking — Break problems down to fundamental truths and reason upinversion — Solve problems by thinking about what would cause failurepareto-principle — 80% of effects come from 20% of causescunninghams-law — The fastest way to get a correct answer is to post a wrong one
7. Scale (3)
amdahls-law — Speedup from parallelization is limited by the serial portiongustafsons-law — With larger workloads, parallelization scales better than Amdahl suggestsmetcalfes-law — The value of a network grows with the square of its users
How to Use
Read individual law files for full context — takeaways, overview, examples, and origins:
laws/conways-law.md
laws/brooks-law.md
laws/hyrums-law.md
Each law file contains:
- A short summary and category in frontmatter
- A level tag (Junior / Mid-Level / Senior) where the source site provides one
- Takeaways — the actionable point
- Overview — the full principle explained
- Examples — concrete scenarios showing the law in practice
- Origins — who coined it and when
- Related notes — connections to adjacent laws, where relevant
- Source URL back to lawsofsoftwareengineering.com
Full Index
See README.md for a categorized index of all 56 laws with clickable links.
