Introduction to Bug Patterns Library
Relevant source files
The following files were used as context for generating this wiki page:
The Bug Patterns Library is an organized collection of recurring software defects identified across multiple projects, different stacks, and problem domains. Its primary purpose is to provide a mechanical way to apply historical project knowledge to new projects via CLAUDE.md configurations or automated bugbot rules, effectively preventing the repetition of fundamental mistakes.
The library categorizes bugs based on three main axes: frequency (how often the pattern appears), severity (security, data loss, financial impact), and stack scope (relevance to specific technologies like React, Postgres, or External SDKs). By documenting these patterns, the repository serves as a personal context library for developers to improve code quality and security from day one of a new project.
Sources: README.md:1-12, INTEGRATION.md:1-10
Core Architecture and Classification
The library is structured into tiers that determine when and how a pattern should be applied to a project. Patterns are categorized based on their prevalence across the source projects (e.g., EmailFlow, Noa Leads, and others).
Pattern Hierarchy
- CORE-PATTERNS (U1-U6): Universal patterns identified in 3 out of 3 source projects. These are applicable to almost every software project.
- CRITICAL-PATTERNS (K1-K14): High-severity patterns involving security, privacy, or data loss, regardless of frequency.
- RECURRING-PATTERNS (R1-R5): Patterns appearing in 2 out of 3 source projects, applied if the stack is relevant.
- BY-STACK Patterns: Specialized patterns for specific technologies such as React, SQLAlchemy, Postgres, and Cron jobs.
- TESTING-PATTERNS (T1-T3): Patterns where the test infrastructure itself is the source of the bug, leading to false positives in CI.
Sources: README.md:13-20, README.md:105-130, MIGRATION-NOTES.md:7-15
Data Flow for Pattern Discovery
The following diagram illustrates how a recurring error becomes a documented pattern within the library.
The flow shows the lifecycle of a bug from detection to becoming a formalized rule or snippet.
Sources: README.md:63-78, MIGRATION-NOTES.md:115-125
Implementation and Integration
Integration of the library into active development occurs through CLAUDE.md files and automated code review tools (Bugbots).
Integration Mechanism
The system relies on "Triggers" defined in a project's CLAUDE.md. Instead of copying full pattern logic into every project, the file contains references that prompt the developer or AI agent to read the relevant pattern file from the central repository when touching a specific area of the code.
| Project Stack Component | Action / Snippet to Apply |
|---|---|
| Universal Baseline | claude-md-snippets/universal.md |
| Security/Critical | claude-md-snippets/critical.md |
| Testing Infrastructure | claude-md-snippets/testing.md |
| Cron / Scheduled Tasks | BY-STACK/cron-jobs.md |
| External SDKs | BY-STACK/external-sdk.md |
Sources: README.md:22-55, INTEGRATION.md:12-30
Code Review Automation (Bugbots)
Specific rules are provided in bugbot-rules/*.md to be used with tools like Cubic, Qodo, or CodeRabbit. These rules are stack-agnostic and focus on detection signatures for issues like TOCTOU races, PII in logs, or improper exception handling.
This diagram demonstrates the automated feedback loop during the code review process.
Sources: INTEGRATION.md:135-180, README.md:52-61
Key Technical Patterns
Async Race and TOCTOU (CORE U1)
The most frequent class of bugs involves asynchronous race conditions where a check happens outside of a lock or before a database write. The library mandates an "INSERT before external call" strategy for idempotency.
Sources: claude-md-snippets/universal.md:3-5, MIGRATION-NOTES.md:52-60
Terminal State in Cron Jobs
Cron jobs often enter infinite loops because they lack a clear terminal state. A job must be filtered such that once processed, it no longer meets the criteria of the initial query.
# POOR: Can loop forever if lead_id remains NULL for spam
q = select(Inbound).where(Inbound.lead_id.is_(None))
# RECOMMENDED: Explicit terminal state
q = select(Inbound).where(Inbound.processing_status == 'pending')
Sources: BY-STACK/cron-jobs.md:15-40, claude-md-snippets/cron-jobs.md:3-8
Testing Pitfalls (TESTING T1)
A critical pattern is "Testing the Spec, Not the Consumer." This occurs when tests use internal handlers or specific paths defined in a specification while the actual client or browser environment behaves differently (e.g., due to CSP or CORS).
Sources: TESTING-PATTERNS.md:18-35, claude-md-snippets/testing.md:3-6
Maintenance and Migration
The library is maintained through a "Close the Loop" process. When a code reviewer (AI or human) identifies a genuine bug pattern not yet documented, it must be added to the repository immediately while the evidence is fresh.
Top-3 Day-1 Priorities
For any new project, the library recommends immediate action on these high-frequency patterns:
- Async Race Conditions: Establish idempotency strategies (e.g., Unique constraints).
- React State Sync: Determine a convention for syncing local state with props (e.g., using keys or derived state).
- External Input Validation: Implement
isinstanceguards and range checks for all data arriving from external APIs.
Sources: README.md:79-90, MIGRATION-NOTES.md:85-112
The Bug Patterns Library effectively transforms individual project failures into a collective, actionable knowledge base that significantly reduces technical debt and increases the reliability of new software deployments.
Sources: README.md:1-12, INTEGRATION.md:215-225