Streamlining AI Development: A Simple Trick for Better OpenHands Integration

I recently discovered a game-changing approach while working with #OpenHands (https://github.com/All-Hands-AI/OpenHands) from All Hands AI that I'm excited to share with the community.

As a developer working with a customized Spring Boot application (without Spring Data) that heavily relies on JDBCTemplate, I faced a common challenge: getting AI to understand and respect my project's specific architecture and conventions. Our codebase includes custom wrappers around Database, Redis, and various utilities, along with a particular folder structure and naming conventions.

Initially, my interactions with OpenHands were frustrating. The AI would:

• Generate files in random locations
• Suggest Spring Data implementations when not needed
• Use conventions that didn't align with our project standards

My first attempt to solve this involved sharing all requirements via chat. However, this proved inconsistent, as I would occasionally miss crucial details, leading to incorrect outputs.

Then came the breakthrough: I created a simple AI_GUIDELINES.md file in my project. My very first interaction with OpenHands is now to ask it to thoroughly review these guidelines. This initial step ensures that all subsequent code generation and recommendations are perfectly aligned with our project standards. This comprehensive guide transformed how OpenHands interacted with our codebase.

Just like training a new team member, this first "onboarding" chat with OpenHands sets the foundation for all future interactions. It's remarkable how this simple step - having OpenHands review our AI_GUIDELINES.md file at the start - has dramatically improved the quality and consistency of its output. From that point forward, every piece of code it generates follows our established patterns, using the right package structure, naming conventions, and even our custom database access patterns.

Here's a glimpse into what the guidelines cover:

Project Structure and Conventions

We maintain a strict package structure:

com.example.project/
├── annotation/          # Custom annotations
├── config/                 # Configuration classes
├── controller/           # Request handlers
├── service/               # Services and implementations
├── dto/                    # Data Transfer Objects
├── enums/               # Enumeration classes
├── exception/          # Exception handling
├── mapper/             # MapStruct mappers
├── model/               # Domain models
└── util/                    # Utility classes        

Naming and Documentation Standards

The guidelines enforce clear naming conventions:

• Controllers must end with Controller (e.g., UserController)
• Services follow interface-implementation pattern with comprehensive Javadoc
• DTOs must end with DTO (e.g., UserDTO)
• Request classes must start with action name (e.g., CreateOrganisationRequest)

Database Practices

We implement strict database conventions:

• All tables use standardized ID generation with public.generate_id()
• Comprehensive table and column comments are mandatory
• Strict naming conventions for constraints (e.g., pk_, fk_, uq_ prefixes)
• All SQL queries must use proper type casting (e.g., :param::VARCHAR, :param::BIGINT)

Service Layer Implementation

Our services follow a structured pattern:

@Slf4j
@Service
@RequiredArgsConstructor
public class OrganisationServiceImpl implements OrganisationService {
    private final DataAccessUtility dataAccessUtility;
    
    @Override
    @Transactional
    public OrganisationPartialDto createOrganisation(CreateOrganisationRequest request) {
        log.debug("Creating new organisation with externalId: {}", request.getExternalId());
        // Implementation details...
    }
}        

The result? OpenHands now generates exactly what I need, respecting our project's architecture and conventions. It's like having a team member who perfectly understands our development standards.

This approach has been particularly effective for:

• Creating new logic
• Adding new files
• Maintaining consistency across the codebase
• Ensuring proper documentation and error handling
• Following database access patterns

I'm currently exploring how this method performs with existing codebase modifications and complex business logic implementations. Some areas I'm focusing on:

• Integration with our custom DataAccessUtility
• Complex SQL query generation with proper type casting
• Service layer documentation patterns
• Exception handling strategies

I'll share my findings in the coming weeks as I delve deeper into these aspects.

What's your experience with AI coding assistants? Have you found effective ways to make them work better with your custom project requirements? Let's discuss in the comments!

P.S. Want to implement something similar? Start with a clear project structure documentation and gradually add your specific conventions and requirements. The key is being explicit about your expectations!