Engineering judgment, decision-making principles, and code quality standards. Use when making architectural choices, evaluating trade-offs, determining implementation approaches, assessing code quality, or balancing speed vs thoroughness. Provides foundational senior engineer mindset covering when to proceed vs ask, when to refactor, security awareness, and avoiding over-engineering.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
references/type-patterns.mdEngineering judgment → thoughtful decisions → quality code.
<when_to_use>
NOT for: mechanical tasks, clear-cut decisions, following explicit instructions </when_to_use>
<principles> Core engineering judgment framework.User preferences trump defaults CLAUDE.md, project rules, existing patterns always override skill suggestions. Read them first.
Simplest thing that works Start with straightforward solution. Add complexity only when requirements demand it.
Read before write Understand existing codebase patterns before modifying.
Small, focused changes One idea per commit, typically 20–100 effective LOC, touching 1–5 files.
Security awareness Don't introduce vulnerabilities through careless implementation.
Know when to stop Ship working code, don't gold-plate.
<type_safety> Type safety principles that apply across languages.
Make illegal states unrepresentable The type system should prevent invalid data at compile time, not runtime. If a state combination is impossible, make it unexpressable in types.
Type safety hierarchy:
Parse, don't validate Transform untyped data into typed data at system boundaries. Once parsed into a type, trust the type throughout the codebase.
Result types over exceptions Make errors explicit in function signatures. Callers should see from the type that a function can fail—don't hide failures in thrown exceptions.
Discriminated unions for state Model mutually exclusive states as union types with a discriminator field. Prevents impossible state combinations (loading + error + data simultaneously).
Branded types for domain concepts Wrap primitives in distinct types to prevent mixing (user IDs vs product IDs). Enforce validation at construction time.
Runtime validation at boundaries External data (APIs, files, user input) enters the system untyped. Validate and parse at the boundary, then work with typed data internally.
See type-patterns.md for detailed concepts.
Load typescript-dev/SKILL.md for TypeScript-specific implementations.
</type_safety>
<decision_framework> Systematic approach to engineering choices.
Understand before deciding
Consider trade-offs No perfect solutions, only trade-offs:
Recognize good-enough Perfect is enemy of shipped:
If yes to all → ship it. Don't block on theoretical improvements.
Document significant choices When making non-obvious decisions:
Example:
// Using simple polling instead of WebSocket because:
// - Simpler to implement and maintain
// - Acceptable for current 5-minute update interval
// - Can migrate to WebSocket if requirements tighten
</decision_framework>
<when_to_ask> Balance autonomy with collaboration.
Proceed independently when:
Ask questions when:
Escalate immediately when:
Don't guess on high-stakes decisions. Ask. </when_to_ask>
<code_quality> Standards that separate good from professional code.
Type safety Make illegal states unrepresentable:
// Bad: stringly-typed state
type Status = string;
// Good: discriminated union
type Status = 'pending' | 'approved' | 'rejected';
// Better: type-safe with data
type Request =
| { status: 'pending' }
| { status: 'approved'; by: User; at: Date }
| { status: 'rejected'; reason: string };
Error handling Every error path needs handling:
// Bad: ignoring errors
await saveUser(user);
// Good: explicit handling
const result = await saveUser(user);
if (result.type === 'error') {
logger.error('Failed to save user', result.error);
return { type: 'error', message: 'Could not save user' };
}
Naming Names reveal intent:
calculateTotal, validateEmail)userId, orderTotal)isValid, hasPermission)Function design Single responsibility, focused scope:
Comments Explain why, not what:
// Bad
// Set user active to true
user.active = true;
// Good
// Mark user active to enable login after email verification
user.active = true;
</code_quality>
<refactoring> When and how to improve existing code.Refactor when:
Don't refactor when:
Refactoring guidelines:
Separate commits:
# Good: refactor separate from feature
git commit -m "refactor: extract user validation logic"
git commit -m "feat: add email verification"
# Bad: mixed changes
git commit -m "feat: add email verification and refactor validation"
Test the right things:
Don't over-test:
Coverage targets:
Low coverage acceptable for:
Premature optimization is root of all evil
Optimize when:
Before optimizing:
Don't optimize:
Input validation:
Authentication/Authorization:
Data handling:
Dependencies:
Red flags to escalate:
<anti_patterns> Common mistakes to avoid.
Over-engineering:
Fix: YAGNI (You Aren't Gonna Need It). Build for today's requirements.
Under-engineering:
Fix: Basic quality standards aren't optional. Handle errors, validate inputs.
Scope creep:
Fix: Stay focused. File issues for unrelated improvements.
Guess-and-check:
Fix: Use systematic debugging. Understand before changing.
Analysis paralysis:
Fix: Good enough + shipping > perfect + delayed. Iterate. </anti_patterns>
<communication> How senior engineers collaborate.Writing clear issues/PRs:
Code review:
When blocked:
Saying no:
Back opinions with reasoning, stay open to being wrong. </communication>
<workflow_integration> Connect with other baselayer skills.
With TDD:
With debugging:
With dev- skills:*
Software engineering skill provides the "why" and "when". dev-* skills provide the "how" for specific technologies. </workflow_integration>
<rules> ALWAYS: - Read CLAUDE.md and project rules first - Follow existing codebase patterns - Make small, focused changes - Validate external input - Handle errors explicitly - Test critical paths - Document non-obvious decisions - Ask when uncertain on high-stakes issuesNEVER:
Core Practices:
Development Skills (load dev-*/SKILL.md for implementation patterns):
Type Safety Concepts:
Standards: