# Engineering Foundations

> 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.

- Skill: `tomevault-io/engineering-foundations` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/engineering-foundations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/engineering-foundations/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/engineering-foundations

---


> **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](https://github.com/anpham1925/claude-marketplace) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->