🤖 AI-Friendly Development¶

GRAB is designed from the ground up to work seamlessly with AI coding assistants, providing comprehensive guidelines that help AI understand the project structure, patterns, and best practices.

📋 Overview¶

GRAB includes out-of-the-box AI assistance for all major coding assistants:

• GitHub Copilot - Works in VS Code, JetBrains IDEs, Visual Studio, and more
• Cursor - Auto-loads rules with intelligent code completion
• Windsurf - Always-On assistance with project awareness
• JetBrains AI - Supports AGENTS.md standard
• Any AGENTS.md-compatible assistant - Universal compatibility

No configuration needed - just clone and start coding with intelligent AI suggestions tailored to GRAB's architecture.

🎯 What Makes GRAB AI-Friendly?¶

1. Comprehensive AI Guidelines¶

GRAB includes four types of AI configuration files:

2. Developer-Focused Content¶

All guidelines focus on using GRAB, not maintaining it:

• ✅ Adding new domains/entities (step-by-step)
• ✅ Creating database migrations
• ✅ Writing Clean Architecture code
• ✅ Testing patterns and coverage
• ✅ Authentication & authorization
• ✅ Error handling
• ✅ Swagger documentation
• ✅ Docker workflow

3. Pattern Recognition¶

AI assistants understand:

• Clean Architecture: Handler → Service → Repository
• Domain Structure: internal/<domain>/ with model, dto, repository, service, handler
• Migration Naming: YYYYMMDDHHMMSS_verb_noun_table
• Testing Conventions: Table-driven tests with mocks
• Error Handling: Centralized c.Error(apiErrors.FromGinValidation(err)) pattern with constructor functions
• Context Helpers: contextutil.GetUserID(), contextutil.GetEmail(), contextutil.GetRoles(), etc.

4. Documentation Integration¶

Every AI file links to comprehensive documentation:

• Authentication Guide
• RBAC Documentation
• Migrations Guide
• Testing Guide
• Configuration
• And more...

🚀 Getting Started¶

Prerequisites¶

Clone GRAB to your local machine:

git clone https://github.com/vahiiiid/go-rest-api-boilerplate.git
cd go-rest-api-boilerplate

IDE-Specific Setup¶

---
alwaysApply: true
---

# My Personal Rules

- Prefer `assert` over `require` in tests
- Use `context.TODO()` for examples
- Add TODO comments for future work

📊 IDE Comparison¶

Feature Matrix¶

| Feature | GitHub Copilot | Cursor | Windsurf | GoLand/IntelliJ | AGENTS.md | |---------|----------------|--------|----------|-----------------|-----------|-------| | Auto-loads | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes (both) | ✅ Yes | | File Path | .github/copilot-instructions.md | .cursor/rules/*.mdc | .windsurf/rules/*.md | Same as Copilot + AGENTS.md | AGENTS.md | | Configuration | None | YAML frontmatter | Markdown header | None | None | | Activation | Automatic | alwaysApply: true | "Always On" | Automatic | Automatic | | Content Length | 350+ lines | 180+ lines | 180+ lines | 350+ / 800+ lines | 800+ lines | | Scope | Developer-focused | Developer-focused | Developer-focused | Developer-focused + Universal | Universal | | Customization | N/A | Personal rules | Per-project | N/A | N/A | | IDE-Specific Files | ❌ No | ✅ Yes (.cursor/) | ✅ Yes (.windsurf/) | ❌ No | ❌ No |

File Structure Overview¶

go-rest-api-boilerplate/
├── .github/
│   └── copilot-instructions.md   # ← GitHub Copilot (VS Code, GoLand, etc.)
├── .cursor/
│   └── rules/
│       └── grab.mdc               # ← Cursor IDE only
├── .windsurf/
│   └── rules/
│       └── grab.md                # ← Windsurf IDE only
└── AGENTS.md                      # ← Universal (JetBrains AI, Amazon Q, etc.)

Key Differences¶

Why GoLand doesn't need dedicated files:

• GitHub Copilot in GoLand uses the same .github/copilot-instructions.md as VS Code
• JetBrains AI Assistant reads AGENTS.md (universal standard)
• No IDE-specific configuration directories required
• Works out-of-the-box after cloning the repository

💡 What AI Assistants Learn¶

When you use AI assistants with GRAB, they understand:

Architecture Patterns¶

// AI knows to create Handler → Service → Repository layers
internal/todo/
├── model.go       // GORM models
├── dto.go         // Request/Response DTOs
├── repository.go  // Database access
├── service.go     // Business logic
├── handler.go     // HTTP handlers
└── *_test.go      // Tests

Docker Workflow¶

# AI suggests Docker-first commands
make up           # AI knows containers auto-start
make test         # AI knows this runs in container
make migrate-up   # AI knows Makefile handles context

Migration Conventions¶

# AI generates correct migration names
make migrate-create NAME=create_todos_table
# Creates: 20251210143022_create_todos_table.up.sql

Clean Architecture Code¶

// AI suggests proper layer separation
func (h *Handler) CreateTodo(c *gin.Context) {
    userID := contextutil.GetUserID(c)  // AI knows context helpers

    var req CreateTodoRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        errors.HandleValidationError(c, err)  // AI uses centralized errors
        return
    }

    result, err := h.service.CreateTodo(c.Request.Context(), userID, &req)
    if err != nil {
        errors.HandleError(c, err)  // AI handles errors consistently
        return
    }

    c.JSON(http.StatusCreated, result)
}

Testing Patterns¶

// AI generates table-driven tests
tests := []struct {
    name        string
    request     *CreateTodoRequest
    setupMocks  func(*MockRepository)
    expectError bool
}{
    {
        name: "success",
        request: &CreateTodoRequest{Title: "Test"},
        setupMocks: func(m *MockRepository) {
            m.EXPECT().Create(gomock.Any(), gomock.Any()).Return(nil)
        },
    },
}

🔧 Customization¶

Adding Personal Rules (Cursor)¶

Create .cursor/rules/personal.mdc for your preferences:

---
alwaysApply: true
---

# Personal Coding Preferences

### Testing Style
- Use `assert` for most checks
- Use `require` when test can't continue
- Always add test description comments

### Error Messages
- Include context in error messages
- Use `fmt.Errorf` with `%w` for wrapping
- Log errors before returning

### Code Organization
- Group related functions together
- Separate public/private with blank line
- Add TODO comments with GitHub issues

Project-Specific Overrides¶

Want different rules for a specific GRAB-based project? Create custom rules:

---
alwaysApply: true
---

# MyProject Customizations

Based on GRAB, but with:
- Redis caching layer
- GraphQL API alongside REST
- Multi-tenancy support
- Additional middleware for analytics

Disabling AI Rules¶

If you need to disable AI rules temporarily:

GitHub Copilot: No built-in disable, but you can: - Rename .github/copilot-instructions.md temporarily - Or use Copilot's disable keyboard shortcut

Cursor: 1. Open Settings → Cursor Rules 2. Disable specific rule files 3. Or add alwaysApply: false to frontmatter

Windsurf: 1. Open Settings → AI Rules 2. Toggle off specific rules 3. Or remove "Always On" from file

🐛 Troubleshooting¶

AI Not Following GRAB Patterns¶

Issue: AI suggestions don't match GRAB's Clean Architecture

Solutions:

1. Verify file exists:

   ls -la .github/copilot-instructions.md    # GitHub Copilot
   ls -la .cursor/rules/grab.mdc             # Cursor
   ls -la .windsurf/rules/grab.md            # Windsurf
   ls -la AGENTS.md                          # Universal
   

2. Check file content: Open the file and verify it has content (not empty)

3. Restart IDE: Sometimes IDE needs restart to load new rules

4. Check IDE version: Ensure your IDE/extension is up to date

5. Explicitly mention GRAB: In your prompt, say "Follow GRAB's Clean Architecture pattern"

Cursor Rules Not Loading¶

Issue: .cursor/rules/grab.mdc not being applied

Solutions:

1. Check frontmatter:

   ---
   alwaysApply: true
   ---
   

2. Verify location: File must be in .cursor/rules/ directory

3. Check file extension: Must be .mdc not .md

4. Reload window: Use Command Palette → "Reload Window"

Conflicting AI Suggestions¶

Issue: AI suggests patterns that contradict GRAB

Solutions:

1. Be explicit: "Use GRAB's pattern from internal/user/"

2. Reference existing code: "Follow the same structure as UserHandler"

3. Mention specific guidelines: "Use Clean Architecture like in AGENTS.md"

4. Override suggestion: Accept suggestion, then refactor with AI's help

Performance Issues¶

Issue: AI responses are slow with large guidelines

Solutions:

• This is normal - comprehensive guidelines need processing time
• Initial responses may be slower, subsequent ones faster
• Consider using shorter format (Cursor/Windsurf) if speed is critical

📚 Examples¶

Example: AI-Assisted Domain Creation¶

Prompt: "Create a Todo domain following GRAB patterns"

AI Understanding: - Creates internal/todo/ directory - Generates model.go with GORM tags - Creates dto.go with validation tags - Implements repository interface - Implements service with business logic - Creates handler with Swagger annotations - Registers routes in router.go - Suggests migration command

Result: Complete domain in ~2 minutes instead of ~30 minutes

Example: AI-Assisted Testing¶

Prompt: "Write tests for TodoService.CreateTodo"

AI Understanding: - Uses table-driven test pattern - Creates mock repository - Tests success case - Tests validation errors - Tests repository errors - Follows GRAB's testing conventions - Includes gomock expectations

Result: Comprehensive test suite matching project standards

Example: AI-Assisted Refactoring¶

Prompt: "Refactor this handler to use centralized error handling"

AI Understanding: - Knows about errors.HandleError() - Knows about errors.HandleValidationError() - Maintains response format - Preserves Swagger annotations - Follows GRAB patterns

Result: Clean, consistent error handling

🎓 Best Practices¶

1. Be Specific with Prompts¶

❌ Bad: "Add error handling"

✅ Good: "Add error handling using GRAB's centralized errors package"

2. Reference Existing Code¶

❌ Bad: "Create a handler"

✅ Good: "Create a handler similar to UserHandler in internal/user/handler.go"

3. Mention Architecture¶

❌ Bad: "Add database code"

✅ Good: "Add repository layer following Clean Architecture"

4. Use GRAB Terminology¶

✅ Say: "domain", "repository", "service", "handler", "DTO"

❌ Don't say: "module", "model layer", "controller", "request struct"

5. Leverage Examples¶

Prompt: "Look at internal/user/ and create similar structure for products"

AI will mirror the proven patterns from the user domain.

🔗 Additional Resources¶

• Main Documentation: GRAB Docs
• Development Guide: Development Guide
• Quick Reference: Quick Reference
• Testing Guide: Testing
• GitHub Repository: vahiiiid/go-rest-api-boilerplate

🤝 Contributing¶

Found ways to improve AI assistance? We'd love your input!

• Open an Issue: GitHub Issues
• Start a Discussion: GitHub Discussions
• Submit a PR: Update AI guidelines with better examples

📝 FAQ¶

Why separate files for different IDEs?¶

Each IDE has unique conventions: - GitHub Copilot: Reads from .github/ directory - Cursor: Uses .mdc with YAML frontmatter - Windsurf: Uses .md with special headers - Universal: AGENTS.md standard

Having IDE-specific files ensures optimal experience for each tool.

Can I use multiple AI assistants?¶

Yes! All files coexist peacefully. Use Copilot in VS Code, Cursor in Cursor IDE, and AGENTS.md works everywhere.

Do I need to configure anything?¶

No! Just clone GRAB and start coding. AI assistants auto-discover their configuration files.

What if my AI doesn't support these formats?¶

Use AGENTS.md - it's the universal standard supported by most modern AI assistants.

Can I modify the AI guidelines?¶

Yes! Fork GRAB and customize for your needs. But consider: - Keep maintainer rules local (.github/copilot-instructions.local.md) - Commit developer-focused rules to help team

Will AI guidelines slow down my IDE?¶

No. AI reads guidelines once and caches them. No performance impact on your development workflow.

Last Updated: 2025-12-10
GRAB Version: v2.0.0