Agent Skills: 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 and 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.
3. For formal review, evaluate all 8 dimensions in 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 — fail-fast, unions, naming, immutability, YAGNI, rationalizations. Read when refactoring.
• 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.