# Design Principles

> Applies software design rules beyond syntax (fail-fast, explicit over implicit, composition, illegal states unrepresentable) and runs structured design analysis. Use this skill when reviewing or refactoring for design quality, naming, coupling, or type safety. Do not use when/for UI visual design (use ui-design-principles) or enforcing only fn(args, deps) syntax (use fn-args-deps).

- Skill: `jagreehal/design-principles` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jagreehal/design-principles`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/design-principles/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/design-principles

---


# Design Principles

## Critical rules

- Make the safe thing explicit and the wrong thing unrepresentable.
- Fail fast with context — no `??` chains hiding missing data.
- No `any` / `as` without approval; prefer guards, unions, Zod.
- Explicit deps (`fn(args, deps)`); domain names; immutability by default; no clarifying comments.
- For structured review: run all 8 analysis dimensions after `code-flow-analysis`.
- Before applying rules or running analysis, read [references/principles.md](references/principles.md) and [references/design-analysis.md](references/design-analysis.md).

## Workflow

1. If reviewing a module: invoke `code-flow-analysis` until structure and behavior are clear.
2. Apply critical principles (fail-fast, types, naming, immutability, YAGNI, calisthenics) — detail in [references/principles.md](references/principles.md).
3. For formal review, evaluate all 8 dimensions in [references/design-analysis.md](references/design-analysis.md).
4. Report findings with severity, file:line, snippets, and concrete fixes only.
5. Do not suggest speculative abstractions or unmeasured performance tweaks.

## Resources

- [references/principles.md](references/principles.md) — fail-fast, unions, naming, immutability, YAGNI, rationalizations. Read when refactoring.
- [references/design-analysis.md](references/design-analysis.md) — 8-dimension protocol and report format. Read for design reviews.

## Validation

- [ ] Code understood via `code-flow-analysis` before findings
- [ ] All 8 dimensions covered when doing formal analysis
- [ ] Every finding has file:line and a real snippet
- [ ] No unflagged `any`/`as`/`@ts-ignore`; no `??` fallback chains
- [ ] Illegal states modeled as unions where applicable; domain names used

## Constraints

- Not for prose/article quality (`spine-framework`, `structured-writing`) or large multi-module architecture (`system-architecture`).
- Related: `fn-args-deps`, `result-types`, `strict-typescript`, `code-flow-analysis`, `critical-peer`.