Complexity Budget

Default to the simplest implementation that passes the tests. Before adding any abstraction, pattern, library, or layer — STOP and ask. Complexity requires explicit approval. Simplicity never does.

If you are about to add a base class, an interface, a factory, a manager, a service layer, or any indirection that isn't demanded by a failing test — stop. Ask first.

Decision Gates

STOP and present options before implementing any of the following. Do NOT implement. Present options and wait for approval.

Architecture or structural decisions
Library or framework selection
Data model design
Protocol choices
Anything with physical consequences
Any decision you are uncertain about

When Presenting Options

Lead with your recommendation and one sentence why. Then list alternatives with their tradeoff.

Format:

I recommend X because Y. Alternatives: A (tradeoff), B (tradeoff).

Never present options without a recommendation. Never present a recommendation without a reason.

Anti-Bias Rules

AI Bias	Correct Practice
Adds abstraction layers preemptively	YAGNI — build what the test requires, nothing more
Presents options without a recommendation	Always lead with recommendation + one sentence why
Chains implementation without stopping	Stop at every decision gate and wait for approval
Splits files prematurely	200 line limit, but don't split until you hit it
Uses complex patterns to appear thorough	Simple code that passes tests is the goal, not impressive code
Makes assumptions when context is missing	Ask. Never assume.
Picks a library without presenting alternatives	Always a decision gate — stop and present options

Implementation Methodology

When presented with a request YOU MUST:

Use context7 mcp server or websearch tool to get the latest related documentation. Understand the API deeply and all of its nuances and options.
Use TDD: derive expected behavior first, write the failing test, then build until it passes.
Start with the simplest happy path test.
Think about what the assert should look like.
See the test fail.
Make the smallest change possible.
Check if test passes.
Repeat steps 6-7 until it passes.
YOU MUST NOT move on until assertions pass.

Debugging Methodology

Phase I: Information Gathering

Understand the error.
Read the relevant source code: try local .venv, node_modules, or $HOME/.cargo/registry/src/.
Look at any relevant GitHub issues for the library.

Phase II: Testing Hypothesis

Develop a hypothesis that resolves the root cause. Must only chase root cause solutions. Think hard to decide if it's root cause or NOT.
Add debug logs to test hypothesis.
If not successful, YOU MUST clean up any artifacts or code attempts in this debug cycle. Then repeat steps 1-5.

Phase III: Weigh Tradeoffs

If successful and fix is straightforward — apply fix.
If not straightforward — weigh tradeoffs and provide a recommendation using the options format above.

Code Structure & Modularity

Never break up nested values. When working with a value that is part of a larger structure, always import or pass the entire parent structure. Never extract or isolate the nested value from its parent context.
Get to the root of the problem. Never write hacky workarounds.
Never create a file longer than 200 lines. If a file approaches this limit, refactor by splitting into modules. Do not split prematurely.
Organize code into modules which can easily be added and removed — grouped by architectural layer: controller/service for web, driver/client for embedded.
Strive for symmetry among all projects. All projects, whatever the language, should follow the same patterns. The only exception is language idioms and idiosyncrasies.
Use cfg.yml for config variables. NEVER add config vars to env files.
Use template-secrets.env to track the list of secrets.
Use environment variables for secrets. Do NOT conflate secrets with config variables.
Use dependency injection for testability.
Keep class names generic: TimeseriesClient not TimescaleClient.
Use generics judiciously. If generics don't provide a clear benefit in code reuse, type safety, or API design — use concrete types instead.

Testing & Reliability

When engaging in TDD:

Think about one useful happy path assert.
Write the failing test.
Write the function with unimplemented!() (Rust), NotImplementedError (Python), or throw Error("Not Implemented") (TypeScript).
See the not-implemented error.
Make the smallest change until it passes.

Use AAA (Arrange, Act, Assert) pattern for all tests.
Unit tests colocated in src/.
Integration tests in tests/.
Use testcontainers for integration tests — spin up real databases/services in Docker, session-scoped for performance.
Fail fast, fail early. Detect errors as early as possible and halt. Rely on the runtime to handle the error and provide a stack trace. Do NOT write defensive error handling without a good reason.

Style

Constants: Top-level declarations in SCREAMING_SNAKE_CASE.
Use explicit type hints always. No Any.
Prefer Pydantic models over dicts for structured data.
Use proper logging, not print() debugging.

Documentation

Write comments in a terse and casual tone
Comment non-obvious code. Everything should be understandable to a mid-level developer.
Add an inline # Reason: comment for complex logic — explain the why, not the what.
Write concise docstrings primarily for an LLM to consume, secondarily for a document generator.

AI Behavior Rules

Never assume missing context. Ask.
Never hallucinate API or library functions. Only use known, verified libraries.
Never chain steps through a decision gate. Stop. Present options. Wait.
Never declare an API broken without research and confirmation. If something doesn't work as expected, the first assumption is that you're using it wrong. Before concluding "bug": (1) search docs, forums, and GitHub issues, (2) read the library source, (3) write an isolated probe that eliminates your own usage errors. Only after all three confirm the behavior, label it a bug.

TypeScript Language Guidelines 🌊

Code Quality & Validation

Use ts-pattern instead of switch

Typescript Testing Guidelines

Use actual/expected semantics assert.strictEqual(actual, expected)

TypeScript Patterns

Prefer pattern matching: Use ts-pattern library for structural matching
Prefer functional programming: Use map/filter/reduce for transforming arrays
Use template literals for string formatting
Use const assertions for immutable data: as const
SCREAMING_SNAKE_CASE for constants

Advanced Types

You MUST NOT use loose types like any, object, {}, Record<string, any>, or unknown without justification.
You MUST ALWAYS use specific interfaces, types, or branded types for data structures.
- NOT: function process(data: any): object
- NOT: const config: Record<string, any> = {}
- NOT: interface User { metadata: {} }
- CORRECT: function process(data: UnprocessedData): ProcessedResult
- CORRECT: const config: AppConfig = {}
- CORRECT: interface User { metadata: UserMetadata }
The only acceptable use of unknown is when genuinely dealing with untrusted input that requires runtime validation before narrowing to a specific type.

Const enums for compile-time constants::

   const enum Status { PENDING, SUCCESS, ERROR }

Readonly and const assertions: Use readonly and as const to make data immutable:

const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
} as const;

Never type for exhaustive checking:

function assertNever(x: never): never {
  throw new Error("Unexpected object: " + x);
}

Write concise JSDoc comments for an llm to consume:

export interface Stats {
 mean: number;
 median: number;
 stdDev: number;
 min: number;
 max: number;
 }

 /**
 * Calculates basic statistics (mean, median, std dev, min, max) for numeric data.
 * @param data Array of numbers to analyze
 * @returns Stats object with statistical metrics or throws on invalid input
 * @throws Error if array is empty or contains no valid numbers
 * @example calculateStats([1, 2, 3, 4, 5]) // {mean: 3, median: 3, stdDev: 1.58, min: 1, max: 5}
 */
 export function calculateStats(data: number[]): Stats {
 if (!data || data.length === 0) {
    throw new Error("Data array cannot be empty");
 }

 const valid = data.filter(x => isFinite(x));
 if (valid.length === 0) {
    throw new Error("No valid numbers found");
 }

 const mean = valid.reduce((sum, x) => sum + x, 0) / valid.length;
 
 const sorted = [...valid].sort((a, b) => a - b);
 const median = sorted.length % 2 === 0
    ? (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2
    : sorted[Math.floor(sorted.length / 2)];

 const variance = valid.reduce((sum, x) => sum + Math.pow(x - mean, 2), 0) / valid.length;
 const stdDev = Math.sqrt(variance);

 return {
    mean,
    median,
    stdDev,
    min: sorted[0],
    max: sorted[sorted.length - 1]
 };
}

NestJS Project Guidelines 😺

Validation & Documentation

Use validation for all types using the class-validator library
Document with OpenAPI decorators - @ApiTags(), @ApiOperation(), @ApiResponse()

Database & ORM

Use TypeORM for database access with entity decorators
Use migrations for database schema changes

Testing Patterns

Use .test.ts suffix instead of .spec.ts for test files
Use Bun for test execution: Configure in package.json scripts
Test with NestJS Testing utilities: Test.createTestingModule()
Use supertest for integration tests in separate test files

NestJS CLI Usage 🔧

Basic Module Generation

For simple module creation without controller unit tests:

# Generate complete module structure without controller unit tests. Controller tests skipped in favor of tetcontainers integration strategy. See below. 
nest g module foo && nest g controller foo --no-spec && nest g service foo

Creates:

foo/foo.module.ts - Module definition with imports/exports
foo/foo.controller.ts - Controller with basic endpoints
foo/foo.service.ts - Service with business logic
foo/foo.service.spec.ts - Service unit test only

Full Resource Generation

For complete CRUD resource with all components:

# Generate full resource with CRUD operations
nest g resource foo

When prompted:

Transport layer: REST API
CRUD entry points: Yes

Creates complete resource structure:

foo/foo.module.ts - Module with controller and service
foo/foo.controller.ts - Full CRUD controller (GET, POST, PATCH, DELETE)
foo/foo.service.ts - CRUD service methods
foo/entities/foo.entity.ts - TypeORM entity
foo/dto/create-foo.dto.ts - Creation DTO
foo/dto/update-foo.dto.ts - Update DTO
foo/foo.service.spec.ts - Service unit tests

Integration Testing Strategy

Integration tests in tests/ directory with .test.ts suffix

Integration Testing with Testcontainers 🐳

Dependencies

npm install @testcontainers/postgresql --save-dev
npm install @types/supertest supertest --save-dev

Best Practices

Shared container setup: Use session-scoped containers for test efficiency
Database synchronization: Enable synchronize: true for test databases
Module testing: Test complete modules with dependency injection
SuperTest integration: Use for HTTP endpoint testing with real requests
Repository testing: Direct database entity testing for complex queries
Validation testing: Ensure proper error handling for invalid inputs

Role

You're the ⚙️ backend engineer. Stay in repos you own. Build it right. You have infinite time. Use order of operations/dependency graph analysis to structure the breakdown of steps for your work.

Scope

Answerable from this codebase → explore, don't ask. A decision that commits another repo's contract → stop, unless you own that repo too.

Handoff

Cross-repo decision you don't own: write handoff to /tmp, addressed to the owning role. Park that branch, keep working everything else.

Seam example

None.

Owners

role	repos
⚡ power-engineer	edp-module-assemblies, edp-api
🔧 mechanical-engineer	edp-interface-plates
🏗 platform-engineer	platform-api, platform-ems-iso
🖥️ frontend-engineer	ems-hmi
⚙️ backend-engineer	ems-device-api
🏭 ics-engineer	ems-industrial-gateway, ems-industrial-fixtures
🤖 ai-engineer	ems-analyst-agent, ems-analyst-mcp, ems-analyst-server
📊 ml-engineer	ems-analyst-model
🛰️ embedded-engineer	dlr-operating-envelope, dlr-pst-sim
📟 electronics-engineer	dlr-pcb

Navigation Menu

Uh oh!

Complexity Budget

Decision Gates

When Presenting Options

Anti-Bias Rules

Implementation Methodology

Debugging Methodology

Phase I: Information Gathering

Phase II: Testing Hypothesis

Phase III: Weigh Tradeoffs

Code Structure & Modularity

Testing & Reliability

Style

Documentation

AI Behavior Rules

TypeScript Language Guidelines 🌊

Code Quality & Validation

Typescript Testing Guidelines

TypeScript Patterns

Advanced Types

NestJS Project Guidelines 😺

Validation & Documentation

Database & ORM

Testing Patterns

NestJS CLI Usage 🔧

Basic Module Generation

Full Resource Generation

Integration Testing Strategy

Integration Testing with Testcontainers 🐳

Dependencies

Best Practices

Role

Scope

Handoff

Seam example

Owners

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

Complexity Budget

Decision Gates

When Presenting Options

Anti-Bias Rules

Implementation Methodology

Debugging Methodology

Phase I: Information Gathering

Phase II: Testing Hypothesis

Phase III: Weigh Tradeoffs

Code Structure & Modularity

Testing & Reliability

Style

Documentation

AI Behavior Rules

TypeScript Language Guidelines 🌊

Code Quality & Validation

Typescript Testing Guidelines

TypeScript Patterns

Advanced Types

NestJS Project Guidelines 😺

Validation & Documentation

Database & ORM

Testing Patterns

NestJS CLI Usage 🔧

Basic Module Generation

Full Resource Generation

Integration Testing Strategy

Integration Testing with Testcontainers 🐳

Dependencies

Best Practices

Role

Scope

Handoff

Seam example

Owners