engineering-foundations

name	engineering-foundations
description	Language-agnostic engineering methodology — DDD, Hexagonal Architecture, TDD, architecture planning, requirements gathering, code review, and ADR writing. Use when the user asks HOW to approach something at the pattern/theory level, regardless of framework. This is the source of truth for DDD concepts (aggregates, domain events, rich models), architecture layers (presentation, application, domain, infrastructure), and testing methodology. Framework-specific implementations live in separate plugins (nestjs-toolkit, django-toolkit, nextjs-toolkit). Triggers for 'how should I test this', 'what is DDD', 'explain domain modeling', 'write an ADR', 'plan this feature', 'what are aggregates', 'hexagonal architecture'. DO NOT use for executing development work (use ai-dlc) or framework-specific questions (use the relevant framework plugin). Use when this capability is needed.
metadata	{"author":"anpham1925"}

Recommended model: Opus — This skill involves deep reasoning, architecture decisions, or code review.

Opinionated, language-agnostic engineering methodology. Before applying any topic, read its reference file in reference/.

Topics

Topic	When to Use	Reference
TDD	Writing unit tests, e2e tests, fixing failing tests	reference/tdd.md
Domain Modeling	Implementing rich domain models with business rules, state transitions	reference/domain-model.md
Code Review	Reviewing PRs, validating code quality, self-review	reference/code-review.md
Requirements	Gathering requirements, clarifying business logic, defining scope	reference/requirements.md
Architecture Planning	Planning features, making architectural decisions, designing solutions	reference/architecture.md
Deep Modules	Judging interface-vs-implementation ratio, choosing where to draw module boundaries, classifying dependencies	reference/deep-modules.md
ADR Writing	Documenting significant architectural decisions	reference/adr.md

Gotchas

Claude-specific failure modes in engineering methodology:

• Hardcoding dates in tests — Claude's most persistent bad habit. Always use dynamic date generation (new Date(), relative offsets). Never '2024-01-15'.
• Modifying existing tests to make them pass — When a test fails, Claude's instinct is to "fix" the test. Fix the application code instead. Only modify tests if the requirements changed.
• Mocking internal modules in e2e tests — Claude mocks everything for convenience. In e2e tests, only mock external services (payment APIs, auth providers). Internal services, handlers, guards, and repositories must be real.
• One giant PR with no intermediate commits — Claude builds everything then commits once. Commit after each TDD Green phase.
• Designing from scratch when patterns exist — Claude invents new architectures instead of finding the closest existing implementation in the codebase. Always search for similar code first.
• Presenting only one option — Architecture planning requires 2-3 options with trade-offs. Claude tends to present its preferred approach as the only option.
• ADRs with no "Rejected Alternatives" — Claude writes ADRs that only describe the chosen approach. The rejected alternatives section is the most valuable part.
• Skipping the "what's out of scope" section — Requirements must explicitly define what is NOT being built. Claude omits this, leading to scope creep.

General Principles

Principle	What to Do
Clarify Constraints	Scale? Budget? Existing systems? Timeline? MVP or production?
Prioritize Simplicity	Simplest solution that works. "The best code is no code."
Security by Design	Least privilege, encryption, input validation, parameterized queries
Present Options	2-3 options with trade-offs. Then recommend one.

Quick Decision Guide

Need to write/fix tests?
  -> Read reference/tdd.md

Need to design a domain model?
  -> Read reference/domain-model.md

Need to review code?
  -> Read reference/code-review.md

Need to gather or clarify requirements?
  -> Read reference/requirements.md

Need to plan a feature or make architecture decisions?
  -> Read reference/architecture.md

Need to judge a module boundary, or decide if something is "too shallow"?
  -> Read reference/deep-modules.md

Need to document a significant decision?
  -> Read reference/adr.md

---

Source: anpham1925/claude-marketplace — distributed by TomeVault.