Consolidate AI documentation into .ai/ directory

- Create .ai/ directory as single source of truth for all AI docs - Organize by topic: core/, development/, patterns/, meta/ - Update CLAUDE.md to reference .ai/ files instead of embedding content - Remove 18KB of duplicated Laravel Boost guidelines from CLAUDE.md - Fix testing command descriptions (pest runs all tests, not just unit) - Standardize version numbers (Laravel 12.4.1, PHP 8.4.7, Tailwind 4.1.4) - Replace all .cursor/rules/*.mdc with single coolify-ai-docs.mdc reference - Delete dev_workflow.mdc (non-Coolify Task Master content) - Merge cursor_rules.mdc + self_improve.mdc into maintaining-docs.md - Update .AI_INSTRUCTIONS_SYNC.md to redirect to new location Benefits: - Single source of truth - no more duplication - Consistent versions across all documentation - Better organization by topic - Platform-agnostic .ai/ directory works for all AI tools - Reduced CLAUDE.md from 719 to ~320 lines - Clear cross-references between files
2026-04-17 17:21:04 +00:00 · 2025-11-18 14:58:59 +01:00
parent 375d8e79b4
commit 3f7c5fbdf9
22 changed files with 739 additions and 1311 deletions
--- a/.AI_INSTRUCTIONS_SYNC.md
+++ b/.AI_INSTRUCTIONS_SYNC.md
@@ -1,156 +1,41 @@
 # AI Instructions Synchronization Guide

-This document explains how AI instructions are organized and synchronized across different AI tools used with Coolify.
+**This file has moved!**

-## Overview
+All AI documentation and synchronization guidelines are now in the `.ai/` directory.

-Coolify maintains AI instructions in two parallel systems:
+## New Locations

-1. **CLAUDE.md** - For Claude Code (claude.ai/code)
-2. **.cursor/rules/** - For Cursor IDE and other AI assistants
+- **Sync Guide**: [.ai/meta/sync-guide.md](.ai/meta/sync-guide.md)
+- **Maintaining Docs**: [.ai/meta/maintaining-docs.md](.ai/meta/maintaining-docs.md)
+- **Documentation Hub**: [.ai/README.md](.ai/README.md)

-Both systems share core principles but are optimized for their respective workflows.
+## Quick Overview

-## 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
+All AI instructions are now organized in `.ai/` directory:

 ```
-/
-├── 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
+.ai/
+├── README.md                    # Navigation hub
+├── core/                        # Project information
+├── development/                 # Dev workflows
+├── patterns/                    # Code patterns
+└── meta/                       # Documentation guides
 ```

-## Recent Updates
+### For AI Assistants

-### 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
+- **Claude Code**: Use `CLAUDE.md` (references `.ai/` files)
+- **Cursor IDE**: Use `.cursor/rules/coolify-ai-docs.mdc` (references `.ai/` files)
+- **All Tools**: Browse `.ai/` directory for detailed documentation

-## Maintenance Commands
+### Key Principles

-```bash
-# Check for version inconsistencies
-grep -r "Laravel [0-9]" CLAUDE.md .cursor/rules/*.mdc
+1. **Single Source of Truth**: Each piece of information exists in ONE file only
+2. **Cross-Reference**: Other files reference the source, don't duplicate
+3. **Organized by Topic**: Core, Development, Patterns, Meta
+4. **Version Consistency**: All versions in `.ai/core/technology-stack.md`

-# Check for PHP version consistency
-grep -r "PHP [0-9]" CLAUDE.md .cursor/rules/*.mdc
+## For More Information

-# 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.
+See [.ai/meta/sync-guide.md](.ai/meta/sync-guide.md) for complete synchronization guidelines and [.ai/meta/maintaining-docs.md](.ai/meta/maintaining-docs.md) for documentation maintenance instructions.