Claude AI Instructions Snippets
Relevant source files
The following files were used as context for generating this wiki page:
Claude AI Instructions Snippets are concise, highly condensed sets of rules (typically ≤ 30 lines) designed to be pasted directly into a project's CLAUDE.md file. Their purpose is to provide immediate, actionable context to AI coding assistants about recurring bug patterns, project-specific conventions, and critical safety checks that have historically caused production issues. These snippets serve as a technical baseline to prevent the recurrence of fundamental mistakes across different stacks and domains.
The library is organized into universal patterns (applicable to all projects) and stack-specific snippets. Universal snippets cover baseline correctness, security, and testing, while stack-specific snippets address unique challenges in environments such as React, Postgres, External SDKs, and Cron jobs. Integration is managed through a "trigger" system where CLAUDE.md points to these snippets based on the specific module a developer is currently modifying.
Sources: README.md:9-25, INTEGRATION.md:9-15, claude-md-snippets/universal.md
Universal and Critical Patterns
The universal snippets form the core of the instruction set, focusing on asynchronous race conditions, data validation, and security enforcement. They are designed to be stack-agnostic, providing a "fail-closed" philosophy for all development activities.
Core Logic and Concurrency
The system emphasizes strict handling of asynchronous operations to prevent Time-of-Check to Time-of-Use (TOCTOU) errors. Developers are instructed to use atomic operations such as INSERT ... ON CONFLICT or Compare-and-Swap (CAS) before performing irreversible external actions.
The diagram represents the recommended "Reserve-then-fill" flow to ensure atomicity between local state and external side effects.
Sources: claude-md-snippets/universal.md:3, claude-md-snippets/webhooks.md:3, claude-md-snippets/state-machine.md:14-16
Input Validation and SDK Safety
External input validation follows a strict isinstance guard policy. Snippets mandate that all external data—whether from webhooks, AI outputs, or SDK responses—must be verified for type and range before processing.
| Category | Requirement | Source |
|---|---|---|
| Types | Use isinstance(obj, dict/list/str) guards | claude-md-snippets/external-sdk.md:12-14 |
| Numbers | isfinite() + range checks | claude-md-snippets/universal.md:8-9 |
| SDK Boot | Try/except wrap with format validation | claude-md-snippets/external-sdk.md:9-10 |
| SDK Errors | Catch base class (e.g., anthropic.APIError) | claude-md-snippets/external-sdk.md:3-5 |
Stack-Specific Instruction Sets
Instruction snippets are modularized to address specific architectural components. This allows for a lightweight CLAUDE.md that only includes relevant rules for the project's technology stack.
Database and State Management
Postgres and SQL patterns focus on the nuances of NULL handling, BigInteger for external IDs, and mandatory tiebreakers for paginated queries. State machine snippets ensure that status updates are atomic across "sibling fields" (e.g., status, activity type, and timestamps).
Background Tasks and Cron Jobs
Cron job snippets prevent infinite loops by mandating explicit terminal states. Heuristics like attempts < MAX are discouraged in favor of dedicated processing_status columns.
- Terminal State: Every query must filter on a column that the action explicitly sets to
Falseupon completion. - Concurrency: Use
UPDATE ... RETURNINGto claim rows atomically between the beat-scheduler and ad-hoc dispatchers. - Async Safety: Sync calls inside async cron loops must be wrapped in
asyncio.to_thread.
Sources: claude-md-snippets/cron-jobs.md:3-14, claude-md-snippets/webhooks.md:18-19
Testing and Verification Snippets
The testing snippets redefine the relationship between tests and production code. They advocate for testing through the actual consumer interface rather than the technical specification.
- Consumer Interface: UI features must be tested by scraping generated HTML (e.g.,
actionand form fields) rather than manual POST requests. - Browser Enforcement: Critical flows involving CSP, CORS, or
SameSitecookies must be verified in a real browser (Playwright/Chromium) as standard test clients do not enforce these policies. - Regression Check: A new test added with a fix MUST be run against the old code to ensure it fails; otherwise, the test provides no evidence of coverage.
Sources: claude-md-snippets/testing.md:3-18
Integration Strategy
Integration involves a two-tiered approach: pasting baseline snippets and maintaining a "Trigger Table" in the project's CLAUDE.md.
This flow ensures that high-density knowledge is retrieved exactly when relevant to the task at hand.
Sources: INTEGRATION.md:9-27, README.md:30-45
Claude AI Instructions Snippets serve as a living repository of lessons learned from production failures. By distilling complex post-mortems into ≤30-line actionable rules, they provide a mechanism for AI assistants to maintain high code quality and security standards without overwhelming the project's primary documentation. This structure ensures that as the project stack evolves, the relevant safety guidelines are automatically triggered and enforced.