Maintaining the Library
Relevant source files
The following files were used as context for generating this wiki page:
Maintaining the amir-bug-patterns library is a systematic process of capturing new bug patterns from production environments and cross-referencing them into a centralized knowledge base. The primary goal is to prevent the recurrence of fundamental mistakes across different projects and technology stacks by creating a "mental model" that is applied mechanically through tools like CLAUDE.md and bug-detection bots.
The maintenance lifecycle is triggered by real-world findings, such as code reviews or recurring errors. It involves documenting the post-mortem in specific source project files and then promoting those findings through a tiered system based on frequency and severity.
Sources: README.md:9-19, README.md:104-124
The Maintenance Lifecycle
The library follows a strict "closing the loop" protocol. Documentation of a new pattern should happen the same day the evidence is fresh, particularly when a code reviewer catches a valid finding not yet covered or when the same type of mistake is corrected twice.
Pattern Ingestion Process
- Documentation: Document the new pattern under
docs/source-projects/<project-name>-patterns.mdusing the standard template (Pattern ID, commits, false positives, and recommended mode). - Tier Promotion: Cross-reference the pattern against existing tiers.
- Automation: Create a clean detection signature in
bugbot-rules/<name>.md. - Integration: Add a trigger line in the
CLAUDE.mdof relevant projects.
Sources: README.md:104-121, INTEGRATION.md:24-33
The following diagram illustrates the flow from a bug discovery to its integration into the library:
The diagram shows the decision logic for categorizing new bug patterns based on severity and frequency.
Sources: README.md:104-118, MIGRATION-NOTES.md:106-110
Categorization Tiers
Maintaining the library requires accurate classification of patterns into tiers. This ensures that developers are not overwhelmed with irrelevant information while still being alerted to critical risks.
| Tier | Criteria | File Reference |
|---|---|---|
| Core Patterns | Confirmed in 3 out of 3 source projects; applicable everywhere. | CORE-PATTERNS.md |
| Critical Patterns | High severity (Security, Data Loss, Privacy) regardless of frequency. | CRITICAL-PATTERNS.md |
| Recurring Patterns | Confirmed in 2 out of 3 source projects; stack-dependent. | RECURRING-PATTERNS.md |
| Testing Patterns | Patterns where the test is the source of the bug (CI lies). | TESTING-PATTERNS.md |
| Stack Patterns | Specific to a technology (e.g., React, Postgres, Cron). | BY-STACK/*.md |
Sources: README.md:21-25, README.md:107-112, MIGRATION-NOTES.md:106-110
Integration and Synchronization
A pattern without a trigger is a pattern that will not be read. Maintenance includes ensuring that the CLAUDE.md file in every active project contains a mapping table that points to the library.
Trigger Mechanism
The library uses a "Template + Data" approach for integration. INTEGRATION.md provides a standard block for CLAUDE.md which instructs the AI agent on when to read specific patterns based on the developer's current task.
| When you touch... | Read |
|---|---|
| Async/Race conditions | amir-bug-patterns/CORE-PATTERNS.md U1 |
| External SDK calls | amir-bug-patterns/BY-STACK/external-sdk.md |
Sources: INTEGRATION.md:11-23, INTEGRATION.md:65-75
Bugbot Instructions
Maintenance also involves updating instructions for automated review tools (e.g., CodeRabbit, qodo). These instructions must be kept concise to avoid diluting attention but should cover high-priority universal patterns like race conditions and security leaks.
Sources: INTEGRATION.md:154-177
Meta-Analysis and Evolution
Periodic review of the library is required to ensure the mental model of "Universal vs. Stack-specific" remains valid.
Quarterly Reviews
Review MIGRATION-NOTES.md quarterly to check if patterns previously considered stack-specific have become universal. For example, the "Reserve-then-fill" pattern was found to be the same root cause as "TOCTOU duplicate sends," leading to a broader definition of CORE U1.
Sources: README.md:123-124, MIGRATION-NOTES.md:52-58
Source Project Integrity
Every documented pattern must link back to specific commits or post-mortem documents. If a pattern is found to be a "false positive" in certain contexts (e.g., reporting-only cron jobs), these exceptions must be added to the documentation to prevent over-alerting.
Sources: BY-STACK/cron-jobs.md:43-45, BY-STACK/hebrew-source.md:36-40
Conclusion
Maintaining the library is a continuous loop of real-world discovery, documentation, and automation. By strictly following the daily documentation rule and the tiered promotion system, the library evolves from a static collection of errors into a dynamic safety net for all software projects within the ecosystem.