skills/software-design/SKILL.md

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