software-engineering

Core engineering principles for quality, maintainable code.

📖 中文导读:Core engineering principles for quality, maintainable code. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: software-engineering description: Core engineering principles for quality, maintainable code.

Software Engineering Standards

Apply these principles to all code.

Core Principles

  • Type-safety (aim for e2e type-safety)
  • Monitoring/observability/profiling/tracing
  • Automated tests (unit, integration, e2e when applicable)
  • Error handling with meaningful messages and proper recovery
  • Security-first approach (validate inputs, sanitize outputs)

Naming & Clarity

  • Be concrete: retryAfterMs > timeout, emailValidator > validator
  • Use domain language consistently across the codebase
  • Prefer explicit over clever code
  • Function names should describe what they do, not how
  • Boolean variables: use is, has, should, can prefixes

Code Organization

  • Keep code close to where it's used (unless used 2-3+ times)
  • Single responsibility per module/function
  • Avoid deep nesting (prefer early returns)
  • Group related functionality together
  • Separate concerns: data, logic, presentation

Error Handling

  • Never swallow errors silently
  • Provide actionable error messages
  • Use typed errors when possible
  • Log errors with context (what, where, why)
  • Fail fast in development, gracefully in production

Performance Awareness

  • Measure before optimizing
  • Consider time and space complexity
  • Avoid premature optimization
  • Profile hot paths in production
  • Cache expensive computations appropriately

Documentation

  • Code should be self-documenting when possible
  • Document "why", not "what" (code shows what)
  • Keep docs close to code (JSDoc, inline comments)
  • Update docs when changing behavior