Best Practices

AI Coding Agent Instructions

For developers using AI coding agents (GitHub Copilot, Cursor, Codeium, etc.), Humus provides modular instruction files that you can copy to your project repository.

📋 Browse the instructions directory

Copy the relevant instruction files to your project’s .github/ directory (or similar location):

Available instruction files:

• humus-common.instructions.md - Common patterns for all service types (required)
• humus-rest.instructions.md - REST API specific patterns
• humus-grpc.instructions.md - gRPC service specific patterns
• humus-kafka.instructions.md - Kafka queue processor specific patterns
• humus-job.instructions.md - Job executor specific patterns

What’s included:

• Project structure patterns (simple, organized, production-ready)
• Service-specific patterns (REST handlers, gRPC services, queue processors, jobs)
• Configuration best practices
• Error handling strategies
• Common pitfalls and anti-patterns
• Testing guidelines

Usage: Copy humus-common.instructions.md along with the file(s) specific to your application type. For example, a REST API would use humus-common.instructions.md + humus-rest.instructions.md.

This helps your AI coding agent generate code that follows Humus conventions and best practices.

General Best Practices

For detailed best practices and patterns, see the Project Structure guide and review the example projects.

Community Support

See GitHub Discussions for community support.