ai-coding-discipline

AI Coding Discipline

These rules override default AI coding tendencies. Follow them in ALL code you write or modify.

---

Rule 1: No Silent Fallbacks

Never use fallback values to mask data that should not be missing.

// FORBIDDEN — hides upstream bugs
const price = product?.price ?? 0;
const userName = user?.name || "Unknown";

// CORRECT — fail fast when data contract is violated
if (product.price == null) {
  throw new Error(`Product ${product.id} is missing price`);
}
const price = product.price;

When fallbacks ARE acceptable:

• User-facing display with explicit design intent (e.g., avatar placeholder)
• Optional configuration with documented defaults
• External input parsing where absence is a valid state

Checklist before writing ??, ||, or ?.:

1. Can this value legitimately be null/undefined at this point?
2. If it is null, will the fallback produce a correct result downstream?
3. Would a thrown error help me find a bug faster?

If the answer to #3 is yes, throw instead of falling back.

---

Rule 2: No Catch-All try/catch in Business Logic

Business logic functions must NOT wrap everything in try/catch. Let errors propagate naturally.

// FORBIDDEN — swallows all errors into a useless null
async function createOrder(data: OrderInput) {
  try {
    const user = await getUser(data.userId);
    const coupon = await validateCoupon(data.couponCode);
    const order = await saveOrder({ ...data, discount: coupon.value });
    return order;
  } catch (error) {
    console.log('Error creating order:', error);
    return null; // caller gets null, has no idea what failed
  }
}

// CORRECT — let errors bubble up, catch at the boundary
async function createOrder(data: OrderInput) {
  const user = await getUser(data.userId);
  const coupon = await validateCoupon(data.couponCode);
  const order = await saveOrder({ ...data, discount: coupon.value });
  return order;
}

// Catch ONLY at the API/controller boundary
app.post('/orders', async (req, res) => {
  try {
    const order = await createOrder(req.body);
    res.json(order);
  } catch (error) {
    logger.error('Order creation failed', { error, body: req.body });
    res.status(500).json({ error: 'Order creation failed' });
  }
});