AI Context Integration Workflow

Relevant source files

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

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

The AI Context Integration Workflow is a systematic process designed to inject real-world production bug patterns into AI-assisted development sessions. By leveraging a centralized repository of lessons learned (amir-bug-patterns), the workflow ensures that AI agents (like Claude or specialized "bugbots") are aware of recurring failure modes before implementation begins. This prevents the repetition of fundamental errors across different tech stacks and problem domains.

The workflow operates on a tiered structure, distinguishing between universal patterns applicable to any project and stack-specific patterns. It utilizes CLAUDE.md files as the primary entry point for context within active projects, acting as a bridge between the centralized knowledge base and the specific implementation task at hand.

Sources: README.md:1-15, INTEGRATION.md:1-10

Architecture and Mechanisms

The system relies on three primary mechanisms to ensure knowledge transfer and one feedback loop to prevent staleness. Instead of duplicating the entire knowledge base into every project, the workflow uses triggers within the project's local documentation to point to the central repository.

Context Injection Layers

Layer	Component	Description
Universal Baseline	universal.md, critical.md, testing.md	~70-90 lines of essential rules applied to every new project regardless of stack.
Trigger Block	CLAUDE.md Integration	A table mapping specific technical areas (e.g., "Webhooks") to their corresponding pattern files in the repository.
External Review	Code Review Instructions	A condensed block of instructions for external AI review tools like Cubic, Qodo, or CodeRabbit.
Feedback Loop	Loop Closure	A mandatory process where newly caught patterns are added to the central repo and their triggers updated in active projects.

Sources: INTEGRATION.md:12-25, README.md:33-50

Integration Flow Diagram

The following diagram illustrates how the knowledge from the amir-bug-patterns repository is integrated into a development session and how new patterns are fed back into the system.

Project Setup and Bootstrapping

When initiating a new project, a specific sequence of steps is followed to establish the AI context. This process takes approximately 20 minutes and ensures the "Day-1" defaults are applied.

Step-by-Step Integration

1. Initial CLAUDE.md: Paste the universal, critical, and testing snippets (approx. 70 lines).
2. Stack Mapping: Use the stack decision tree to identify relevant files (e.g., BY-STACK/postgres.md).
3. Trigger Block: Insert the Markdown table in CLAUDE.md that maps implementation topics to repo files.
4. Bugbot Configuration: Inject review guidelines into AI PR review tools.
5. Day-1 Defaults: Decide on strategies for idempotency and state synchronization based on MIGRATION-NOTES.md.

Sources: INTEGRATION.md:162-180, MIGRATION-NOTES.md:65-90

Stack Decision Logic

The workflow uses a decision tree to determine which specific patterns to include:

Core Patterns Integration

The most critical patterns are integrated directly into the CLAUDE.md trigger block because they have high severity or frequency across projects.

The CAS/Idempotency Pattern (U1)

Developers are instructed to always implement a write-before-call strategy for irreversible external actions.

Integration Priorities Table

Based on the meta-analysis of project migrations, these three patterns are prioritized for Day-1 integration due to their impact:

Priority	Pattern	File Reference	Action Required
1	Async Race / TOCTOU	CORE-PATTERNS.md U1	Define idempotency strategy for every endpoint.
2	React State Sync	CORE-PATTERNS.md U2	Choose between key={id} or useEffect resync.
3	External Input Validation	CORE-PATTERNS.md U3	Implement isinstance guards before any .get() or .strip().

Sources: MIGRATION-NOTES.md:65-95

Conclusion

The AI Context Integration Workflow transforms retrospective "post-mortem" knowledge into proactive development constraints. By strictly following the integration steps in INTEGRATION.md and maintaining the feedback loop between code reviews and the central repository, the system ensures that AI agents operate within the safety boundaries established by previous production failures. This methodology shifts the focus from fixing bugs to preventing their implementation through continuous context injection.

Sources: INTEGRATION.md:1-10, README.md:1-10