From 70d0ae2b3304ec745fc03b22efdc6a84657c5385 Mon Sep 17 00:00:00 2001
From: Andras Bacsai <5845193+andrasbacsai@users.noreply.github.com>
Date: Tue, 7 Oct 2025 12:52:52 +0200
Subject: [PATCH] docs(sync): create AI Instructions Synchronization Guide and
 update CLAUDE.md references

- Added a new document, `.AI_INSTRUCTIONS_SYNC.md`, detailing the organization and synchronization of AI instructions across CLAUDE.md and .cursor/rules/.
- Updated CLAUDE.md to include a note for AI assistants directing them to the new synchronization guide and emphasizing the importance of maintaining consistency.
- Enhanced `.cursor/rules/cursor_rules.mdc`, `README.mdc`, and other related files with cross-references to the synchronization guide for better clarity on maintaining documentation consistency.
---
 .AI_INSTRUCTIONS_SYNC.md           | 156 +++++++++++++++++++++++++++++
 .cursor/rules/README.mdc           |   6 +-
 .cursor/rules/cursor_rules.mdc     |   6 ++
 .cursor/rules/laravel-boost.mdc    |   2 +-
 .cursor/rules/testing-patterns.mdc |   2 +
 CLAUDE.md                          |  12 ++-
 6 files changed, 179 insertions(+), 5 deletions(-)
 create mode 100644 .AI_INSTRUCTIONS_SYNC.md

diff --git a/.AI_INSTRUCTIONS_SYNC.md b/.AI_INSTRUCTIONS_SYNC.md
new file mode 100644
index 000000000..bbe0a90e1
--- /dev/null
+++ b/.AI_INSTRUCTIONS_SYNC.md
@@ -0,0 +1,156 @@
+# AI Instructions Synchronization Guide
+
+This document explains how AI instructions are organized and synchronized across different AI tools used with Coolify.
+
+## Overview
+
+Coolify maintains AI instructions in two parallel systems:
+
+1. **CLAUDE.md** - For Claude Code (claude.ai/code)
+2. **.cursor/rules/** - For Cursor IDE and other AI assistants
+
+Both systems share core principles but are optimized for their respective workflows.
+
+## Structure
+
+### CLAUDE.md
+- **Purpose**: Condensed, workflow-focused guide for Claude Code
+- **Format**: Single markdown file
+- **Includes**:
+  - Quick-reference development commands
+  - High-level architecture overview
+  - Core patterns and guidelines
+  - Embedded Laravel Boost guidelines
+  - References to detailed .cursor/rules/ documentation
+
+### .cursor/rules/
+- **Purpose**: Detailed, topic-specific documentation
+- **Format**: Multiple .mdc files organized by topic
+- **Structure**:
+  - `README.mdc` - Main index and overview
+  - `cursor_rules.mdc` - Maintenance guidelines
+  - Topic-specific files (testing-patterns.mdc, security-patterns.mdc, etc.)
+- **Used by**: Cursor IDE, Claude Code (for detailed reference), other AI assistants
+
+## Cross-References
+
+Both systems reference each other:
+
+- **CLAUDE.md** → references `.cursor/rules/` for detailed documentation
+- **.cursor/rules/README.mdc** → references `CLAUDE.md` for Claude Code workflow
+- **.cursor/rules/cursor_rules.mdc** → notes that changes should sync with CLAUDE.md
+
+## Maintaining Consistency
+
+When updating AI instructions, follow these guidelines:
+
+### 1. Core Principles (MUST be consistent)
+- Laravel version (currently Laravel 12)
+- PHP version (8.4)
+- Testing execution rules (Docker for Feature tests, mocking for Unit tests)
+- Security patterns and authorization requirements
+- Code style requirements (Pint, PSR-12)
+
+### 2. Where to Make Changes
+
+**For workflow changes** (how to run commands, development setup):
+- Primary: `CLAUDE.md`
+- Secondary: `.cursor/rules/development-workflow.mdc`
+
+**For architectural patterns** (how code should be structured):
+- Primary: `.cursor/rules/` topic files
+- Secondary: Reference in `CLAUDE.md` "Additional Documentation" section
+
+**For testing patterns**:
+- Both: Must be synchronized
+- `CLAUDE.md` - Contains condensed testing execution rules
+- `.cursor/rules/testing-patterns.mdc` - Contains detailed examples and patterns
+
+### 3. Update Checklist
+
+When making significant changes:
+
+- [ ] Identify if change affects core principles (version numbers, critical patterns)
+- [ ] Update primary location (CLAUDE.md or .cursor/rules/)
+- [ ] Check if update affects cross-referenced content
+- [ ] Update secondary location if needed
+- [ ] Verify cross-references are still accurate
+- [ ] Run: `./vendor/bin/pint CLAUDE.md .cursor/rules/*.mdc` (if applicable)
+
+### 4. Common Inconsistencies to Watch
+
+- **Version numbers**: Laravel, PHP, package versions
+- **Testing instructions**: Docker execution requirements
+- **File paths**: Ensure relative paths work from root
+- **Command syntax**: Docker commands, artisan commands
+- **Architecture decisions**: Laravel 10 structure vs Laravel 12+ structure
+
+## File Organization
+
+```
+/
+├── CLAUDE.md                          # Claude Code instructions (condensed)
+├── .AI_INSTRUCTIONS_SYNC.md          # This file
+└── .cursor/
+    └── rules/
+        ├── README.mdc                 # Index and overview
+        ├── cursor_rules.mdc           # Maintenance guide
+        ├── testing-patterns.mdc       # Testing details
+        ├── development-workflow.mdc   # Dev setup details
+        ├── security-patterns.mdc      # Security details
+        ├── application-architecture.mdc
+        ├── deployment-architecture.mdc
+        ├── database-patterns.mdc
+        ├── frontend-patterns.mdc
+        ├── api-and-routing.mdc
+        ├── form-components.mdc
+        ├── technology-stack.mdc
+        ├── project-overview.mdc
+        └── laravel-boost.mdc          # Laravel-specific patterns
+```
+
+## Recent Updates
+
+### 2025-10-07
+- ✅ Added cross-references between CLAUDE.md and .cursor/rules/
+- ✅ Synchronized Laravel version (12) across all files
+- ✅ Added comprehensive testing execution rules (Docker for Feature tests)
+- ✅ Added test design philosophy (prefer mocking over database)
+- ✅ Fixed inconsistencies in testing documentation
+- ✅ Created this synchronization guide
+
+## Maintenance Commands
+
+```bash
+# Check for version inconsistencies
+grep -r "Laravel [0-9]" CLAUDE.md .cursor/rules/*.mdc
+
+# Check for PHP version consistency
+grep -r "PHP [0-9]" CLAUDE.md .cursor/rules/*.mdc
+
+# Format all documentation
+./vendor/bin/pint CLAUDE.md .cursor/rules/*.mdc
+
+# Search for specific patterns across all docs
+grep -r "pattern_to_check" CLAUDE.md .cursor/rules/
+```
+
+## Contributing
+
+When contributing documentation:
+
+1. Check both CLAUDE.md and .cursor/rules/ for existing documentation
+2. Add to appropriate location(s) based on guidelines above
+3. Add cross-references if creating new patterns
+4. Update this file if changing organizational structure
+5. Verify consistency before submitting PR
+
+## Questions?
+
+If unsure about where to document something:
+
+- **Quick reference / workflow** → CLAUDE.md
+- **Detailed patterns / examples** → .cursor/rules/[topic].mdc
+- **Both?** → Start with .cursor/rules/, then reference in CLAUDE.md
+
+When in doubt, prefer detailed documentation in .cursor/rules/ and concise references in CLAUDE.md.
diff --git a/.cursor/rules/README.mdc b/.cursor/rules/README.mdc
index 07f19a816..d0597bb72 100644
--- a/.cursor/rules/README.mdc
+++ b/.cursor/rules/README.mdc
@@ -9,6 +9,10 @@ alwaysApply: false
 
 This comprehensive set of Cursor Rules provides deep insights into **Coolify**, an open-source self-hostable alternative to Heroku/Netlify/Vercel. These rules will help you understand, navigate, and contribute to this complex Laravel-based deployment platform.
 
+> **Cross-Reference**: This directory is for **detailed, topic-specific rules** used by Cursor IDE and other AI assistants. For Claude Code specifically, also see **[CLAUDE.md](mdc:CLAUDE.md)** which provides a condensed, workflow-focused guide. Both systems share core principles but are optimized for their respective tools.
+>
+> **Maintaining Rules**: When updating these rules, see **[.AI_INSTRUCTIONS_SYNC.md](mdc:.AI_INSTRUCTIONS_SYNC.md)** for synchronization guidelines to keep CLAUDE.md and .cursor/rules/ consistent.
+
 ## Rule Categories
 
 ### 🏗️ Architecture & Foundation
@@ -71,7 +75,7 @@ Coolify uses a **team-based multi-tenancy** model where:
 - **Multi-server** support with SSH connections
 
 ### 3. Technology Stack
-- **Backend**: Laravel 11 + PHP 8.4
+- **Backend**: Laravel 12 + PHP 8.4
 - **Frontend**: Livewire 3.5 + Alpine.js + Tailwind CSS 4.1
 - **Database**: PostgreSQL 15 + Redis 7
 - **Containerization**: Docker + Docker Compose
diff --git a/.cursor/rules/cursor_rules.mdc b/.cursor/rules/cursor_rules.mdc
index 7dfae3de0..9edccd496 100644
--- a/.cursor/rules/cursor_rules.mdc
+++ b/.cursor/rules/cursor_rules.mdc
@@ -4,6 +4,12 @@ globs: .cursor/rules/*.mdc
 alwaysApply: true
 ---
 
+# Cursor Rules Maintenance Guide
+
+> **Important**: These rules in `.cursor/rules/` are shared between Cursor IDE and other AI assistants. Changes here should be reflected in **[CLAUDE.md](mdc:CLAUDE.md)** when they affect core workflows or patterns.
+>
+> **Synchronization Guide**: See **[.AI_INSTRUCTIONS_SYNC.md](mdc:.AI_INSTRUCTIONS_SYNC.md)** for detailed guidelines on maintaining consistency between CLAUDE.md and .cursor/rules/.
+
 - **Required Rule Structure:**
   ```markdown
   ---
diff --git a/.cursor/rules/laravel-boost.mdc b/.cursor/rules/laravel-boost.mdc
index 005ede849..c409a4647 100644
--- a/.cursor/rules/laravel-boost.mdc
+++ b/.cursor/rules/laravel-boost.mdc
@@ -185,7 +185,7 @@ protected function isAccessible(User $user, ?string $path = null): bool
 
 ### Database
 - When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.
-- Laravel 11 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
+- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
 
 ### Models
 - Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models.
diff --git a/.cursor/rules/testing-patterns.mdc b/.cursor/rules/testing-patterns.mdc
index 38bebc700..f2133c0ac 100644
--- a/.cursor/rules/testing-patterns.mdc
+++ b/.cursor/rules/testing-patterns.mdc
@@ -5,6 +5,8 @@ alwaysApply: false
 ---
 # Coolify Testing Architecture & Patterns
 
+> **Cross-Reference**: These detailed testing patterns align with the testing guidelines in **[CLAUDE.md](mdc:CLAUDE.md)**. Both documents share the same core principles about Docker execution and mocking preferences.
+
 ## Testing Philosophy
 
 Coolify employs **comprehensive testing strategies** using modern PHP testing frameworks to ensure reliability of deployment operations, infrastructure management, and user interactions.
diff --git a/CLAUDE.md b/CLAUDE.md
index eafcd97f6..b190a9c05 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,10 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to **Claude Code** (claude.ai/code) when working with code in this repository.
+
+> **Note for AI Assistants**: This file is specifically for Claude Code. If you're using Cursor IDE, refer to the `.cursor/rules/` directory for detailed rule files. Both systems share core principles but are optimized for their respective workflows.
+>
+> **Maintaining Instructions**: When updating AI instructions, see [.AI_INSTRUCTIONS_SYNC.md](.AI_INSTRUCTIONS_SYNC.md) for synchronization guidelines between CLAUDE.md and .cursor/rules/.
 
 ## Project Overview
 
@@ -250,7 +254,9 @@ ## Important Reminders
 
 ## Additional Documentation
 
-For more detailed guidelines and patterns, refer to the `.cursor/rules/` directory:
+This file contains high-level guidelines for Claude Code. For **more detailed, topic-specific documentation**, refer to the `.cursor/rules/` directory (also accessible by Cursor IDE and other AI assistants):
+
+> **Cross-Reference**: The `.cursor/rules/` directory contains comprehensive, detailed documentation organized by topic. Start with [.cursor/rules/README.mdc](.cursor/rules/README.mdc) for an overview, then explore specific topics below.
 
 ### Architecture & Patterns
 - [Application Architecture](.cursor/rules/application-architecture.mdc) - Detailed application structure
@@ -456,7 +462,7 @@ ### Laravel 10 Structure
 
 ### Database
 - When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.
-- Laravel 11 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
+- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
 
 ### Models
 - Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models.