tiennm99/coolify
1
0
Fork 0
mirror of https://github.com/tiennm99/coolify.git synced 2026-04-17 17:21:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: consolidate AI documentation into .ai/ directory

Browse Source 
- Update CLAUDE.md to reference .ai/ directory as single source of truth
- Move documentation structure to organized .ai/ directory with core/, development/, patterns/, meta/ subdirectories
- Update .ai/README.md with correct path references
- Update .ai/meta/maintaining-docs.md to reflect new structure
- Consolidate sync-guide.md with detailed synchronization rules
- Fix cross-reference in frontend-patterns.md

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Andras Bacsai
2025-11-18 17:28:56 +01:00
parent 3f7c5fbdf9
commit 76e93806bf
4 changed files with 139 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.ai/README.md
View File

@@ -4,7 +4,7 @@ Welcome to the Coolify AI documentation hub. This directory contains all AI assi
## Quick Start ## Quick Start
- **For Claude Code**: Start with [CLAUDE.md](CLAUDE.md) - **For Claude Code**: Start with [CLAUDE.md in root directory](../CLAUDE.md)
- **For Cursor IDE**: Check `.cursor/rules/coolify-ai-docs.mdc` which references this directory - **For Cursor IDE**: Check `.cursor/rules/coolify-ai-docs.mdc` which references this directory
- **For Other AI Tools**: Continue reading below - **For Other AI Tools**: Continue reading below
@@ -92,7 +92,7 @@ Documentation about documentation:
## Navigation Tips ## Navigation Tips
1. **Start broad**: Begin with project-overview or CLAUDE.md 1. **Start broad**: Begin with project-overview or ../CLAUDE.md
2. **Get specific**: Navigate to topic-specific files for details 2. **Get specific**: Navigate to topic-specific files for details
3. **Cross-reference**: Files link to related topics 3. **Cross-reference**: Files link to related topics
4. **Single source**: Version numbers and critical data exist in ONE place only 4. **Single source**: Version numbers and critical data exist in ONE place only
@@ -135,7 +135,7 @@ When updating documentation:
## Questions? ## Questions?
- **Claude Code users**: Check [CLAUDE.md](CLAUDE.md) first - **Claude Code users**: Check [../CLAUDE.md](../CLAUDE.md) first
- **Cursor IDE users**: Check `.cursor/rules/coolify-ai-docs.mdc` - **Cursor IDE users**: Check `.cursor/rules/coolify-ai-docs.mdc`
- **Documentation issues**: See [meta/maintaining-docs.md](meta/maintaining-docs.md) - **Documentation issues**: See [meta/maintaining-docs.md](meta/maintaining-docs.md)
- **Sync issues**: See [meta/sync-guide.md](meta/sync-guide.md) - **Sync issues**: See [meta/sync-guide.md](meta/sync-guide.md)

3
.ai/meta/maintaining-docs.md
View File

@@ -9,13 +9,14 @@ All AI documentation lives in the `.ai/` directory with the following structure:
``` ```
.ai/ .ai/
├── README.md # Navigation hub ├── README.md # Navigation hub
├── CLAUDE.md # Main Claude Code instructions
├── core/ # Core project information ├── core/ # Core project information
├── development/ # Development practices ├── development/ # Development practices
├── patterns/ # Code patterns and best practices ├── patterns/ # Code patterns and best practices
└── meta/ # Documentation maintenance guides └── meta/ # Documentation maintenance guides
``` ```
> **Note**: `CLAUDE.md` is in the repository root, not in the `.ai/` directory.
## Required File Structure ## Required File Structure
When creating new documentation files: When creating new documentation files:

208
.ai/meta/sync-guide.md
View File

@@ -4,153 +4,211 @@ This document explains how AI instructions are organized and synchronized across
## Overview ## Overview
Coolify maintains AI instructions in two parallel systems: Coolify maintains AI instructions with a **single source of truth** approach:
1. **CLAUDE.md** - For Claude Code (claude.ai/code) 1. **CLAUDE.md** - Main entry point for Claude Code (references `.ai/` directory)
2. **.cursor/rules/** - For Cursor IDE and other AI assistants 2. **.cursor/rules/coolify-ai-docs.mdc** - Master reference file for Cursor IDE (references `.ai/` directory)
3. **.ai/** - Single source of truth containing all detailed documentation
Both systems share core principles but are optimized for their respective workflows. All AI tools (Claude Code, Cursor IDE, etc.) reference the same `.ai/` directory to ensure consistency.
## Structure ## Structure
### CLAUDE.md ### CLAUDE.md (Root Directory)
- **Purpose**: Condensed, workflow-focused guide for Claude Code - **Purpose**: Entry point for Claude Code with quick-reference guide
- **Format**: Single markdown file - **Format**: Single markdown file
- **Includes**: - **Includes**:
- Quick-reference development commands - Quick-reference development commands
- High-level architecture overview - High-level architecture overview
- Core patterns and guidelines - Essential patterns and guidelines
- Embedded Laravel Boost guidelines - References to detailed `.ai/` documentation
- References to detailed .cursor/rules/ documentation
### .cursor/rules/ ### .cursor/rules/coolify-ai-docs.mdc
- **Purpose**: Detailed, topic-specific documentation - **Purpose**: Master reference file for Cursor IDE
- **Format**: Multiple .mdc files organized by topic - **Format**: Single .mdc file with frontmatter
- **Content**: Quick decision tree and references to `.ai/` directory
- **Note**: Replaces all previous topic-specific .mdc files
### .ai/ Directory (Single Source of Truth)
- **Purpose**: All detailed, topic-specific documentation
- **Format**: Organized markdown files by category
- **Structure**: - **Structure**:
- `README.mdc` - Main index and overview ```
- `cursor_rules.mdc` - Maintenance guidelines .ai/
- Topic-specific files (testing-patterns.mdc, security-patterns.mdc, etc.) ├── README.md # Navigation hub
- **Used by**: Cursor IDE, Claude Code (for detailed reference), other AI assistants ├── core/ # Project information
│ ├── technology-stack.md # Version numbers (SINGLE SOURCE OF TRUTH)
│ ├── project-overview.md
│ ├── application-architecture.md
│ └── deployment-architecture.md
├── development/ # Development practices
│ ├── development-workflow.md
│ ├── testing-patterns.md
│ └── laravel-boost.md
├── patterns/ # Code patterns
│ ├── database-patterns.md
│ ├── frontend-patterns.md
│ ├── security-patterns.md
│ ├── form-components.md
│ └── api-and-routing.md
└── meta/ # Documentation guides
├── maintaining-docs.md
└── sync-guide.md (this file)
```
- **Used by**: All AI tools through CLAUDE.md or coolify-ai-docs.mdc
## Cross-References ## Cross-References
Both systems reference each other: All systems reference the `.ai/` directory as the source of truth:
- **CLAUDE.md** → references `.cursor/rules/` for detailed documentation - **CLAUDE.md** → references `.ai/` files for detailed documentation
- **.cursor/rules/README.mdc** → references `CLAUDE.md` for Claude Code workflow - **.cursor/rules/coolify-ai-docs.mdc** → references `.ai/` files for detailed documentation
- **.cursor/rules/cursor_rules.mdc** → notes that changes should sync with CLAUDE.md - **.ai/README.md** → provides navigation to all documentation
## Maintaining Consistency ## Maintaining Consistency
When updating AI instructions, follow these guidelines:
### 1. Core Principles (MUST be consistent) ### 1. Core Principles (MUST be consistent)
- Laravel version (currently Laravel 12)
- PHP version (8.4) These are defined ONCE in `.ai/core/technology-stack.md`:
- Laravel version (currently Laravel 12.4.1)
- PHP version (8.4.7)
- All package versions (Livewire 3.5.20, Tailwind 4.1.4, etc.)
**Exception**: CLAUDE.md is permitted to show essential version numbers as a quick reference for convenience. These must stay synchronized with `technology-stack.md`. When updating versions, update both locations.
Other critical patterns defined in `.ai/`:
- Testing execution rules (Docker for Feature tests, mocking for Unit tests) - Testing execution rules (Docker for Feature tests, mocking for Unit tests)
- Security patterns and authorization requirements - Security patterns and authorization requirements
- Code style requirements (Pint, PSR-12) - Code style requirements (Pint, PSR-12)
### 2. Where to Make Changes ### 2. Where to Make Changes
**For version numbers** (Laravel, PHP, packages):
1. Update `.ai/core/technology-stack.md` (single source of truth)
2. Update CLAUDE.md quick reference section (essential versions only)
3. Verify both files stay synchronized
4. Never duplicate version numbers in other locations
**For workflow changes** (how to run commands, development setup): **For workflow changes** (how to run commands, development setup):
- Primary: `CLAUDE.md` 1. Update `.ai/development/development-workflow.md`
- Secondary: `.cursor/rules/development-workflow.mdc` 2. Update quick reference in CLAUDE.md if needed
3. Verify `.cursor/rules/coolify-ai-docs.mdc` references are correct
**For architectural patterns** (how code should be structured): **For architectural patterns** (how code should be structured):
- Primary: `.cursor/rules/` topic files 1. Update appropriate file in `.ai/core/`
- Secondary: Reference in `CLAUDE.md` "Additional Documentation" section 2. Add cross-references from related docs
3. Update CLAUDE.md if it needs to highlight this pattern
**For code patterns** (how to write code):
1. Update appropriate file in `.ai/patterns/`
2. Add examples from real codebase
3. Cross-reference from related docs
**For testing patterns**: **For testing patterns**:
- Both: Must be synchronized 1. Update `.ai/development/testing-patterns.md`
- `CLAUDE.md` - Contains condensed testing execution rules 2. Ensure CLAUDE.md testing section references it
- `.cursor/rules/testing-patterns.mdc` - Contains detailed examples and patterns
### 3. Update Checklist ### 3. Update Checklist
When making significant changes: When making significant changes:
- [ ] Identify if change affects core principles (version numbers, critical patterns) - [ ] Identify if change affects core principles (version numbers, critical patterns)
- [ ] Update primary location (CLAUDE.md or .cursor/rules/) - [ ] Update primary location in `.ai/` directory
- [ ] Check if update affects cross-referenced content - [ ] Check if CLAUDE.md needs quick-reference update
- [ ] Update secondary location if needed - [ ] Verify `.cursor/rules/coolify-ai-docs.mdc` references are still accurate
- [ ] Verify cross-references are still accurate - [ ] Update cross-references in related `.ai/` files
- [ ] Run: `./vendor/bin/pint CLAUDE.md .cursor/rules/*.mdc` (if applicable) - [ ] Verify all relative paths work correctly
- [ ] Test links in markdown files
- [ ] Run: `./vendor/bin/pint` on modified files (if applicable)
### 4. Common Inconsistencies to Watch ### 4. Common Inconsistencies to Watch
- **Version numbers**: Laravel, PHP, package versions - **Version numbers**: Should ONLY exist in `.ai/core/technology-stack.md`
- **Testing instructions**: Docker execution requirements - **Testing instructions**: Docker execution requirements must be consistent
- **File paths**: Ensure relative paths work from root - **File paths**: Ensure relative paths work from their location
- **Command syntax**: Docker commands, artisan commands - **Command syntax**: Docker commands, artisan commands must be accurate
- **Architecture decisions**: Laravel 10 structure vs Laravel 12+ structure - **Cross-references**: Links must point to current file locations
## File Organization ## File Organization
``` ```
/ /
├── CLAUDE.md # Claude Code instructions (condensed) ├── CLAUDE.md # Claude Code entry point
├── .AI_INSTRUCTIONS_SYNC.md # This file ├── .AI_INSTRUCTIONS_SYNC.md # Redirect to this file
└── .cursor/ ├── .cursor/
└── rules/ │ └── rules/
├── README.mdc # Index and overview │ └── coolify-ai-docs.mdc # Cursor IDE master reference
├── cursor_rules.mdc # Maintenance guide └── .ai/ # SINGLE SOURCE OF TRUTH
├── testing-patterns.mdc # Testing details ├── README.md # Navigation hub
├── development-workflow.mdc # Dev setup details ├── core/ # Project information
├── security-patterns.mdc # Security details ├── development/ # Development practices
├── application-architecture.mdc ├── patterns/ # Code patterns
├── deployment-architecture.mdc └── meta/ # Documentation guides
├── 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 ## Recent Updates
### 2025-11-18 - Documentation Consolidation
- ✅ Consolidated all documentation into `.ai/` directory
- ✅ Created single source of truth for version numbers
- ✅ Reduced CLAUDE.md from 719 to 319 lines
- ✅ Replaced 11 .cursor/rules/*.mdc files with single coolify-ai-docs.mdc
- ✅ Organized by topic: core/, development/, patterns/, meta/
- ✅ Standardized version numbers (Laravel 12.4.1, PHP 8.4.7, Tailwind 4.1.4)
- ✅ Created comprehensive navigation with .ai/README.md
### 2025-10-07 ### 2025-10-07
- ✅ Added cross-references between CLAUDE.md and .cursor/rules/ - ✅ Added cross-references between CLAUDE.md and .cursor/rules/
- ✅ Synchronized Laravel version (12) across all files - ✅ Synchronized Laravel version (12) across all files
- ✅ Added comprehensive testing execution rules (Docker for Feature tests) - ✅ Added comprehensive testing execution rules (Docker for Feature tests)
- ✅ Added test design philosophy (prefer mocking over database) - ✅ Added test design philosophy (prefer mocking over database)
- ✅ Fixed inconsistencies in testing documentation - ✅ Fixed inconsistencies in testing documentation
- ✅ Created this synchronization guide
## Maintenance Commands ## Maintenance Commands
```bash ```bash
# Check for version inconsistencies # Check for version inconsistencies (should only be in technology-stack.md)
grep -r "Laravel [0-9]" CLAUDE.md .cursor/rules/*.mdc # Note: CLAUDE.md is allowed to show quick reference versions
grep -r "Laravel 12" .ai/ CLAUDE.md .cursor/rules/coolify-ai-docs.mdc
grep -r "PHP 8.4" .ai/ CLAUDE.md .cursor/rules/coolify-ai-docs.mdc
# Check for PHP version consistency # Check for broken cross-references to old .mdc files
grep -r "PHP [0-9]" CLAUDE.md .cursor/rules/*.mdc grep -r "\.cursor/rules/.*\.mdc" .ai/ CLAUDE.md
# Format all documentation # Format all documentation
./vendor/bin/pint CLAUDE.md .cursor/rules/*.mdc ./vendor/bin/pint CLAUDE.md .ai/**/*.md
# Search for specific patterns across all docs # Search for specific patterns across all docs
grep -r "pattern_to_check" CLAUDE.md .cursor/rules/ grep -r "pattern_to_check" CLAUDE.md .ai/ .cursor/rules/
# Verify all markdown links work (from repository root)
find .ai -name "*.md" -exec grep -H "\[.*\](.*)" {} \;
``` ```
## Contributing ## Contributing
When contributing documentation: When contributing documentation:
1. Check both CLAUDE.md and .cursor/rules/ for existing documentation 1. **Check `.ai/` directory** for existing documentation
2. Add to appropriate location(s) based on guidelines above 2. **Update `.ai/` files** - this is the single source of truth
3. Add cross-references if creating new patterns 3. **Use cross-references** - never duplicate content
4. Update this file if changing organizational structure 4. **Update CLAUDE.md** if adding critical quick-reference information
5. Verify consistency before submitting PR 5. **Verify `.cursor/rules/coolify-ai-docs.mdc`** still references correctly
6. **Test all links** work from their respective locations
7. **Update this sync-guide.md** if changing organizational structure
8. **Verify consistency** before submitting PR
## Questions? ## Questions?
If unsure about where to document something: If unsure about where to document something:
- **Quick reference / workflow** → CLAUDE.md - **Version numbers** → `.ai/core/technology-stack.md` (ONLY location)
- **Detailed patterns / examples** → .cursor/rules/[topic].mdc - **Quick reference / commands** → CLAUDE.md + `.ai/development/development-workflow.md`
- **Both?** → Start with .cursor/rules/, then reference in CLAUDE.md - **Detailed patterns / examples** → `.ai/patterns/[topic].md`
- **Architecture / concepts** → `.ai/core/[topic].md`
- **Development practices** → `.ai/development/[topic].md`
- **Documentation guides** → `.ai/meta/[topic].md`
When in doubt, prefer detailed documentation in .cursor/rules/ and concise references in CLAUDE.md. **Golden Rule**: Each piece of information exists in ONE location in `.ai/`, other files reference it.
When in doubt, prefer detailed documentation in `.ai/` and lightweight references in CLAUDE.md and coolify-ai-docs.mdc.

2
.ai/patterns/frontend-patterns.md
View File

@@ -258,7 +258,7 @@ public bool $autoDisable = true; // Automatically disable if no permission
- **Automatic disabling** for unauthorized users - **Automatic disabling** for unauthorized users
- **Smart behavior** (disables instantSave on checkboxes for unauthorized users) - **Smart behavior** (disables instantSave on checkboxes for unauthorized users)
For complete documentation, see **[form-components.mdc](mdc:.cursor/rules/form-components.mdc)** For complete documentation, see **[form-components.md](.ai/patterns/form-components.md)**
## Form Handling Patterns ## Form Handling Patterns