01-coding-standards.mdc

---
description: 
globs: 
alwaysApply: false
---
# Coding Standards & Best Practices

**Description**: Core development standards covering code quality, workflow, security, testing, and communication guidelines for containerized applications. Apply when writing or modifying any code.

**Key Focus Areas**: Development workflow, code standards, containerization practices, security/performance, testing, communication standards

## Code Quality & Development Process

### Development Workflow
- **Verify Information**: Always verify information before presenting it. Do not make assumptions or speculate without clear evidence
- **Incremental Changes**: Make changes incrementally and provide opportunities to review and validate changes
- **Single Responsibility**: Each component, service, and container should have a single, well-defined responsibility
- **Preserve Existing Architecture**: Don't remove unrelated code or functionalities. Maintain existing system boundaries and interfaces
- **Container Readiness**: Ensure all code changes maintain container compatibility and follow containerization best practices
- **Documentation First**: Always update documentation immediately after making code changes
- **Complete Documentation**: Ensure all changes are documented appropriately before considering the task complete

### Code Standards
- **Explicit Naming**: Use descriptive, explicit variable and function names that clearly indicate purpose and scope
- **Consistent Style**: Adhere to language-specific style guides and maintain consistency across the codebase
- **Configuration Externalization**: Use environment variables and configuration files instead of hardcoded values
- **Modular Design**: Design for modularity to enable easy containerization and service decomposition
- **Interface Contracts**: Define clear interfaces between components and services
- **Dependency Management**: Explicitly declare and manage all dependencies with version constraints

### Container & Service Standards
- **Stateless Design**: Design services to be stateless whenever possible for better scalability
- **Health Checks**: Implement comprehensive health check endpoints for all services
- **Graceful Shutdown**: Handle shutdown signals properly to ensure clean container termination
- **Resource Efficiency**: Write resource-efficient code suitable for containerized environments
- **Service Discovery**: Use service names and internal networking for inter-service communication
- **Configuration Management**: Support multiple configuration sources (environment variables, config files, secrets)

### Security & Performance
- **Security-First Approach**: Consider security implications of all code changes, especially for containerized applications
- **Least Privilege**: Run containers and services with minimal required permissions
- **Secrets Management**: Never hardcode secrets; use proper secret management systems
- **Input Validation**: Validate all inputs, especially for services exposed through APIs
- **Performance Optimization**: Consider performance implications, especially for services running in resource-constrained containers
- **Error Handling**: Implement comprehensive error handling with proper logging
- **Monitoring Integration**: Include necessary logging and metrics for observability

### Testing & Quality Assurance
- **Container Testing**: Test code both locally and in containerized environments
- **Integration Testing**: Test service-to-service communication and API interactions
- **Dependency Testing**: Validate all dependencies work correctly in containerized environments
- **Version Compatibility**: Ensure code works with specified language and framework versions
- **Database Compatibility**: Test database interactions and schema compatibility
- **Performance Testing**: Validate performance under containerized resource constraints

### Communication Standards
- **Clear Communication**: Provide clear, direct communication without unnecessary apologies or confirmations
- **Actionable Feedback**: Give specific, actionable feedback and suggestions
- **Real File References**: Always reference actual files and locations, not generated or theoretical ones
- **Context Awareness**: Check actual file contents and current implementations before making suggestions
- **No Unnecessary Verbosity**: Avoid summaries, confirmations, or explanations of obvious changes
- **Implementation Focus**: Focus on practical implementation details rather than theoretical discussions

### Container-Specific Practices
- **Multi-Stage Builds**: Use multi-stage Docker builds for optimized production images
- **Layer Optimization**: Minimize Docker layers and optimize for caching
- **Base Image Selection**: Choose appropriate, secure base images and keep them updated
- **Resource Limits**: Define appropriate resource limits and requests for containers
- **Environment Separation**: Maintain clear separation between development, staging, and production environments
- **Logging Standards**: Use structured logging suitable for containerized log aggregation

### Microservices Patterns
- **Service Boundaries**: Define clear service boundaries based on business capabilities
- **API Design**: Design consistent, versioned APIs for service communication
- **Data Consistency**: Implement appropriate data consistency patterns for distributed systems
- **Circuit Breakers**: Implement circuit breaker patterns for resilient service communication
- **Async Communication**: Use asynchronous communication patterns where appropriate
- **Service Mesh Ready**: Design services to work well with service mesh technologies