Debugging Patterns

Your auth endpoint fails roughly 30% of logins in production. The stack trace points at a line that looks fine, the failure vanishes the moment you attach a debugger, and your PM wants an ETA. This is the kind of bug that eats an afternoon. AI does not magically know the answer either — but used systematically, it turns a frustrating hunt into a tight loop of instrument, reproduce, correlate, fix.

What You’ll Walk Away With

• A reusable prompt for instrumenting intermittent failures with strategic logging
• A workflow for turning a raw production stack trace into a defensive fix
• A copy-paste prompt for writing a failing race-condition test before you fix the bug
• A cross-service tracing recipe that correlates logs by request ID
• The failure modes of AI-assisted debugging — and how to keep it honest

Pattern 1: The Strategic Logging Loop

The highest-leverage pattern: let the AI instrument the suspect path, reproduce under load, then feed the logs back for correlation. The workflow is the same in all three tools — only the surface changes (Cursor edits the file in the editor, Claude Code runs headless over the repo, Codex runs in the TUI or Cloud).

1. Describe the problem precisely. Vague input produces vague logging. Give it the symptom, the frequency, and what you have ruled out.

   Tip

   Copy-paste prompt for intermittent auth failures:

   Add strategic debug logging to auth.js to diagnose intermittent token validation failures (~30% of logins, no correlation with user type or time of day). Instrument token generation, validation timing, clock skew between issuer and verifier, and state transitions. Use a structured [AUTH] log prefix with timestamps so I can grep and correlate. Do not change behavior — logging only.

2. Let the tool add the logging. The same prompt drives each tool:

   Cursor

   Open auth.js, select the validateToken function, and run the prompt in Agent mode (Cmd/Ctrl+I). Review the diff inline before accepting. Cursor adds targeted, structured logging:

   async function validateToken(token) {
     console.log('[AUTH] validation started', {
       tokenLength: token?.length,
       at: Date.now(),
     });
     try {
       const decoded = jwt.verify(token, SECRET);
       const msToExpiry = decoded.exp * 1000 - Date.now();
       console.log('[AUTH] decoded', { userId: decoded.userId, msToExpiry });
       if (msToExpiry < 60_000) {
         console.warn('[AUTH] token expiring soon', { msToExpiry });
       }
       return decoded;
     } catch (error) {
       console.error('[AUTH] validation failed', {
         message: error.message,
         iat: jwt.decode(token)?.iat,
       });
       throw error;
     }
   }

   Claude Code

   Run the prompt headless at the repo root, then reproduce and feed the logs back:

   claude "Add strategic debug logging to auth.js to diagnose intermittent token validation failures. Instrument timing, clock skew, and race conditions. Logging only."
   
   # Reproduce under load, capture the output
   NODE_ENV=debug npm start 2>&1 | tee debug.log
   
   # Hand the captured logs back for correlation
   claude "Analyze debug.log and identify what correlates with the [AUTH] validation failures"

   Codex

   Launch the TUI with the prompt, or run it headless with codex exec:

   codex "add strategic debug logging to auth.js for intermittent token validation failures: timing, clock skew, race conditions. logging only"
   
   # Or non-interactive for CI / scripted reproduction
   codex exec "instrument auth.js token validation with structured [AUTH] logging, no behavior change" \
     --sandbox workspace-write

3. Reproduce under load to surface the timing-dependent failure.

   # Hammer the path so the intermittent failure actually fires
   npm test -- --grep "authentication" --repeat 100 2>&1 | tee debug.log

4. Feed the logs back and ask for correlation, not a guess.

   Tip

   Copy-paste prompt for log correlation:

   Here is debug.log from 100 reproduced runs. Roughly 30% failed. Correlate the [AUTH] failure entries against request duration, msToExpiry, and iat. Tell me what the failing requests have in common and what the passing ones don’t — do not propose a fix yet, just the correlation and your confidence level.

   A good response narrows to a testable cause — e.g. “failures cluster when validation latency pushes msToExpiry negative; the token expires mid-request. Secondary signal: iat skew of ~4s between two hosts.” Now you fix clock-skew tolerance and pre-emptive refresh against evidence, not a hunch.

Pattern 2: Production Stack-Trace to Defensive Fix

A raw stack trace from Sentry or your logs is the single richest input you can hand an AI — it pins the file, line, and call chain. The job is to turn it into a fix that handles the edge case without papering over the real cause.

Tip

Copy-paste prompt for a production stack trace:

Production error from Sentry:

TypeError: Cannot read property 'id' of undefined
  at UserService.processOrder (/app/services/user.js:145:23)
  at async OrderController.create (/app/controllers/order.js:67:18)

Walk the call chain and tell me which value is undefined at line 145 and how it got there. Then propose a fix that fails loudly for genuinely-invalid input but degrades gracefully for the legitimate-but-incomplete case. Do not just add ?. everywhere — distinguish “should never happen” from “expected sometimes”.

The distinction in that last sentence is what stops the AI from silencing a real bug. A good response separates the two cases:

async processOrder(userId, orderData) {
  // "Should never happen" -> fail loudly
  if (!userId) throw new ValidationError('User ID required');

  const user = await this.getUser(userId);
  if (!user) throw new NotFoundError(`User ${userId} not found`);

  // "Expected sometimes" -> degrade gracefully
  if (!user.stripeCustomer?.id) {
    logger.warn('User missing Stripe customer; creating one', { userId });
    user.stripeCustomer = await this.createStripeCustomer(user);
  }
  return this.createOrder(user, orderData);
}

Pattern 3: Memory Leak Detection

When heap usage climbs without bound, lead with real tooling, then let the AI interpret the evidence. Capture a snapshot with Node’s built-in inspector (node --inspect, then Chrome DevTools Memory tab, or node --heapsnapshot-signal=SIGUSR2), or run clinic.js (clinic heapprofiler) or 0x for a flame graph. Hand the AI the retained-size breakdown, not a vague “it’s leaking”.

Tip

Copy-paste prompt for a heap snapshot diff:

Two heap snapshots taken 1 hour apart on our Express app. Retained size grew ~100MB; the diff is dominated by closures and arrays under EventManager. Here are the top 10 retainers: [paste]. Identify the most likely leak source, explain the retention path, and show the minimal cleanup (e.g. an unsubscribe/destroy() path) — not a rewrite of the class.

The usual culprit the AI will surface is an unbounded collection — listeners, timers, or cache entries added but never removed. The fix is a cleanup path that callers actually invoke:

addListener(event, callback) {
  const listener = { event, callback };
  this.listeners.push(listener);
  // Hand back an unsubscribe so callers can release the reference
  return () => {
    const i = this.listeners.indexOf(listener);
    if (i > -1) this.listeners.splice(i, 1);
  };
}

Pattern 4: Race Condition Detection

Identify and fix timing-related bugs. The strongest move is to make the AI write a failing test that reproduces the race before it touches the fix — otherwise you cannot tell whether the fix worked.

Tip

Copy-paste prompt for a race-condition repro test:

Users report duplicate charges when they double-click submit — happens ~5% of the time under load. Write a Vitest test that fires 5 concurrent processPayment calls for the same user with Promise.allSettled and asserts exactly one fulfils while the rest reject with an idempotency error. The test must fail against the current code. Then implement the minimal idempotency guard that makes it pass.

// AI writes the failing test first
describe('Payment Processing Race Conditions', () => {
  it('should handle concurrent submissions', async () => {
    const userId = 'test-user';
    const paymentData = { amount: 100, currency: 'USD' };

    // Simulate rapid clicks
    const promises = Array(5).fill(null).map(() =>
      processPayment(userId, paymentData)
    );

    const results = await Promise.allSettled(promises);

    // Only one should succeed
    const successful = results.filter(r => r.status === 'fulfilled');
    expect(successful).toHaveLength(1);

    // Others should be rejected with idempotency error
    const rejected = results.filter(r => r.status === 'rejected');
    expect(rejected).toHaveLength(4);
    rejected.forEach(r => {
      expect(r.reason.message).toContain('Payment already processing');
    });
  });
});

// AI suggests idempotency solution
class PaymentService {
  constructor() {
    this.processingPayments = new Map();
  }

  async processPayment(userId, paymentData) {
    const idempotencyKey = `${userId}-${Date.now()}`;

    // Check if already processing
    if (this.processingPayments.has(userId)) {
      throw new ConflictError('Payment already processing');
    }

    // Mark as processing
    this.processingPayments.set(userId, idempotencyKey);

    try {
      // Process payment
      const result = await this.chargeCard(paymentData);
      return result;
    } finally {
      // Always cleanup
      this.processingPayments.delete(userId);
    }
  }
}

Cross-Service Debugging

When a failure spans services, the signal lives in the correlation, not in any single log file. The recipe: stamp a request ID at the edge, gather logs from every hop, and let the AI rebuild the timeline.

Tip

Copy-paste prompt for cross-service correlation:

Here are logs from three services (api-gateway.log, user-service.log, payment-service.log), each line prefixed with a requestId. Reconstruct the full timeline for requestId: abc-123 across all three, in chronological order with millisecond deltas between hops. Flag the longest gap and tell me which service owns it — that is where the latency or failure originates.

# Gather logs from every hop (adjust to your platform's log command)
kubectl logs -l app=user-service --since=1h > user-service.log
kubectl logs -l app=payment-service --since=1h > payment-service.log

# Hand them to the AI for timeline reconstruction
claude "Correlate these logs by requestId and trace the failed payment flow for abc-123"

A reconstructed timeline turns “something is slow” into “Payment Service blocked 5s waiting for the DB, then the pool exhausted and the call chain cascaded” — a root cause you can act on. For richer traces, wire up OpenTelemetry spans rather than parsing text logs; the same correlation prompt works on exported span data.

When This Breaks

AI-assisted debugging fails in specific, recognizable ways. Knowing them is what separates a real investigation from a confident-sounding dead end.

Caution

Failure modes of AI-assisted debugging:

• It invents a plausible-but-wrong root cause. With thin evidence, the model will confidently name a cause that fits the symptom but isn’t real. Defense: always ask it to state its confidence and the evidence, and never accept a fix without a test that fails first (Pattern 4).
• Log noise drowns the signal. Ask for “logging everywhere” and you get megabytes of low-value output the model then struggles to correlate. Defense: scope logging to the suspect path and use a structured prefix you can grep.
• The fix masks the symptom. Blanket ?. and empty catch {} blocks make the error disappear without fixing anything. Defense: force the “should never happen” vs “expected sometimes” distinction (Pattern 2).
• The bug is a Heisenbug. Synchronous logging changes timing and the race vanishes. Defense: buffer log entries and flush asynchronously (process.nextTick) so instrumentation doesn’t perturb the timing you’re measuring.
• Stale context. The model reasons about code that no longer matches main. Defense: re-share the current file or re-run the headless prompt against the live repo before trusting its analysis.

What’s Next

• Logging Patterns - structured logging that makes the correlation prompts above land
• Monitoring Patterns - catch these failures before users do
• Recovery Patterns - graceful degradation and retries once you know the cause