kylejryan/systems-design-patterns
skills/systems-design-patterns/SKILL.md
Staff+ engineering patterns for maximum leverage per line of code. Use this skill when designing abstractions, building reusable primitives, creating shared libraries, reducing code through architecture, reviewing code for leverage and reuse potential, choosing between building vs configuring, or establishing conventions and patterns across a codebase.
$ install --global
skillsauthnpx skillsauth add kylejryan/better-code systems-design-patternsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 6, 2026, 7:49 AM224.9s22 files scanned
SKILL.md
- name:
- systems-design-patterns
- description:
- Staff+ engineering patterns for maximum leverage per line of code. Use this skill when designing abstractions, building reusable primitives, creating shared libraries, reducing code through architecture, reviewing code for leverage and reuse potential, choosing between building vs configuring, or establishing conventions and patterns across a codebase.
- license:
- MIT
- author:
- kylejryan
- version:
- 1.0.0
- organization:
- kylejryan
- date:
- March 2026
- abstract:
- Systems-level code leverage guide for staff-plus engineers. Covers leverage mindset (primitives over features, lines as liability), abstraction design (Three Cs, vocabulary layers, extraction decisions), minimum code patterns (convention over configuration, schema-driven development, registries, pipelines), system boundaries (internal APIs as products, DRY across boundaries), code reduction through design (eliminate states, branching, ceremony), and a review lens for evaluating existence, placement, shape, minimum, and composability.
Systems Design Patterns
Every line you write is a line someone must read, understand, test, debug, and maintain. The goal: engineers working in this codebase should feel like they're assembling, not building. The hard problems are solved once, in the right place, and everything else is composition.
When to Apply
Apply leverage thinking when:
- Designing abstractions or shared libraries
- Building reusable primitives or frameworks
- Choosing between building new code vs configuring existing code
- Reviewing code for leverage and reuse potential
- Establishing conventions and patterns across a codebase
- Evaluating whether code should be data instead
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Leverage Mindset | CRITICAL | mindset- |
| 2 | Abstraction Design | CRITICAL | abstraction- |
| 3 | Minimum Code Patterns | HIGH | pattern- |
| 4 | System Boundaries | HIGH | boundary- |
| 5 | Code Reduction | MEDIUM-HIGH | reduce- |
| 6 | Review Lens | MEDIUM | review- |
Core Principles
Think in Primitives: Features are one-time. Primitives are forever. Decompose every feature: Feature = Primitive A + Primitive B + Glue(A, B). Build A and B as reusable. Keep the glue thin.
Lines of Code Are Liability: Before writing anything, ask: Does this already exist? Should this be data instead of code? How many future features does this unlock? What's the smallest useful version?
The Three Cs: Every abstraction must be Composable (combines without special-casing), Constraining (makes incorrect usage hard), and Complete (handles the full problem within its boundary).
Thin Glue Principle: Application-specific code should be 10-15% of the codebase. If feature code is 70%, every new feature costs as much as the first — there's no compounding.
How to Use
Read individual reference files for detailed explanations and examples:
references/mindset-primitives.md
references/abstraction-three-cs.md
references/pattern-registry.md
references/reduce-eliminate-states.md
references/_sections.md
Each reference file contains:
- Brief explanation of the principle and why it matters
- Incorrect approach with explanation
- Correct approach with explanation
- Additional context and trade-offs
Code Leverage Checklist
Before committing code, verify:
- Searched for existing solutions (codebase, stdlib, packages) before writing new code
- Logic that could be data/config IS data/config
- New primitives are named for what they ARE, not where they're USED
- Abstractions satisfy the Three Cs (Composable, Constraining, Complete)
- Vocabulary doesn't leak across layers
- Adding the next similar feature requires configuration, not code
- No boolean soup — states are modeled explicitly
- Branching is minimized via polymorphism, dispatch, defaults
- Feature-specific code is thin glue between reusable pieces
- Every function, class, and module earns its existence
Related Skills
kylejryan/targeted-vuln-analysis
development
VerifiedTrustedCommunity
Use this skill when performing the actual vulnerability analysis AFTER a threat model has been established (see threat-model skill). Triggers when the user asks to find vulnerabilities, audit code for security, hunt for bugs, or perform security review of source code AND a threat model already exists or the codebase context is clear. This skill enforces depth-first, exploitability-proven analysis — it actively prevents the breadth-first pattern-matching that produces lists of theoretical vulnerabilities. Do NOT use without a threat model; use threat-model skill first. Do NOT use for general code quality review.
1SKILL.mdUpdated May 6, 2026
kylejryan/software-testing
development
VerifiedTrustedCommunity
Use this skill when designing test strategies, writing tests beyond basic unit tests, verifying software for production readiness, or improving test coverage and reliability. Triggers when the user asks about testing strategy, integration tests, end-to-end tests, contract tests, property-based tests, load tests, chaos testing, test architecture, flaky tests, test confidence, 'how do I test this,' 'how do I know this is safe to deploy,' 'my tests are flaky,' 'what should I test,' 'test coverage,' CI/CD test pipelines, or any question about software verification and validation. Also triggers when the user is shipping a change and wants confidence it won't break production. Primarily targets TypeScript and Go but principles apply universally. Do NOT use for writing basic unit tests for simple functions — this skill is for the harder testing questions.
1SKILL.mdUpdated May 6, 2026
kylejryan/root-cause-analysis
development
VerifiedTrustedCommunity
Use this skill when debugging software issues, performing root cause analysis, triaging errors from logs or alerts, or investigating why code isn't working as expected. Triggers when the user shares an error message, stack trace, log output, failing test, unexpected behavior, crash report, performance degradation, or says things like 'this isn't working,' 'I'm getting an error,' 'help me debug,' 'why is this failing,' 'something broke,' or 'I can't figure out what's wrong.' Also use when the user has been going back and forth trying fixes that aren't working — this is the signal to stop guessing and start systematically diagnosing. Do NOT use for writing new code from scratch, general code review, or feature development unless a bug is involved.
1SKILL.mdUpdated May 6, 2026
kylejryan/principal-review
development
VerifiedTrustedCommunity
Principal-engineer / architect review loop driven by desired state and invariants rather than feature lists. Use this skill when scoping a new initiative, kicking off a feature or refactor, reviewing a design doc or PR for over-scope, cutting work that isn't paying for itself, deciding what to defer, or reviewing whether a system actually reaches the state it claims. Triggers on phrases like "what should we cut," "is this the right scope," "what are the invariants here," "are we over-engineering," "design review," "principal review," "architect review," "what must be true when this is done," or whenever the team is choosing between building more vs. building right.
1SKILL.mdUpdated May 6, 2026