Global Development Rules

Mission: Build professional, robust, and efficient software solutions using world-class standards.

Note: These are production standards. For learning side projects, prioritize speed and experimentation over perfection.

1. Core Philosophy

1.1 Clarity Over Cleverness

PRIORITY 1: Clear, semantic, understandable code that enhances maintainability
Simple and clear is ALWAYS superior to clever and complex
Exception: When execution speed is explicitly paramount, provide clear explanatory comments
Code should be self-documenting; comments explain WHY, not WHAT
Never use hacks or rigid fixed solutions; use robust solutions that flexibly handle all edge cases

1.2 Goal Upgrades Framework

When providing solutions, ALWAYS:

Ask for more details if needed to be very clear on the objective
Add “or better” to any objective to be achieved
Explore innovative, unconventional solutions combining effective insights in novel ways

Definitions of “Better” for Tech/Code:

Simpler, more understandable, more maintainable
Lower security risks, lower future risk (tech discontinuation)
Less vendor lock-in, better FOSS alignment
More efficient resource usage
Better error handling and debugging capability

1.3 AI-First Development

Primary AI Tools: Currently using Gemini 3.0, Cursor 2.0, Claude Code, Warp
Supporting AI Tools: Crew AI, n8n when appropriate
Leverage AI for: Code generation, documentation, testing, refactoring, project orchestration
Critical: ALWAYS review and test AI-generated code. Never blindly commit.

1.4 FOSS Preference

Prefer FOSS solutions when functionality and deliverability don’t suffer
Avoid monthly subscription lock-ins unless significantly superior
Balance: Don’t be penny-wise and pound-foolish with time vs. cost

1.5 Performance Philosophy

Priority Order: Functional and robust first. Then optimize for speed.
Speed is a feature, but not at the expense of correctness or maintainability
Ship minimal JavaScript
Optimize assets
Use SSG (Static Site Generation) by default
Profile before optimizing; document performance trade-offs

2. Technology Stack

2.1 Web Development

Core Architecture

Site Framework: Astro (latest) for all websites - static content, blogs, marketing sites
Web Applications: Svelte (or better) for complex, state-heavy applications
UI Components: Use framework-appropriate component libraries
- Currently using Shadcn-Svelte with Tailwind CSS v4 for Svelte projects
Styling: Tailwind CSS (v4)
- Use utility classes for layout and spacing
- Use @apply or CSS variables for theming and reusable components
Design System: CSS variables + Utopia fluid responsive design
Content: Markdown (.md) or MDX (.mdx) for blog/documentation content
CMS: Currently using Decap CMS for blog content management

Decision Framework: When to Use What

Static content site/blog: Astro + minimal JavaScript
Lightweight interactivity (menus, modals, simple state): Alpine.js or vanilla JS
Complex web application: Svelte or React-based framework
Default Rule: Use the simplest appropriate tool. Avoid over-engineering.

Package Management

Node.js: Currently using pnpm (fast, disk-efficient)
Python: Currently using UV (replaces pip/poetry)

Language Standards

TypeScript: Strict mode required for production code. No any unless absolutely necessary.
Python: Type hints required for all non-trivial scripts. Follow PEP 8.

2.2 Backend & Database

Database

Primary: Currently using MariaDB for direct EspoCRM and Sendy integration
Modern Projects: Currently using PostgreSQL with Supabase
Local Development: SQLite with proper migration path to production
ORM: Currently using Prisma for type-safe database access

API Development

REST APIs: Follow RESTful conventions
Authentication: Currently using Supabase Auth or EspoCRM Portal
Error Handling: Consistent error response format
Rate Limiting: Implement for all public endpoints
Documentation: OpenAPI/Swagger for all endpoints

2.3 Deployment & Hosting

Frontend Hosting

Primary: Currently using Cloudflare Pages for unbeatable performance
Alternative: Vercel for Jamstack hosting
CDN: Leverage Cloudflare’s global network
Build: Automatic builds from Git commits

Backend Hosting

Managed VPS: Currently using Cloudways on DigitalOcean Toronto
PHP Applications: EspoCRM, Sendy on LAMP stack
Node.js: For Astro SSR and APIs
Database: MariaDB on same VPS for performance

DevOps Pipeline

Version Control: GitHub with GitHub Actions for CI/CD
Secrets Management: Platform built-ins (Cloudflare Pages, n8n Cloud) or currently using Doppler
Monitoring: Currently using Uptime Kuma for service monitoring
Error Tracking: Currently using Sentry or similar for production error logging

3. Development Standards

3.1 Project Structure

project/
├── src/
│   ├── pages/          # Astro pages or app routes
│   ├── components/     # Reusable components
│   ├── layouts/        # Layout templates
│   ├── content/        # Markdown content (if applicable)
│   ├── lib/            # Utilities and helpers
│   ├── styles/         # Global CSS + design tokens
│   ├── assets/         # Images, fonts, static files
│   └── config/         # Configuration files
├── scripts/            # Build scripts, utilities
├── public/             # Static assets
├── dist/               # Build output (gitignored)
├── tests/              # Test files
├── docs/               # Documentation
│   └── Lessons.md      # Learnings from development process
└── README.md           # Setup and deployment guide

3.2 Naming Conventions

Files/Directories: kebab-case (e.g., my-component.astro, user-profile/)
Components: PascalCase (e.g., Button.astro, HeroSection.svelte)
Variables/Functions: camelCase (e.g., getUserData, isValid)
Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRIES, API_BASE_URL)
Use descriptive, searchable names - avoid abbreviations and mental mapping
Functions/methods: Use verbs (calculateTotal, getUserData)
Variables: Use nouns (userEmail, totalAmount)

3.3 Code Quality Standards

Architecture & Design

Follow SOLID principles
Prefer composition over inheritance
Use dependency injection for testability
Design for failure - assume things will break

Error Handling

Graceful Failure: Applications should never crash silently
Fail fast and fail clearly
Use specific exception types
Logging:
- Dev: Console logging
- Prod: Structured logging with correlation IDs in markdown format
- Log errors with context (what, when, why)
Notification: Critical errors must notify developer (Email/SMS)
Provide actionable error messages

Documentation

README.md for every project with setup instructions
Inline comments for complex business logic only (WHY, not WHAT)
API documentation for all public interfaces
Keep documentation close to code (avoid separate wikis)
Architecture Decisions: Document in Obsidian knowledge base as ADRs
Maintain single source of truth for architectural decisions

3.4 Documentation Standards

Project Documentation

README.md: Setup, deployment, and contribution guidelines for every project
docs/Lessons.md: Capture learnings from development process
- Document when AI or human struggles to produce results
- Record solutions that worked well
- Note patterns to avoid
- Purpose: Make future development more effective and efficient

Code Documentation

Inline Comments: Only for complex business logic (explain WHY, not WHAT)
API Documentation: Generate from OpenAPI specifications for all endpoints
Component Stories: Use Storybook or similar for component documentation when appropriate

Architecture Documentation

ADRs (Architecture Decision Records): Document in Obsidian knowledge base
Tech Stack Decisions: Link to relevant business processes and rationale
Single Source of Truth: This Global-Dev-Rules.md for all development standards

3.5 Security Standards

Security First

Never commit secrets or credentials
Validate all inputs (client-side + server-side verification)
Use parameterized queries only (prevent SQL injection)
Follow principle of least privilege
Content Security Policy: Strict CSP headers
HTTPS: Enforce SSL/TLS everywhere
XSS Prevention: Escape all user content
CORS: Strict CORS policy configuration

Dependency Security

Regular CVE scanning: Use tools like uv audit, pip-audit, safety check, or snyk
Keep dependencies updated to patched versions
Automate security scanning in CI/CD pipeline
Balance security patches with stability (not bleeding-edge, but not stale)

3.6 Performance Standards

Core Web Vitals

LCP (Largest Contentful Paint): Optimize images, lazy loading, critical resource hints
FID (First Input Delay): Minimize JavaScript, defer non-critical scripts
CLS (Cumulative Layout Shift): Define image dimensions, avoid layout shifts
Target: All metrics in “Good” range (green)

Asset Optimization

Images: Use modern formats (WebP, AVIF), responsive images with proper dimensions
CSS: Critical CSS inline, defer non-critical styles
JavaScript: Code splitting, tree shaking, minimal bundles
Fonts: Font display swap, preload critical fonts

Caching Strategy

Static Assets: Long cache headers (1 year)
HTML: Short cache with ETags
API Responses: Appropriate cache based on content type
CDN: Leverage Cloudflare’s caching capabilities

3.7 Accessibility Standards

ARIA labels for interactive elements
Semantic HTML
Keyboard navigation support
Color contrast compliance (WCAG AA minimum)
Screen reader testing for critical flows

4. Version Control & Collaboration

Git Workflow

Commit Messages: Use conventional commits format
- feat:, fix:, docs:, refactor:, test:, chore:
Branching: Feature branches, no direct commits to main
Code Reviews: Required for all changes
Atomic Commits: One logical change per commit

AI-Assisted Workflow

Plan: Define objective and requirements clearly, incorporating insights from docs/Lessons.md
Generate: Use AI tools for boilerplate, refactoring, or implementations
Verify: ALWAYS review and test AI-generated code
Update docs/Lessons.md: Document useful learnings from dev process, especially when AI or human struggles to produce results, so future development efforts are more effective and efficient
Iterate: Refine based on testing and world-class standards

5. Testing & Quality Assurance

Testing Philosophy

Test behavior, not implementation
Unit tests for business logic
Integration tests for system boundaries
E2E tests for critical user paths
Aim for 80% coverage, focus on critical paths

Current Testing Tools

Unit Tests: Vitest for component and utility testing
E2E Tests: Playwright for user flow testing
Performance: Lighthouse CI for performance regression
Accessibility: Axe-core for automated a11y testing

Code Quality Tools

Linting: ESLint + Prettier for code consistency
Type Safety: TypeScript strict mode, Python type hints
Bundle Analysis: Analyze and optimize bundle size
Performance Budgets: Set and enforce performance budgets

6. Integration Patterns

Third-Party Services (Currently Using)

Email: Amazon SES via Sendy for bulk emails
Analytics: Plausible Analytics for privacy-first tracking
Forms: Web3Forms or Formspree for form handling
Payments: Stripe for payment processing
Search: Meilisearch for site search functionality

Automation Integration

Workflow Automation: Currently using n8n for data processing
Webhooks: Implement for real-time integrations
Cron Jobs: Server-side scheduling for maintenance tasks

7. Project Categories

7.1 System Utilities

Scripts and tools to automate tasks (Python/Bash)
Type hints for Python
Clear error handling and logging

7.2 Side Projects (Learning)

Speed > Perfection
Experiment freely with new technologies
Document learnings, not every detail

7.3 Production Apps & Sites

Quality, Testing, and Stability are paramount
Follow ALL standards in this document
Comprehensive testing required
Monitoring from day one
Proper backup strategy (automated, tested, documented)

8. Critical Reminders

Before Starting ANY Task

IF ANY TASK IS NOT VERY CLEAR OR ADDITIONAL INFORMATION IS NEEDED OR EVEN WOULD BE HELPFUL, ALWAYS ASK. IT IS MUCH MORE EFFECTIVE TO BE 100% CLEAR ON WHAT IS EXPECTED FROM THE START.

During Development

Follow naming conventions from this document and related naming systems
Never use hacks - find robust solutions
Review AI-generated code carefully
Write tests for critical paths
Document complex decisions

Before Deployment

Run security scans
Check performance metrics
Verify error monitoring is active
Test backup and restore procedures
Review secrets management

Document Version: 1.0.0
Last Updated: 2024
Single Source of Truth: This document supersedes all previous development guidelines