Chain of Thought Comments

What are Chain of Thought Comments?

Chain of Thought (CoT) comments document the reasoning behind code decisions. They help both humans and AI understand:

• →Why this approach was chosen over alternatives
• →What problem this code solves
• →What constraints influenced the design
• →What would break if this code changed

Why AI Needs Context

Without reasoning context, AI might "improve" code in ways that break things:

// Fetch users
function getUsers() {
  return db.query('SELECT * FROM users LIMIT 100');
}

/**
 * REASONING: Limited to 100 because:
 * 1. UI can't render 10k+ users performantly
 * 2. Full table scan would timeout
 * 3. Pagination handled by separate endpoint
 */
function getUsers() {
  return db.query('SELECT * FROM users LIMIT 100');
}

CoT Comment Format

Use structured comments that AI can easily parse:

/**
 * DESIGN DECISION: Using setTimeout instead of setInterval
 *
 * REASONING:
 * 1. setInterval can stack calls if handler takes too long
 * 2. setTimeout guarantees gap between executions
 * 3. Easier to cancel and restart with dynamic delays
 *
 * ALTERNATIVES CONSIDERED:
 * - setInterval: Rejected due to stacking issue
 * - requestAnimationFrame: Overkill for this use case
 *
 * CONSTRAINTS:
 * - Must handle network latency (up to 5s)
 * - Must not block UI thread
 *
 * PATTERN: Pattern-POLLING-001
 */
function pollForUpdates() {
  fetchUpdates().then(() => {
    setTimeout(pollForUpdates, 5000);
  });
}

Key Sections

• DESIGN DECISION: One-line summary of the choice
• REASONING: Numbered list of why this approach
• ALTERNATIVES CONSIDERED: What else was tried
• CONSTRAINTS: What limitations influenced design
• PATTERN: Reference to a documented pattern (optional)

When to Add CoT Comments

How AI Uses CoT Comments

When AI assistants like Claude Code or Cursor read your code, they automatically see and understand CoT comments:

1. 1AI reads the file you're working on, including comments
2. 2CoT comments provide context about design decisions
3. 3AI understands constraints and avoids breaking documented patterns
4. 4AI respects the reasoning and suggests compatible changes