backend
Skill8 starsChanged 44 days agoMITView on GitHub
Backend development skill for microservices following Clean Architecture, CQRS with a transactional outbox, the repository/use-case pattern, and a Testing-Trophy strategy.
- Reads credentials
20 other projects use a version of this.
Adopted by
Most recently taken up by
- nomorehappypath/nomorehappypaththeir own version, first seen Nov 15, 2026
- gabros20/backend-skilltheir own version, first seen Nov 1, 2026
- hushh-labs/hushh-researchtheir own version, first seen Nov 1, 2026
- darknecrocities/SkillBuildertheir own version, first seen Nov 1, 2026
- marcusbelz/di2-starter-kittheir own version, first seen Oct 31, 2026
- hilmifawwazsaad/NextJS-js-Boilerplatetheir own version, first seen Oct 20, 2026
Used with
Projects with it also use security, devops and 4 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
0xSeroSkillsecurity
Also in 5 projects that use this
mrgoonieSkilldevops
Deploy to Cloudflare (Workers, R2, D1), Docker, GCP (Cloud Run, GKE), Kubernetes (kubectl, Helm). Use for serverless, containers, CI/CD, GitOps, security audit.
Also in 3 projects that use this
MicrosoftSkillhelp
Entry point for the MedImageInsight plugin, covering the getting-started walkthrough, how the skills work, what MI2 is, and troubleshooting.
Also in 3 projects that use this
OpenAISkillsupabase
Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector).
Also in 3 projects that use this
VercelSkilldeploy
Deploy applications to Vercel. Use when the user says "deploy", "deploy to Vercel", "push to production", "deploy my app", or "go live".
Also in 3 projects that use this
NVIDIASkilltesting
Run Python and Rust tests for physicsnemo-curator using uv + pytest with coverage reporting via pytest-cov, and cargo-nextest for Rust tests. Includes benchmark workflows with pytest-benchmark and criterion.
Also in 4 projects that use this
Other versions20 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 20
- langwatch/langwatch★ 5ksame name
- AlexPEClub/ai-coding-starter-kit★ 382same name
- hushh-labs/hushh-research★ 40same name
- nomorehappypath/nomorehappypath★ 22same name
- ElmatadorZ/skynetclaw★ 16same name
- DojoCodingLabs/code-sensei★ 14same name
- darknecrocities/SkillBuilder★ 13same name
- udaysharmadev/Skills★ 13same name
- darker2016/WorkbuddySkillGroups4DSH★ 6same name
- MarvelCollin/agent-skills★ 5same name
10 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- context/CLAUDE.mdCLAUDE.md
- api-designSkill
- cavemanSkill
- commitSkill
- evaluator-optimizerSkill
- frontend-design-systemSkill
- interactive-live-testingSkill
- module-planningSkill
- multi-agent-orchestrationSkill
- plan-featureSkill
- prSkill
- ralph-loopSkill
- review-boardSkill
- reviewSkill
- systematic-debuggingSkill
- tdd-workflowSkill
- verification-before-completionSkill
- verificationSkill
- work-recordingSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. 0 are common, 15 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 17 edited versions we read keep these.
15
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 58
Every service should follow this structure.
- Distinctive: line 117
If the system is multi-tenant, ALWAYS filter by the tenant identifier.
- Distinctive: line 401
Use one envelope for every response so clients can parse success and failure uniformly.
- Very specific: line 474
When a write triggers an asynchronous downstream effect, respond 202 Accepted and queue an outbox command in the same transaction.
- Distinctive: line 572
Before completing ANY backend task:
- Distinctive: line 606
Missing tenantId: always filter by tenant in a multi-tenant system.
- Distinctive: line 608
Validation in controllers: use schema middleware.
- Distinctive: line 609
Duplicated auth middleware: import from the shared HTTP package.
- Distinctive: line 610
200 for async operations: use 202 Accepted.
- Distinctive: line 611
Logging secrets: never log passwords, tokens, or PII.
- Distinctive: line 612
Mocking databases: use a disposable real database (Testcontainers) instead.
- Very specific: line 666
Use a money value object backed by scaled BigInt (no floating-point on the hot path).
- Distinctive: line 683
Phantom DTO fields are forbidden: Every field in a DTO must map to a column on the model the use case writes to.
- Distinctive: line 684
Required-in-DTO implies required-in-model: If the DTO marks a field non-optional, the persistence model must also be non-optional (or a …
- Distinctive: line 687
Enums stay in lockstep: Import the persistence enum directly into the schema (for example via a native-enum validator) to eliminate manual …
- Very specific: line 726
Every outbox create(...) call must be inside either:
- Distinctive: line 731
If you have a custom lint rule, enforce this mechanically: an outbox write outside a transaction is a latent data-consistency bug that a …
- Distinctive: line 771
Follow your team's policy on AI attribution in commit messages.
- Distinctive: line 772
Never use emojis in commit messages.
“Common” is measured: kept by at least 6 in 10 of the 17 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Backend Development Skill
You are an expert backend developer. This skill provides comprehensive patterns for building enterprise-grade microservices following Clean Architecture principles.
The concrete examples below assume a TypeScript / Node.js / Express stack with Zod for validation and an ORM for persistence, because concrete code is easier to learn from than abstract description. The discipline itself is stack-agnostic: the layering, the dependency direction, the outbox pattern, the validation contract, and the testing strategy translate directly to any language and framework. Where you see a TypeScript idiom, read it as the general principle expressed in one concrete dialect.
Architecture Overview
A typical monorepo layout for this style of system:
backend/ # Monorepo (e.g. Turborepo, Nx, pnpm workspaces)
├── apps/ # Microservices
│ ├── svc-admin/ # Admin / back-office operations
│ ├── svc-auth/ # Authentication
│ ├── svc-account/ # Account management
│ ├── svc-billing/ # Billing, balances, transfers
│ ├── svc-catalog/ # Domain entity catalog
│ ├── svc-notification/ # Notifications, messaging
│ └── svc-<name>/ # Additional domain services
├── workers/ # Background workers
│ ├── projector/ # Event projection into read models
│ └── outbox-submitter/ # CQRS command submission
├── packages/ # Shared libraries
│ ├── core-http/ # HTTP middleware, validation helpers
│ ├── core-db/ # ORM client
│ ├── core-config/ # Env-var schema validation
│ ├── core-logger/ # Structured logging
│ ├── core-errors/ # Standardized error classes
│ ├── core-events/ # Event schema registry
│ ├── core-storage/ # Document storage, file handling
│ ├── core-openapi/ # OpenAPI validation
│ └── test-utils/ # Test containers, data factories
└── db/ # The schema and migrationsReplace the service names with your own domain services. The point is the separation: thin services in apps/, asynchronous work in workers/, and shared concerns extracted into versioned packages/ so no cross-cutting logic is copy-pasted between services.
When a service grows too broad, decompose it along a clear seam rather than letting one service own unrelated concerns. A single service that handles both authentication and identity verification, for example, is usually better split into
svc-authandsvc-kyc. When you split a service, deprecate the old one explicitly so consumers know where the responsibility moved.
Local Development Setup
See references/local-development-setup.md for how to run a service locally, port-forward from the cluster, and the port assignment table.
Internal Service Structure (Clean Architecture)
Every service should follow this structure. The dependency rule is the whole point: inner layers know nothing about outer layers. domain/ depends on nothing. application/ depends only on domain/. infrastructure/ and interface/ depend inward. Frameworks, databases, and HTTP live at the edges and are swappable.
apps/svc-{name}/src/
├── domain/ # Core business logic (NO external dependencies)
│ ├── entities/ # Domain entities with behavior
│ ├── value-objects/ # Immutable domain concepts
│ ├── services/ # Domain services (pure logic)
│ ├── events/ # Domain events
│ └── errors/ # Domain-specific errors
│
├── application/ # Application layer (use cases)
│ ├── use-cases/ # Business use cases (feature-grouped)
│ │ ├── auth/ # e.g. login, register, refresh
│ │ └── user/ # e.g. get-profile, update-profile
│ ├── ports/ # Interfaces (contracts)
│ │ ├── repositories/ # Repository interfaces
│ │ └── services/ # External service interfaces
│ ├── dto/ # DTOs with schema validation
│ │ ├── request/ # Request DTOs
│ │ └── response/ # Response DTOs
│ └── mappers/ # Entity <-> DTO mappers
│
├── infrastructure/ # External adapters (implementations)
│ ├── repositories/ # ORM repository implementations
│ └── services/ # External service implementations
│
├── interface/ # HTTP layer
│ ├── controllers/ # THIN controllers
│ ├── routes/ # HTTP routes
│ ├── middlewares/ # HTTP middlewares
│ └── validators/ # Request schemas
│
├── shared/ # Cross-cutting
│ └── di/ # Dependency injection
│
├── app.ts # App factory
└── index.ts # Entry pointCore Patterns
1. CQRS with Transactional Outbox
When a write must produce a side effect in another system (publishing an event, calling an external service, submitting to a slow downstream), do not call that system inside the request. Instead, write the local state change and an outbox record in the same database transaction, then let a background worker drain the outbox. This guarantees the side effect happens exactly when the state change commits, and survives crashes.
WRITE PATH:
API -> Use Case -> Repository -> db.$transaction([data, outboxCommand]) -> 202 Accepted
Background: outbox-submitter -> external system / event bus
READ PATH:
Events -> projector -> read models (e.g. PostgreSQL) -> API queries2. Multi-Tenancy
If the system is multi-tenant, ALWAYS filter by the tenant identifier. A single missing filter leaks one tenant's data to another.
await db.user.findMany({
where: { tenantId: req.user!.tenantId, status: 'ACTIVE' },
});3. Repository Pattern
The use case depends on an interface (a port). The implementation (an adapter) lives in infrastructure/. This keeps the ORM out of the business logic and makes the use case testable without a database.
// Port (interface) -- application/ports/repositories
export interface IUserRepository {
findById(id: string): Promise<User | null>;
create(user: User): Promise<User>;
}
// Adapter (implementation) -- infrastructure/repositories
export class OrmUserRepository implements IUserRepository {
async findById(id: string): Promise<User | null> {
const record = await db.user.findUnique({ where: { id } });
return record ? UserMapper.toDomain(record) : null;
}
}4. Use Case Pattern
A use case orchestrates one piece of business intent. It validates business rules, builds domain entities, persists through a port, and returns a DTO. It contains no HTTP and no ORM.
export class RegisterUseCase {
constructor(
private userRepo: IUserRepository,
private hasher: IPasswordHasher,
) {}
async execute(dto: RegisterRequestDTO): Promise<AuthResponseDTO> {
// 1. Validate business rules
const existing = await this.userRepo.findByEmail(dto.email);
if (existing) throw new UserAlreadyExistsError();
// 2. Create domain entity
const user = User.create({ ...dto, passwordHash: await this.hasher.hash(dto.password) });
// 3. Persist
const saved = await this.userRepo.create(user);
// 4. Return DTO
return UserMapper.toResponseDTO(saved);
}
}5. DTO Validation with a Schema
Validate and coerce input at the boundary with a schema library (Zod shown here; the principle holds for any validator). The inferred type becomes the DTO, so the validation and the type never drift.
// application/dto/request/register.dto.ts
export const registerSchema = z.object({
email: z.string().email().transform(v => v.toLowerCase()),
password: z.string().min(8).regex(/[A-Z]/).regex(/[a-z]/).regex(/[0-9]/),
firstName: z.string().min(1).max(100),
lastName: z.string().min(1).max(100),
});
export type RegisterRequestDTO = z.infer<typeof registerSchema>;6. Thin Controllers
Controllers handle only HTTP concerns: read the request, call a use case, shape the response, forward errors. No business logic.
export class AuthController {
constructor(private registerUseCase: RegisterUseCase) {}
register = async (req: Request, res: Response, next: NextFunction) => {
try {
// Validation done by middleware, logic in use case
const result = await this.registerUseCase.execute(req.body);
res.status(201).json({ success: true, data: result });
} catch (error) {
next(error);
}
};
}7. Validation Middleware
Validation runs in middleware, before the controller. The controller can assume req.body is already valid.
// interface/middlewares/validation.middleware.ts
import { validateBody, validateQuery, validateParams } from '@org/core-http';
// In routes
router.post('/register', validateBody(registerSchema), controller.register);
router.get('/users', validateQuery(paginationSchema), controller.listUsers);
router.get('/users/:id', validateParams(idSchema), controller.getUser);8. Entity Mapper
Mappers translate between the three representations of an entity: the persistence record, the domain entity, and the response DTO. Each boundary gets an explicit mapping so a schema change cannot silently reshape the API.
export class UserMapper {
// Persistence record -> Domain
static toDomain(record: UserRecord): User {
return User.reconstitute({ id: record.id, email: Email.create(record.email), /* ... */ });
}
// Domain -> Persistence record
static toPersistence(entity: User): UserRecord {
return { id: entity.id, email: entity.email.value, /* ... */ };
}
// Domain -> Response DTO
static toDTO(entity: User): UserProfileDTO {
return { id: entity.id, email: entity.email.value, /* ... */ };
}
}Creating a New Feature (Step by Step)
This walks one feature from the inside out: domain first, infrastructure last. Each step lives in its proper layer.
Step 1: Define the Domain Entity (if new)
// domain/entities/feature.entity.ts
export class Feature {
private constructor(
public readonly id: string,
public readonly name: string,
public readonly tenantId: string,
public readonly createdAt: Date,
) {}
static create(props: { name: string; tenantId: string }): Feature {
return new Feature(generateId(), props.name, props.tenantId, new Date());
}
static reconstitute(props: FeatureProps): Feature {
return new Feature(props.id, props.name, props.tenantId, props.createdAt);
}
}Step 2: Define the Repository Port
// application/ports/repositories/feature.repository.port.ts
export interface IFeatureRepository {
findById(id: string, tenantId: string): Promise<Feature | null>;
findAll(tenantId: string, options: PaginationOptions): Promise<Feature[]>;
create(feature: Feature): Promise<Feature>;
}
export const FEATURE_REPOSITORY = Symbol('FEATURE_REPOSITORY');Step 3: Define DTOs with a Schema
// application/dto/request/create-feature.dto.ts
export const createFeatureSchema = z.object({
name: z.string().min(2).max(100),
description: z.string().max(500).optional(),
});
export type CreateFeatureDTO = z.infer<typeof createFeatureSchema>;
// application/dto/response/feature.dto.ts
export interface FeatureResponseDTO {
id: string;
name: string;
createdAt: string;
}Step 4: Create the Use Case
// application/use-cases/feature/create-feature.use-case.ts
@injectable()
export class CreateFeatureUseCase {
constructor(@inject(FEATURE_REPOSITORY) private featureRepo: IFeatureRepository) {}
async execute(dto: CreateFeatureDTO, tenantId: string): Promise<FeatureResponseDTO> {
const feature = Feature.create({ name: dto.name, tenantId });
const saved = await this.featureRepo.create(feature);
return FeatureMapper.toDTO(saved);
}
}Step 5: Implement the Repository
// infrastructure/repositories/orm-feature.repository.ts
@injectable()
export class OrmFeatureRepository implements IFeatureRepository {
async create(feature: Feature): Promise<Feature> {
const record = await db.feature.create({
data: FeatureMapper.toPersistence(feature),
});
return FeatureMapper.toDomain(record);
}
}Step 6: Create the Controller (THIN)
// interface/controllers/feature.controller.ts
@injectable()
export class FeatureController {
constructor(@inject(CreateFeatureUseCase) private createUseCase: CreateFeatureUseCase) {}
create = async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
try {
const result = await this.createUseCase.execute(req.body, req.user!.tenantId);
res.status(201).json({ success: true, data: result });
} catch (error) {
next(error);
}
};
}Step 7: Create the Routes
// interface/routes/feature.routes.ts
import { validateBody } from '@org/core-http';
const router = Router();
const controller = container.get(FeatureController);
router.post('/',
createAuthMiddleware({ jwtSecret: config.jwtSecret }),
validateBody(createFeatureSchema),
controller.create
);
export default router;Authentication & Authorization
Centralize auth middleware in a shared package so every service enforces it the same way. Read identity from the verified token, never from the request body.
import { createAuthMiddleware, requireRoles, AuthenticatedRequest } from '@org/core-http';
const auth = createAuthMiddleware({ jwtSecret: config.jwtSecret });
// In routes
router.get('/protected', auth, controller.method);
router.post('/admin-only', auth, requireRoles(['ADMIN']), controller.adminMethod);
// In controller
async handler(req: AuthenticatedRequest, res: Response) {
const userId = req.user!.sub;
const tenantId = req.user!.tenantId;
const roles = req.user!.roles;
}Error Handling
Standard Response Format
Use one envelope for every response so clients can parse success and failure uniformly.
// Success
{ success: true, data: T, meta?: { page, limit, total } }
// Error
{ success: false, error: { code: string, message: string, timestamp: string, details?: [] } }Error Classes (from a shared errors package)
import {
BadRequestError,
ValidationError,
UnauthorizedError,
ForbiddenError,
NotFoundError,
ConflictError,
BusinessRuleError,
InsufficientBalanceError,
RateLimitError,
ServiceUnavailableError,
InternalError,
} from '@org/core-errors';
// Usage in use cases
if (!user) throw new NotFoundError('User', userId);
if (balance < amount) throw new InsufficientBalanceError(balance, amount);
if (existing) throw new ConflictError('User', 'email', email);A single error-handling middleware maps these classes to status codes, so use cases throw typed errors and never touch HTTP.
Error Codes
| Code | Status | Usage |
| VALIDATION_ERROR | 400 | Invalid input |
| UNAUTHORIZED | 401 | Missing/invalid token |
| FORBIDDEN | 403 | Insufficient permissions |
| NOT_FOUND | 404 | Resource not found |
| CONFLICT | 409 | Duplicate resource |
| INSUFFICIENT_BALANCE | 400 | Not enough funds |
Database Operations
import { db } from '@org/core-db';
// ALWAYS filter by tenantId in a multi-tenant system
const users = await db.user.findMany({
where: { tenantId, status: 'ACTIVE' },
skip: (page - 1) * limit,
take: limit,
});
// ALWAYS use transactions for multi-table operations
await db.$transaction(async (tx) => {
const user = await tx.user.update({ /* ... */ });
const account = await tx.account.create({ /* ... */ });
await tx.outboxCommand.create({ type: 'CREATE_ACCOUNT', /* ... */ });
return { user, account };
});CQRS Outbox Pattern
When a write triggers an asynchronous downstream effect, respond 202 Accepted and queue an outbox command in the same transaction. The caller polls or subscribes for the result.
const result = await db.$transaction(async (tx) => {
// Update local state
const account = await tx.account.update({ /* ... */ });
// Queue downstream command
const command = await tx.outboxCommand.create({
data: {
type: CommandType.TRANSFER_FUNDS,
payload: { fromAccountId, toAccountId, amount: amount.toString() },
status: OutboxStatus.PENDING,
tenantId,
createdBy: userId,
},
});
return { commandId: command.id };
});
return res.status(202).json({
success: true,
data: { commandId: result.commandId, status: 'PENDING' },
});Configuration
Validate environment variables at startup with a schema. A misconfigured service should fail loudly on boot, not silently at request time.
import { baseServiceSchema, createServiceConfig, z } from '@org/core-config';
// Extend the base schema for service-specific config
const authConfigSchema = baseServiceSchema.extend({
EMAIL_API_KEY: z.string().min(1),
OTP_EXPIRY_MINUTES: z.coerce.number().int().positive().default(10),
});
export const config = createServiceConfig(authConfigSchema);
export type AuthConfig = typeof config;Logging
import { logger } from '@org/core-logger';
// Structured logging with context
logger.info({ userId, tenantId, action: 'login' }, 'User logged in');
logger.error({ error, userId }, 'Transfer failed');
// NEVER log sensitive data (passwords, tokens, PII)Structured logs are queryable; string logs are not. Always attach the identifiers you would want to filter by later.
Testing Patterns (Testing Trophy)
The Testing Trophy weights integration tests heaviest because they catch the bugs that actually ship: wiring between layers, real database behavior, real serialization. Unit tests cover pure logic; end-to-end tests cover only critical user journeys.
Test Distribution
| Layer | % | Tool (example) | Tests |
| Unit | 10-15% | Vitest / Jest | Pure functions only |
| Integration | 65-75% | Vitest + Testcontainers | Real DB |
| Contract | 10-15% | Pact | API compatibility |
| E2E | 5-10% | Playwright | Critical user journeys only |
See references/testing-trophy-examples.md for worked Unit, Integration, and Contract test code examples.
Test Naming Convention
*.unit.spec.ts # Unit tests
*.integration.spec.ts # Integration tests
*.contract.spec.ts # Contract tests
*.pact.spec.ts # Pact contract testsWhat NOT to Test with Unit Tests
- Controllers (they just call use cases)
- Repositories (they just call the ORM)
- Anything that requires mocking the database (write an integration test instead)
Validation Checklist
Before completing ANY backend task:
Architecture:
- Domain logic in
domain/layer (no I/O) - Use cases in
application/layer - Repositories implement interfaces from
ports/ - Controllers are THIN (delegate to use cases)
Code Quality:
- DTOs validated with a schema
- Entity mappers for persistence <-> domain <-> DTO
- Structured logging at key points
- No sensitive data in logs
Security:
- Auth middleware from the shared HTTP package
- tenantId filtering on ALL queries (multi-tenant systems)
- Input sanitization
Data Integrity:
- Transactions for multi-table operations
- Outbox pattern for asynchronous downstream effects
- Proper status codes (201 create, 202 async)
Testing:
- Unit tests for pure business logic
- Integration tests with a real database (Testcontainers)
- Contract tests if consuming another service's API
Common Mistakes to Avoid
- Fat controllers: move logic to use cases.
- Missing tenantId: always filter by tenant in a multi-tenant system.
- Direct ORM calls in controllers: go through repositories.
- Validation in controllers: use schema middleware.
- Duplicated auth middleware: import from the shared HTTP package.
- 200 for async operations: use 202 Accepted.
- Logging secrets: never log passwords, tokens, or PII.
- Mocking databases: use a disposable real database (Testcontainers) instead.
Quick Reference
// Imports (replace @org/* with your workspace package scope)
import { db } from '@org/core-db';
import { logger } from '@org/core-logger';
import { createAuthMiddleware, requireRoles, AuthenticatedRequest, validateBody } from '@org/core-http';
import { NotFoundError, ConflictError, InsufficientBalanceError } from '@org/core-errors';
import { baseServiceSchema, createServiceConfig, z } from '@org/core-config';
import { setupTestDatabase, UserFactory, AccountFactory } from '@org/test-utils';
import { CommandType, OutboxStatus } from '<your-orm-client>';
// Common models (replace with your domain)
db.user, db.account, db.transaction, db.outboxCommandProduction-Grade Best Practices
These conventions are non-negotiable for new code. They emerge from a recurring pattern: choices that look harmless at small scale (a number field, a bare timestamp, a service-layer-only tenant filter) become silent data-corruption or data-leak bugs at production scale. Each rule below trades a little upfront discipline for a class of bug you will never have to debug.
Capture the rationale for major decisions in docs/adrs/ (architecture decision records) so the team has a durable record of why, not just what.
Money and Decimal Amounts
Never use a floating-point number for monetary fields. IEEE 754 doubles have 53 bits of integer precision; any amount above 2^53 minor units (~9 × 10^15) silently loses precision when crossing the JSON-parse boundary. This is the single most common money bug in JavaScript backends.
The required pattern mirrors the minor-unit conventions used by Stripe, Adyen, and major ledger systems: represent money as an integer count of the smallest unit, validate it as a string, and never let a float touch it.
// DTO: regex-string validation (no float ever enters the system)
const transferSchema = z.object({
amount: z.string().regex(
/^\d+(\.\d{1,6})?$/,
'Amount must be a positive decimal with up to 6 fractional digits',
),
// ...
});
// Use case (application layer): parse at the boundary into a precise type
async execute(dto: TransferDTO): Promise<Result> {
const amount = Money.from(dto.amount);
if (!amount.isPositive()) {
throw new InvalidAmountError(dto.amount, 'must be greater than zero');
}
// arithmetic only on the precise Money / BigInt type from here onward
}Use a money value object backed by scaled BigInt (no floating-point on the hot path). Typical operations: from, toString, toBigInt, isZero, isPositive, isGreaterThan, isLessThanOrEqual, add, subtract. Outbox payloads and wire format serialize via amount.toString(): strings are the canonical wire format for money.
Pick the precision your domain requires (for example, currencies with 2 decimal places, or higher-precision domains needing 6 or more) and make it a single documented constant. The persistence column should match that precision exactly, for example a fixed-point Decimal(36, 6) for a 6-decimal domain. Never store money as Float (IEEE 754 lossy) and never as a plain integer if the domain has fractional units it cannot represent. The value object may use a higher internal scale (for example 18 decimals) to avoid rounding during multi-step calculations, while all persisted and wire-format values use the canonical domain precision.
Banker's rounding (HALF_EVEN) is the financial-systems consensus. Declare it once per service at startup:
import Decimal from 'decimal.js';
Decimal.set({ rounding: Decimal.ROUND_HALF_EVEN });DTO <-> Schema Alignment
The validation contract (the request schema) and the persistence contract (the database schema) must stay in lockstep. Drift between them is silent: tests using DTO-shaped fixtures never surface a persistence-layer mismatch, so the bug only appears in production.
Rules for new code:
- Phantom DTO fields are forbidden. Every field in a DTO must map to a column on the model the use case writes to. If you collect data the model cannot store, either add the column (with a migration) or drop the field from the DTO.
- Required-in-DTO implies required-in-model. If the DTO marks a field non-optional, the persistence model must also be non-optional (or a CHECK constraint must enforce conditional non-null when the entity reaches the relevant state).
- Length constraints align. A
max(N)string in the schema should match the column'sVarChar(N). Prefer widening the model in a migration over tightening the DTO. - Field names align. No
deviceOsin the DTO mapped toosVersionin the model. Use identical names. Renames are breaking changes that must be coordinated with API consumers. - Enums stay in lockstep. Import the persistence enum directly into the schema (for example via a native-enum validator) to eliminate manual transcription drift.
Identifiers
- UUID v4 is acceptable for existing tables. Do not migrate just to migrate.
- UUID v7 (RFC 9562, May 2024) is the new-table default. It is time-ordered, which preserves index locality on high-write tables. Generate it at the database or application layer depending on your ORM's support.
- Prefixed IDs in the style of
cus_xxxorord_xxxare encouraged for human-debuggability when an ID will appear in logs and support tickets. The convention is<short-type-code>_<base32-payload>.
Time and Timestamps
PostgreSQL guidance has been consistent for over a decade: always use TIMESTAMPTZ, never bare TIMESTAMP. Bare TIMESTAMP stores no timezone, which leaves distributed-system reconciliation ambiguous.
createdAt TIMESTAMPTZ default now()
updatedAt TIMESTAMPTZ on update now()Store UTC at the boundary; render in the user's timezone in the UI. Never store local time anywhere.
Tenant Isolation
Service-layer tenantId filtering (the pattern shown above) is industry-standard but is one forgotten WHERE tenant_id = ? away from a cross-tenant data leak. The defense-in-depth layer is Postgres Row-Level Security (RLS), which makes accidental cross-tenant reads structurally impossible:
ALTER TABLE "Account" ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON "Account"
USING (tenant_id::text = current_setting('app.current_tenant_id', true));Set the session variable in middleware before each request handler runs.
Sensitive Data
- PII fields (email, phone, date of birth, national identifiers, biometric hashes, full names): protect with column-level encryption (for example
pgcrypto) or application-layer envelope encryption backed by a KMS. Never store PII plaintext at rest. Treat every new table as a chance to encrypt by default. - Secrets (API keys, passwords, OAuth secrets): hash with argon2id (OWASP 2024 recommendation). Bcrypt is acceptable for legacy compatibility but not for new code. The field name should reflect that it stores a hash:
passwordHash, notpassword. - GDPR Article 17 erasure: soft delete (set
deletedAt) plus scheduled anonymization (zero out PII, retain row shape for referential integrity, hard-delete after the retention window). Pure soft-delete leaves PII queryable and is non-compliant.
CQRS Outbox Discipline
Every outbox create(...) call must be inside either:
- A
db.$transaction(...)callback, or - An atomic-transaction port callback (the port pattern that wraps the transaction internally).
If you have a custom lint rule, enforce this mechanically: an outbox write outside a transaction is a latent data-consistency bug that a lint rule catches at authoring time.
The outbox row should always include tenantId, service (the producing service name, for example 'svc-billing'), requestId (deterministic, typically ${entityId}-${commandType} so crash-retries are idempotent), commandType, and payload. A missing tenantId, service, or requestId will fail at runtime when the projector dispatches.
Pre-commit and Pre-push Discipline
A three-tier verification ladder keeps the feedback loop fast while still catching everything before CI:
| Tier | Latency target | Scope |
| Pre-commit | under 5s | lint-staged runs eslint --fix + prettier --write on changed files only |
| Pre-push | under 60s | npm run verify runs lint, type-check, and test workspace-wide |
| CI | under 10min | Full repo lint + type-check + test + build + security-scan + dependency audit |
Configure via your git-hooks tooling (for example Husky pre-commit and pre-push). --no-verify is reserved for genuine emergencies: fix the underlying error rather than bypass the gate.
Empty-test packages must pass with no tests (for example --passWithNoTests). Manual scripts that are not real tests must not match the test glob; rename them (for example *.manual-script.ts) or move them out of the test directory.
Test-Runner Alignment
When a codebase migrates between test runners, mixing one runner with another's test syntax causes the transform to choke on ESM imports. Any package whose *.spec.ts files import from a given runner must declare that runner in its package.json test script (for example "test": "vitest run --passWithNoTests"). Keep the runner and the test syntax consistent per package.
Local-CI Parity
The CI gate (lint, type-check, test, build, security-scan) and the local npm run verify script must match one-for-one. If a check fires in CI but not in verify, that gap costs the team a CI round-trip on every pull request. Keep the two in sync deliberately.
Documentation Standards
- Capture new work as a narrative in a dated work record, for example
docs/workrecords/work-record-YYYY-MM-DD.md. Append-only. - Architectural decisions go into
docs/adrs/as decision records or design studies. - Durable industry research and reference material go into a dedicated docs folder (for example
docs/references/). - Each new module or service specification follows a shared spec template kept under
.claude/templates/.
Commit Discipline
- File-by-file commits. Each commit is one logical change.
- Conventional Commits format:
type(scope): subject, withtypein {feat, fix, refactor, chore, docs, test, perf, security, ci}. - Imperative mood (
add, notadded). - Subject line at most 72 characters; the body explains why, not what.
- Never commit secrets.
- Follow your team's policy on AI attribution in commit messages.
- Never use emojis in commit messages.
Reference Files
This skill's on-demand reference material, kept out of the core workflow so it is not injected on every invocation:
references/local-development-setup.md-- how to run a service locally, port-forward from the cluster, and the port assignment table. Read when setting up or troubleshooting the local dev environment.references/testing-trophy-examples.md-- worked Unit, Integration, and Contract test code examples. Read when writing the actual test files for a feature.
Apply to: $ARGUMENTS
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

