SECURITY_CORE.md Security
Comprehensive security guidelines covering authentication and authorization, input validation, data protection, error handling, AI agent security, insider threat mitigation, supply chain security, API security, and zero-trust defaults.
When to use: Reference when building any system that handles user data, authentication, external input, or third-party integrations. Essential reading before designing auth flows, API endpoints, or data storage.
SCALABILITY_CORE.md Scalability
Guidelines for building systems that handle 10x growth without a rewrite. Covers statelessness, async-first decoupling with message queues, database scaling strategies, graceful degradation with circuit breakers, and API versioning.
When to use: Reference when designing system architecture, choosing between synchronous and asynchronous patterns, planning database schemas for growth, or implementing API contracts that must evolve over time.
MAINTAINABILITY_CORE.md Maintainability
Practices for reducing technical debt and keeping code easy to read and test. Covers the Rule of Three for abstraction, self-documenting code, automated testing requirements, meaningful error context, and dependency management.
When to use: Reference during code reviews, when deciding whether to abstract shared logic, when setting up testing strategy, or when evaluating whether to add a new dependency.
UIUX_CORE.md UI/UX
Standards for a professional, responsive user experience. Covers optimistic UI updates, the 3-click rule for navigation depth, the 100ms visual feedback rule, four-state design (loading, empty, error, success), and design system consistency.
When to use: Reference when designing user interfaces, implementing loading and error states, building navigation structures, or establishing a design system with consistent spacing, typography, and color.
AVAILABILITY_CORE.md Availability
Guidelines for maximizing uptime and eliminating single points of failure. Covers redundancy and replication, traffic management with health checks, self-healing and autoscaling, data integrity with PITR backups, and zero-downtime deployments.
When to use: Reference when planning infrastructure, configuring load balancers, setting up database failover, defining backup and recovery strategies, or designing deployment pipelines.
ADAPTABILITY_CORE.md Adaptability
Standards for internationalization and localization. Covers separation of content and logic with externalized strings, cultural formatting for dates, currencies, numbers, and measurements, layout fluidity for RTL and text expansion, and locale-aware search and sorting.
When to use: Reference when building any user-facing application that may serve multiple languages, regions, or cultures. Essential before hardcoding any date format, currency symbol, or sort order.
CLEAN_CODE.md Clean Code
Fundamental clean code rules. Covers KISS and the Boy Scout Rule, descriptive naming with no magic numbers, singular-purpose functions with minimal arguments, no flag parameters, no hidden side effects, and no negative conditionals.
When to use: Reference during all code writing and review. These are the daily habits that keep code readable, predictable, and easy to modify. The most frequently referenced guide in the collection.
ARCHITECTURAL_DESIGN.md Architecture
Structural design principles. Covers the Law of Demeter, dependency injection, polymorphism over conditional logic, boundary encapsulation, hiding internal data structures, small focused classes, and preferring non-static methods.
When to use: Reference when designing module boundaries, defining class responsibilities, deciding how components communicate, or reviewing code for excessive coupling and hidden dependencies.
SOURCE_STRUCTURE.md Structure
Code layout and formatting standards. Covers vertical flow with code density and proximity, top-down readability, short lines without horizontal scrolling, consistent indentation, and meaningful use of white space for grouping.
When to use: Reference when organizing files, arranging functions within a file, or establishing formatting standards for a project. Useful during initial project setup and when onboarding new team members.
DOCUMENTATION_COMMENTS.md Documentation
Philosophy and rules for documentation and comments. Prioritizes self-explaining code over comments, intent over mechanics, and identifies anti-patterns like redundant comments, noisy banners, and commented-out code.
When to use: Reference when deciding whether to add a comment, during code review to flag unnecessary or misleading comments, or when establishing documentation standards for a project.
ENVIRONMENT_STANDARDS.md Environment
Rules for environment management across dev, staging, and production. Covers environment-agnostic configuration via .env files, the production lock for destructive operations, data sanitization for PII/GDPR compliance, and staging-production feature parity.
When to use: Reference when setting up CI/CD pipelines, managing environment configurations, copying or seeding data between environments, or defining deployment safeguards and approval gates.
AI_CODING.md AI Guardrails
Guardrails for AI-assisted code generation. Covers the Hallucination Guardrail (verify packages and APIs exist), the Security Leak Guardrail (scan for hardcoded secrets), and the Copy-Paste Guardrail (always provide full context in edits).
When to use: Include in every project that uses AI-assisted coding. Reference when reviewing AI-generated code, when configuring Claude Code CLAUDE.md instructions, or when onboarding a team to AI-assisted workflows.