Applying to a New Project

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• INTEGRATION.md
• MIGRATION-NOTES.md
• claude-md-snippets/universal.md
• claude-md-snippets/critical.md
• claude-md-snippets/testing.md

The amir-bug-patterns repository provides a mechanical framework for applying proven bug prevention patterns to new software projects. The goal is to ensure that fundamental errors encountered in previous projects—such as asynchronous race conditions, state synchronization failures, and security vulnerabilities—are not repeated. This is achieved by integrating specific triggers and rules into the project's CLAUDE.md file and automated code review tools.

Sources: README.md:1-5, INTEGRATION.md:3-8

Integration Workflow

Applying these patterns to a new project involves a structured checklist that populates the local project context with relevant safety rules based on its technology stack.

Setup Checklist

The following steps should be completed within approximately 20 minutes when starting a new project:

1. Initial CLAUDE.md: Copy the universal snippets (universal.md, critical.md, and testing.md) into the project's CLAUDE.md.
2. Stack Decision Tree: Evaluate the project's stack and copy corresponding BY-STACK files and snippets.
3. Trigger Block: Insert the dynamic trigger table into CLAUDE.md to reference the central repository during implementation.
4. Bugbot Configuration: Connect the repository to automated review tools (e.g., cubic, qodo) and paste the standard review block.
5. Day-1 Defaults: Establish core strategies for idempotency, state synchronization, and input validation.

Sources: INTEGRATION.md:126-140, README.md:16-19

Component Relationship Diagram

The following diagram illustrates how the central repository knowledge flows into a specific project instance.

Core Patterns Integration

Every project, regardless of the technology stack, must include the "Universal," "Critical," and "Testing" patterns. These cover approximately 90 lines of baseline rules for security, data integrity, and Hebrew-specific code comments.

Required Universal Snippets

Source File	Destination	Description
claude-md-snippets/universal.md	CLAUDE.md	6 core rules for Async, React, and SQL.
claude-md-snippets/critical.md	CLAUDE.md	13 high-severity security and privacy rules.
claude-md-snippets/testing.md	CLAUDE.md	6 rules to prevent "lying" CI/CD pipelines.
claude-md-snippets/hebrew.md	CLAUDE.md	Standards for Hebrew comments and BiDi handling.

Sources: README.md:16-30, claude-md-snippets/universal.md, claude-md-snippets/critical.md

Stack-Specific Selection

After the universal baseline is established, specific modules are added based on a decision tree. Each "Yes" for a technology requirement results in copying one stack-specific reference file and one snippet.

Technology Mapping

If the project has...	Reference File	CLAUDE.md Snippet
React Frontend	BY-STACK/react-frontend.md	claude-md-snippets/react.md
SQLAlchemy Async	BY-STACK/async-orm.md	claude-md-snippets/async-orm.md
Cron / Scheduled Tasks	BY-STACK/cron-jobs.md	claude-md-snippets/cron-jobs.md
Postgres / SQL	BY-STACK/postgres.md	claude-md-snippets/postgres.md
External SDKs (Stripe/OAuth)	BY-STACK/external-sdk.md	claude-md-snippets/external-sdk.md
State Machines / Enums	BY-STACK/state-machine.md	claude-md-snippets/state-machine.md

Sources: README.md:32-48, INTEGRATION.md:65-107

Implementation Triggers

The CLAUDE.md file must contain a "Trigger Block." This table instructs developers (or AI agents) to read specific patterns before touching sensitive code areas.

Trigger Table Logic

Permanent Triggers

Certain triggers apply at all times during the implementation phase:

• Before wrapping code in try/except: Consult CRITICAL-PATTERNS.md K11 (Return values as failure).
• Before writing a new test: Consult claude-md-snippets/testing.md.
• After a test fails on an exception: Consult bugbot-rules/widened-exception-scope.md.
• Before passing secrets via URL: Consult CRITICAL-PATTERNS.md K14.

Sources: INTEGRATION.md:32-37

Day-1 Architectural Actions

The migration analysis identifies three high-impact patterns that should be addressed on the very first day of a new project to prevent future data corruption or silent failures.

1. Race Condition Strategy (CORE U1): Before writing the first webhook or cron job, decide on an idempotency strategy (e.g., UNIQUE constraints or SELECT FOR UPDATE).
2. React State Sync (CORE U2): Establish a project-wide convention for syncing local state from props (e.g., using key={id} or derived state).
3. External Input Guards (CORE U3): Implement mandatory isinstance and isfinite guards for all external API and LLM outputs.

Sources: MIGRATION-NOTES.md:73-108

Conclusion

Applying amir-bug-patterns to a new project transforms a static library of errors into an active safeguard. By embedding triggers directly into the developer's context (CLAUDE.md) and automating enforcement through bugbots, the project ensures that high-severity issues like TOCTOU races and PII leaks are identified before they reach production. The lifecycle is completed by the "Closed Loop" requirement: if a new pattern is discovered during a code review, it must be added back to the central repository and the new project's trigger table simultaneously.

Sources: README.md:57-65, INTEGRATION.md:39-44