# 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