software-engineering

WallysonGalvao's avatarfrom WallysonGalvao

Core engineering principles for quality, maintainable code.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026
[Architecture Design]

When & Why to Use This Skill

This Claude skill serves as a comprehensive guide for implementing core software engineering principles to ensure the delivery of high-quality, maintainable, and scalable code. It emphasizes essential practices such as end-to-end type-safety, functional programming, and the KISS (Keep It Simple, Stupid) principle. By providing clear standards for naming conventions, code organization, and robust error handling, it helps development teams reduce technical debt and improve long-term project velocity.

Use Cases

  • Codebase Standardization: Establish and enforce consistent naming conventions and organizational structures across a team to ensure the code is as readable as a journal.
  • Refactoring Legacy Systems: Apply principles like 'KISS' and 'YAGNI' to simplify over-engineered components and remove useless abstractions from existing projects.
  • Implementing Test-Driven Development: Utilize behavior-focused testing strategies and automated CI pipelines to prevent bug re-occurrence and ensure system stability.
  • Security and Accessibility Integration: Incorporate OWASP security best practices and WCAG accessibility guidelines into the initial design phase to build secure and inclusive applications.
namesoftware-engineering
descriptionCore 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
  • Simplicity (KISS, YAGNI, no clutter)
  • Functional programming (immutability, high order functions)
  • Automation (CI pipelines for builds and tests)

Naming & Clarity

  • Be concrete: retryAfterMs > timeout, emailValidator > validator
  • Avoid vague terms: data, item, list, component, info
  • Every character must earn its place
  • Use nested objects for context: config.public.ENV_NAME instead of ENV_NAME

Code Organization

  • Keep code close to where it's used (unless used 2-3+ times)
  • A folder with a single file should be a single file
  • Comments are unnecessary 98% of the time (convert to functions/variables)
  • Code is reference, history, and functionality - must be readable as a journal

Error Handling

  • Always provide user feedback
  • Log errors with observability tools
  • Use HighOrderFunctions for monitoring/error handling/profiling

Testing

  • Test behavior, not implementation
  • Write test for each bug fixed (prevents re-occurrence)
  • 3rd person verbs (not "should")
  • Organize with describe blocks

Security & Accessibility

  • Follow OWASP best practices
  • Strive for WCAG 2.0 guidelines
  • Don't write pure SQL strings; use query-builders for injection protection

Avoid

  • Premature optimization
  • Useless abstractions (functions that mainly call one function, helpers used only once)
  • Over-engineering