Improve adherence to AI rules

[jhnns]

AI agents sometimes seem to ignore some rules (e.g. they use single letter type parameter names). This is probably because the training data contains so much examples where this is done.

I asked Claude how we can improve the rules so that it doesn't use single letter type parameter names anymore. This is its answer:

1. Move it to a dedicated section

Instead of burying it at the end of the Types section, create a separate "Generic Type Parameters" section:

Generic Type Parameters

• NEVER use single letter type parameters (❌ T, K, V, U)
• ALWAYS use descriptive names (✅ TValue, TResult, TInput, TKey)
• Examples:
  • ❌ function map<T, U>(items: Array<T>, fn: (item: T) => U): Array<U>
  • ✅ function map<TInput, TOutput>(items: Array<TInput>, fn: (item: TInput) => TOutput): Array<TOutput>

2. Add it to Universal Principles

Include it at the top level where it's impossible to miss:

Universal Principles

• Write idiomatic, self-documenting code with clear, descriptive names
• CRITICAL: Never use single letter names for anything (variables, functions, type parameters)
• Optimize for readability

3. Add explicit examples of violations

In the Types section, add a "Common Mistakes" subsection:

Types - Common Mistakes to Avoid

❌ NEVER DO THIS:

type Result<T, E> = { ok: T } | { error: E }
function identity<T>(value: T): T
interface Store<K, V> { get(key: K): V }

✅ ALWAYS DO THIS:
type Result<TValue, TError> = { ok: TValue } | { error: TError }
function identity<TValue>(value: TValue): TValue
interface Store<TKey, TValue> { get(key: TKey): TValue }

4. Add it to the file header

Add a "CRITICAL RULES" section at the very top:

---
description: JavaScript and TypeScript best practices and conventions
globs: **/*.js, **/*.ts, **/*.mjs, **/*.cjs, **/*.mts, **/*.cts
---

# ⚠️ CRITICAL RULES - ALWAYS FOLLOW

1. **NO SINGLE LETTER TYPE PARAMETERS** - Use `TValue` not `T`, `TKey` not `K`
2. Use `.ts` file extensions in imports
3. No default exports

# JavaScript & TypeScript

5. Use repetition

Mention it multiple times throughout the document to reinforce:

• Once in Universal Principles
• Once in Naming Conventions
• Once in Types section
• Once in a dedicated Generic Types section

The most effective approach would be combining #1, #3, and #4 - having it prominently at the top, in its own section with examples, and showing explicit violations to avoid.

---

/cc @benekoehler