engineering-principles

name

engineering-principles

description

Engineering principles matcher — based on current task and project context, filters applicable development principles and constraints from the principles library, outputting actionable guidance checklists to specs/engineering-principles.md. Does not force inapplicable principles (e.g., won't push TDD on legacy projects without test dependencies). Only outputs principles verified as applicable after context validation. Passively invoked, never auto-triggers. Use this skill when: coding standards, design principles, architecture guidance, code quality, maintainability, extensibility, TDD, DDD, SOLID, design patterns, engineering practices, code review, engineering principles, code quality, best practices, ddd, tdd, bdd, solid, clean code, refactoring suggestions.

Engineering Principles Matcher

This Skill solves a core problem: Models lack engineering discipline when writing code. Not all principles apply to all projects — legacy projects without test frameworks shouldn't be forced into TDD, small projects don't need DDD layering.

Core logic: Sense project context first -> Match applicable principles -> Output actionable constraints.

Core Mechanism

graph LR
    TASK["Current Task"]
    CTX["Project Context Scan<br/>Tech stack / Test framework / Scale / Directory structure"]
    MATCH["Principle Matching<br/>Context conditions -> Applicable principles"]
    OUT["Output<br/>Applicable Principles Checklist + DO/DON'T"]

    TASK --> CTX --> MATCH --> OUT

    style TASK fill:#e3f2fd,stroke:#1976d2
    style CTX fill:#fff3e0,stroke:#f57c00
    style MATCH fill:#f3e5f5,stroke:#7b1fa2
    style OUT fill:#e8f5e9,stroke:#388e3c

Principle Categories and Applicability Conditions

Each principle category has explicit prerequisite conditions — skip if conditions are not met.

Category	Included Principles	Applicability Condition
SOLID	SRP, OCP, LSP, ISP, DIP	Project uses OOP language (TS/Java/Python class)
DDD Layering	Aggregates, bounded contexts, domain services, value objects	Project has clear business domain with >= 3 modules
TDD	Red-green-refactor, test-first, test pyramid	Project has configured test framework (jest/vitest/junit/pytest)
BDD	Gherkin acceptance, scenario-driven	Project has E2E test tools (cypress/playwright)
Design Patterns	Small-scale (Guard Clause/table-driven/Pipe), Classic GoF (Factory/Builder/Decorator/Strategy/Observer/State Machine/Command/Chain of Responsibility), Mid-scale (Pipeline/Circuit Breaker/Worker Pool/Repository), Frontend/Backend/Cross-cutting patterns	Code has identifiable pattern-applicable scenarios
Architecture Patterns	Layered, Hexagonal/Clean Architecture, Microkernel/Plugin, Modular Monolith, Microservices, Event-driven, Serverless	Involves system architecture decisions or project initialization
Anti-patterns	God Object, circular dependency, shotgun surgery, over-abstraction, anemic model, etc.	Code review or refactoring tasks
Clean Code	Naming, function length, comments, readability	Always applicable (unconditional)
Error Handling	Exception classification, boundary validation, defensive programming	Always applicable (unconditional)
Testability	Dependency injection, pure functions, interface isolation	Project has test framework OR new project
Performance Awareness	Avoid N+1, lazy loading, caching strategies	Tasks involving DB queries or API calls
Security Practices	Input validation, SQL injection prevention, XSS, CSRF	Tasks involving user input, API endpoints, authentication

Full principles and DO/DON'T for each category -> references/ corresponding files

Design patterns by scale: design-patterns.md (index) -> patterns-small-scale.md / patterns-classic.md / patterns-module.md / patterns-frontend.md / patterns-backend.md / patterns-crosscut.md / patterns-architecture.md / anti-patterns.md (load on demand)

Context Scanning

Before matching principles, scan project context to determine the following:

Auto-detection Items

Detection Item	Detection Method	Affects Selection
Language/Framework	package.json, pom.xml, pyproject.toml, tsconfig	How SOLID/DDD/design patterns apply
Test Framework	jest.config, vitest.config, pytest.ini, build.gradle	Whether TDD/BDD applies
Project Scale	File count, module count	Whether DDD layering is worth introducing
Directory Structure	Whether layering exists (controller/service/repository)	Whether to continue layered practices
Existing Tests	tests/, .test., .spec.	Current test coverage status
E2E Tools	cypress/, playwright.config	Whether BDD applies
ORM/Database	prisma/, typeorm, mybatis, sequelize	Performance awareness, data modeling principles

Context Tiers

Project Type	Characteristics	Default Applicable Principles
New project	No src/, no package.json or empty project	Clean Code + SOLID + Testability (recommend TDD)
Small project	< 50 files, single module	Clean Code + SOLID + Error Handling
Medium project	50-500 files, 2-5 modules, has tests	All optional (per detection results)
Large project	> 500 files, multi-module	DDD + SOLID + Performance + Security (per detection results)
Legacy project	No test framework, no clear layering	Clean Code + Error Handling + Gradual improvement

Output Format

Principles Checklist

# Engineering Principles Matching Report

## Project Context
- Language/Framework: TypeScript + NestJS
- Test Framework: vitest (configured)
- Project Scale: Medium (~200 files)
- Directory Structure: DDD layering (controller/service/repository)

## Applicable Principles

### Always Applicable
- **Clean Code**: Functions <= 30 lines, meaningful variable names, no magic numbers
- **Error Handling**: Business vs system exception classification, never swallow exceptions

### Applicable Per Detection
- **SOLID (OOP)**: Class usage detected -> SRP, OCP, DIP applicable
- **TDD**: vitest detected -> New features should write tests first
- **DDD Layering**: controller/service/repository structure detected -> Continue
- **Testability**: Dependency injection in use (NestJS @Injectable) -> Continue following
- **Performance**: Database involved -> Watch for N+1, add necessary indexes

### Not Applicable (Skip Reasons)
- **BDD**: No E2E framework detected (no cypress/playwright)
- **Design Patterns - Factory/Strategy**: Current task doesn't involve polymorphism/strategy selection

Single Principle Constraints (Embedded in Coding)

When the model executes coding tasks, applicable principles are embedded as brief constraints:

[Principle Constraints]
- SRP: Each class/function does only one thing
- OCP: Extend through interfaces, don't modify existing classes
- TDD: Write failing test first -> pass -> refactor
- Error Handling: Use custom exception classes, not strings

Python Script

python scripts/principles_matcher.py match --root <project_root> [--task <task description>] [--format json|markdown]

• --root: Project path for context scanning
• --task: Task description (optional) for more precise principle matching
• Without --root, only generic matching based on task description

Script implementation -> scripts/principles_matcher.py