add phil of software design skill

software-design/SKILL.md

@@ -0,0 +1,57 @@
+# Philosophy of Software Design — Codex Skill
+
+## Goal
+
+Design software so it is easy to understand, change, and extend.
+
+## Core rule
+
+Optimize for **lower complexity**, not just fewer lines of code.
+
+## Recommendations
+
+1. **Prefer deep modules.** Hide substantial complexity behind a small, clean interface.
+2. **Keep interfaces simple.** Expose only what callers truly need.
+3. **Hide information aggressively.** Do not leak implementation details across module boundaries.
+4. **Do not pass complexity around.** Solve it where it belongs instead of pushing it onto callers.
+5. **Make the important things obvious.** Favor clarity over cleverness.
+6. **Minimize special cases.** Exceptions, one-off rules, and edge-paths increase cognitive load.
+7. **Design invalid states out of the system.** Prevent mistakes through better APIs and structure.
+8. **Separate mechanism from policy.** Keep reusable machinery distinct from usage-specific decisions.
+9. **Use precise names.** Good naming reduces system-wide confusion.
+10. **Write comments that add information.** Explain why, constraints, invariants, and intent — not what the code already says.
+11. **Document interfaces clearly.** State guarantees, expectations, and failure modes.
+12. **Refactor early when complexity starts rising.** Small structural fixes compound.
+13. **Be consistent.** Similar things should look and behave similarly.
+14. **Protect layering.** Higher-level code should not depend on unnecessary low-level details.
+15. **Write for future readers.** Assume the next editor needs the system to be legible fast.
+
+## Decision filter
+
+Before adding code, ask:
+
+- Does this reduce or increase cognitive load?
+- Does this make future changes easier?
+- Is the interface smaller and clearer?
+- Am I hiding complexity or spreading it?
+- Will another engineer understand this quickly?
+
+## Anti-patterns
+
+Avoid:
+
+- clever abstractions with leaky interfaces
+- shallow modules that add indirection without hiding complexity
+- comments that merely restate code
+- special cases added without simplifying the general model
+- dependency tangles across layers
+
+## Output standard
+
+When generating or editing code:
+
+- favor simple, stable interfaces
+- keep module responsibilities crisp
+- eliminate unnecessary branching and exceptions
+- choose clarity over brevity when they conflict
+- leave the codebase easier to change than before