engineering foundations

Writing Community

Skill notes

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

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.

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

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

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Writing
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

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

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.