docs: add comprehensive AI assistant integration guide
- Create AGENT.md with detailed guide for OpenCode, Gemini CLI, and Claude usage - Document AI-assisted packaging workflow and best practices - Include prompt templates and context sharing strategies - Add symbolic links GEMINI.md and CLAUDE.md for easy access - Update README.md to reference AI assistant documentation AI Integration Features: - Phase-specific assistant recommendations (Research→Gemini, Development→Claude, etc.) - Template-driven development with AI assistance - Quality assurance workflows with AI review - Multi-assistant collaborative approaches This establishes AI-first development approach for the 56-application packaging initiative, significantly accelerating development while maintaining quality standards. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
292
AGENT.md
Normal file
292
AGENT.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# AI Coding Assistants for Cloudron Packaging
|
||||
|
||||
This document outlines how to effectively use AI coding assistants (OpenCode, Gemini CLI, Claude) for developing Cloudron packages in this project.
|
||||
|
||||
## 🤖 Available AI Assistants
|
||||
|
||||
### OpenCode
|
||||
- **Purpose**: Local development assistance and code generation
|
||||
- **Strengths**: Fast local responses, code completion, refactoring
|
||||
- **Use Cases**: Writing Dockerfiles, bash scripts, configuration files
|
||||
|
||||
### Gemini CLI
|
||||
- **Purpose**: Google's AI assistant via command line
|
||||
- **Strengths**: Research, documentation analysis, multi-modal capabilities
|
||||
- **Use Cases**: Understanding upstream applications, generating documentation
|
||||
|
||||
### Claude (Claude Code)
|
||||
- **Purpose**: Advanced reasoning and systematic development
|
||||
- **Strengths**: Complex problem solving, architectural decisions, comprehensive analysis
|
||||
- **Use Cases**: Complete package development, workflow design, troubleshooting
|
||||
|
||||
## 📋 Packaging Workflow with AI Assistants
|
||||
|
||||
### Phase 1: Research & Planning
|
||||
**Best Assistant**: Gemini CLI or Claude
|
||||
```bash
|
||||
# Use Gemini to research application requirements
|
||||
gemini "Analyze the requirements and architecture of [ApplicationName] for containerization"
|
||||
|
||||
# Use Claude for systematic analysis
|
||||
claude "Research [ApplicationName] and create a packaging plan including dependencies, configuration, and Cloudron integration requirements"
|
||||
```
|
||||
|
||||
**Key Questions to Ask**:
|
||||
- What are the system dependencies?
|
||||
- What databases or services are required?
|
||||
- What ports and networking are needed?
|
||||
- What are the security considerations?
|
||||
- What configuration files need customization?
|
||||
|
||||
### Phase 2: Package Development
|
||||
**Best Assistant**: Claude Code or OpenCode
|
||||
|
||||
#### CloudronManifest.json Creation
|
||||
```bash
|
||||
claude "Create a CloudronManifest.json for [ApplicationName] with these requirements: [list requirements]"
|
||||
```
|
||||
|
||||
#### Dockerfile Development
|
||||
```bash
|
||||
opencode "Generate a Dockerfile for [ApplicationName] using cloudron/base:4.2.0 that installs [dependencies] and follows Cloudron conventions"
|
||||
```
|
||||
|
||||
#### Startup Script Creation
|
||||
```bash
|
||||
claude "Create a start.sh script for [ApplicationName] that handles Cloudron addon integration, initialization, and proper error handling"
|
||||
```
|
||||
|
||||
### Phase 3: Configuration & Integration
|
||||
**Best Assistant**: Claude Code
|
||||
|
||||
```bash
|
||||
claude "Help me integrate [ApplicationName] with Cloudron's PostgreSQL and Redis addons, including proper environment variable handling"
|
||||
```
|
||||
|
||||
### Phase 4: Documentation & Validation
|
||||
**Best Assistant**: Any assistant
|
||||
|
||||
```bash
|
||||
gemini "Generate comprehensive build notes for this [ApplicationName] Cloudron package"
|
||||
```
|
||||
|
||||
## 🛠️ Assistant-Specific Usage Patterns
|
||||
|
||||
### OpenCode Usage
|
||||
Best for rapid iteration and code completion:
|
||||
|
||||
```bash
|
||||
# Quick Dockerfile generation
|
||||
opencode "Create Dockerfile for Node.js app with nginx proxy"
|
||||
|
||||
# Configuration file templates
|
||||
opencode "Generate nginx.conf for Cloudron app on port 8080"
|
||||
|
||||
# Script snippets
|
||||
opencode "Write bash function to check if PostgreSQL is ready"
|
||||
```
|
||||
|
||||
### Gemini CLI Usage
|
||||
Best for research and analysis:
|
||||
|
||||
```bash
|
||||
# Application research
|
||||
gemini "What are the key components and dependencies of Apache APISIX?"
|
||||
|
||||
# Documentation analysis
|
||||
gemini "Analyze this README.md and extract installation requirements"
|
||||
|
||||
# Troubleshooting
|
||||
gemini "Explain this Docker build error: [paste error]"
|
||||
```
|
||||
|
||||
### Claude Usage
|
||||
Best for comprehensive development:
|
||||
|
||||
```bash
|
||||
# Complete package development
|
||||
claude "Package [ApplicationName] for Cloudron following our established patterns"
|
||||
|
||||
# Complex problem solving
|
||||
claude "Debug this Cloudron package that fails to start properly"
|
||||
|
||||
# Architectural guidance
|
||||
claude "Design the optimal approach for packaging this multi-service application"
|
||||
```
|
||||
|
||||
## 📚 AI Assistant Integration with Our Workflow
|
||||
|
||||
### Template-Driven Development
|
||||
Each assistant can use our package template:
|
||||
|
||||
```bash
|
||||
# Share the template with any assistant
|
||||
claude "Use the template in CloudronPackages/PackageTemplate/CloudronPackagePrompt.md to package [ApplicationName]"
|
||||
|
||||
gemini "Based on our packaging template, what specific considerations apply to [ApplicationName]?"
|
||||
```
|
||||
|
||||
### Quality Assurance with AI
|
||||
Before merging to integration:
|
||||
|
||||
```bash
|
||||
# Code review
|
||||
claude "Review this Cloudron package for security issues, best practices, and completeness"
|
||||
|
||||
# Documentation review
|
||||
gemini "Check this build documentation for completeness and clarity"
|
||||
|
||||
# Testing guidance
|
||||
opencode "Generate test commands to validate this Cloudron package"
|
||||
```
|
||||
|
||||
## 🔄 Multi-Assistant Workflow
|
||||
|
||||
### Collaborative Approach
|
||||
1. **Gemini**: Research application and requirements
|
||||
2. **Claude**: Develop complete package structure
|
||||
3. **OpenCode**: Refine and optimize code
|
||||
4. **Claude**: Final review and documentation
|
||||
|
||||
### Context Sharing
|
||||
When switching between assistants, provide:
|
||||
|
||||
```markdown
|
||||
## Context
|
||||
- Application: [Name]
|
||||
- Progress: [Current phase]
|
||||
- Requirements: [List key requirements]
|
||||
- Issues: [Any current blockers]
|
||||
- Files: [List relevant files created]
|
||||
```
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
### Prompt Engineering for Packaging
|
||||
Always include in prompts:
|
||||
- **Target Platform**: "for Cloudron deployment"
|
||||
- **Base Image**: "using cloudron/base:4.2.0"
|
||||
- **Conventions**: "following our established patterns"
|
||||
- **Quality Standards**: "with proper error handling and logging"
|
||||
|
||||
### Version Control Integration
|
||||
Document AI assistance in commits:
|
||||
```bash
|
||||
git commit -m "feat(app): add Cloudron package
|
||||
|
||||
Generated with assistance from Claude Code for package structure
|
||||
and Gemini CLI for application research.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.ai/code)
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
### Quality Gates with AI
|
||||
Before each phase:
|
||||
- [ ] Ask AI to validate requirements understanding
|
||||
- [ ] Request security review of generated code
|
||||
- [ ] Verify Cloudron convention compliance
|
||||
- [ ] Generate test procedures
|
||||
|
||||
## 🔧 Assistant Configuration
|
||||
|
||||
### Environment Setup
|
||||
```bash
|
||||
# Ensure all assistants are available
|
||||
which opencode gemini claude
|
||||
|
||||
# Set up consistent workspace
|
||||
export CLOUDRON_PROJECT_ROOT=$(pwd)
|
||||
export PACKAGING_CONTAINER="tsys-cloudron-packaging"
|
||||
```
|
||||
|
||||
### Context Files
|
||||
Create context files for each assistant:
|
||||
|
||||
**`.ai-context/project-context.md`**:
|
||||
```markdown
|
||||
# KNEL Cloudron Packaging Project
|
||||
- Goal: Package 56 applications for Cloudron
|
||||
- Current Phase: [update as needed]
|
||||
- Standards: cloudron/base:4.2.0, proper addon integration
|
||||
- Workflow: feature → integration → main (PR required)
|
||||
```
|
||||
|
||||
## 📊 AI Assistant Effectiveness Metrics
|
||||
|
||||
### Development Velocity
|
||||
- **Time per Package**: Track packaging time with/without AI assistance
|
||||
- **Error Reduction**: Monitor build failures and fixes
|
||||
- **Quality Consistency**: Measure compliance with standards
|
||||
|
||||
### Learning and Improvement
|
||||
- Document which assistant works best for different tasks
|
||||
- Build prompt libraries for common packaging scenarios
|
||||
- Share effective prompt patterns across the team
|
||||
|
||||
## 🚨 Limitations and Considerations
|
||||
|
||||
### Security Review Required
|
||||
- Never trust AI-generated secrets or credentials
|
||||
- Always review security configurations manually
|
||||
- Validate network configurations and exposure
|
||||
|
||||
### Testing Still Essential
|
||||
- AI cannot replace actual testing
|
||||
- Build and deploy every package manually
|
||||
- Verify functionality beyond basic container startup
|
||||
|
||||
### Context Limitations
|
||||
- Assistants may not understand latest Cloudron changes
|
||||
- Always verify against official Cloudron documentation
|
||||
- Update assistant knowledge with project-specific patterns
|
||||
|
||||
## 🎓 Learning Resources
|
||||
|
||||
### Improving AI Interactions
|
||||
- Study effective prompt engineering techniques
|
||||
- Learn to provide clear context and constraints
|
||||
- Practice iterative refinement of AI outputs
|
||||
|
||||
### Cloudron-Specific Prompts
|
||||
Build a library of proven prompts:
|
||||
- Application analysis prompts
|
||||
- Package generation templates
|
||||
- Troubleshooting scenarios
|
||||
- Documentation generation patterns
|
||||
|
||||
---
|
||||
|
||||
## 📝 Quick Reference
|
||||
|
||||
### Common Commands
|
||||
```bash
|
||||
# Research phase
|
||||
gemini "Analyze [app] for Cloudron packaging"
|
||||
|
||||
# Development phase
|
||||
claude "Create complete Cloudron package for [app]"
|
||||
|
||||
# Optimization phase
|
||||
opencode "Optimize this Dockerfile for size and security"
|
||||
|
||||
# Review phase
|
||||
claude "Review this package for production readiness"
|
||||
```
|
||||
|
||||
### Context Sharing Template
|
||||
```markdown
|
||||
## AI Assistant Context
|
||||
- **Application**: [name]
|
||||
- **Current Task**: [specific task]
|
||||
- **Requirements**: [list]
|
||||
- **Previous Work**: [what's already done]
|
||||
- **Constraints**: [any limitations]
|
||||
- **Expected Output**: [what you need]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-04
|
||||
**Maintained By**: KNEL/TSYS Development Team
|
||||
**Part of**: [KNEL Production Containers](README.md) packaging project
|
||||
@@ -168,6 +168,12 @@ Each Cloudron package requires:
|
||||
- **Mounted**: Repository at `/workspace`
|
||||
- **Persistent**: Survives across development sessions
|
||||
|
||||
### AI Coding Assistants
|
||||
- **[AGENT.md](AGENT.md)**: Comprehensive guide for using OpenCode, Gemini CLI, and Claude
|
||||
- **[GEMINI.md](GEMINI.md)**: → Symbolic link to AGENT.md
|
||||
- **[CLAUDE.md](CLAUDE.md)**: → Symbolic link to AGENT.md
|
||||
- **Usage**: Accelerate development with AI-assisted packaging
|
||||
|
||||
### Helper Scripts
|
||||
- **`UpstreamVendor-Clone.sh`**: Clone all upstream repositories
|
||||
- **`UpstreamVendor-Update.sh`**: Update existing checkouts
|
||||
|
||||
Reference in New Issue
Block a user