BLISS FRAMEWORK - CLAUDE CODE GENERAL PRINCIPLES
Version: 1.0.0
Last Modified: 2025-01-19T00:00:00Z
Category: Core Guidelines
Priority: Critical

Core working principles for all projects developed with Claude Code.

=== COMMUNICATION ===

Language Convention:
- User communication: Czech (čeština)
- Code and documentation: English
- Comments in code: English
- Git commits: English

Response Style:
- Direct and concise
- Focus on implementation over explanation
- Show code first, explain if needed
- No unnecessary preambles

=== DEVELOPMENT WORKFLOW ===

1. Task Planning
Always use TodoWrite tool for:
- Tasks with 3+ steps
- Complex implementations
- Multiple file modifications
- Bug fixing with investigation

2. Investigation First
Before implementing:
- Search existing codebase for patterns
- Check dependencies and imports
- Understand current architecture
- Look for similar implementations

3. Follow Existing Patterns
- Match code style in existing files
- Use established libraries (don't introduce new ones)
- Follow naming conventions
- Maintain consistency over personal preference

=== CODE QUALITY ===

Never Compromise On:
1. Security: No hardcoded secrets, proper validation
2. Type Safety: Full typing in TypeScript/C#
3. Error Handling: Explicit error handling everywhere
4. Testing: Write tests for critical logic

Always Prefer:
- Explicit over implicit
- Readability over cleverness
- Composition over inheritance
- Pure functions over side effects

=== FILE MANAGEMENT ===

Creation Rules:
- NEVER create files unless absolutely necessary
- ALWAYS prefer editing existing files
- NEVER create documentation proactively
- ONLY create what's explicitly requested

Modification Rules:
- Understand context before editing
- Preserve existing formatting
- Keep changes minimal and focused
- Don't refactor unrelated code

=== ARCHITECTURE PRINCIPLES ===

Three-Layer Rule:
IO Layer ← → Management Layer ← → Provider Layer
                    ↑
                Side Layer
           (Models, Mappers, Helpers)

Strict Rules:
- Providers NEVER talk to each other
- Management orchestrates all provider interaction
- IO handles all external communication
- Side layer has no dependencies on other layers

Provider Pattern:
Each provider:
- Has single responsibility
- Returns domain models (not raw data)
- Handles its own errors
- Is independently testable

=== ERROR HANDLING ===

Standard Approach:
```typescript
try {
    // Happy path
    return { success: true, data: result };
} catch (error) {
    // Explicit error handling
    logger.error('Operation failed', error);
    return { success: false, error: error.message };
}
```

Never:
- Swallow errors silently
- Use generic error messages
- Throw in providers (return error objects)
- Log sensitive information

=== GIT WORKFLOW ===

Commit Messages:
Format: <type>: <description>

Types:
- feat: New feature
- fix: Bug fix
- refactor: Code restructuring
- docs: Documentation
- test: Testing
- chore: Maintenance

Branch Strategy:
- main/prod: Production code
- feature/*: New features
- fix/*: Bug fixes
- refactor/*: Code improvements

=== PERFORMANCE CONSIDERATIONS ===

Always:
- Batch database operations
- Use pagination for lists
- Cache expensive computations
- Lazy load when possible

Never:
- Premature optimization
- N+1 queries
- Synchronous blocking operations
- Memory leaks (cleanup subscriptions)

=== TESTING PHILOSOPHY ===

Test Priority:
1. Critical business logic
2. Data transformations
3. Edge cases
4. Integration points

Test Structure:
```typescript
describe('Component/Function', () => {
    describe('method', () => {
        it('should handle normal case', () => {});
        it('should handle edge case', () => {});
        it('should handle error case', () => {});
    });
});
```

=== CODE REVIEW CHECKLIST ===

Before considering task complete:
- [ ] Follows existing patterns
- [ ] Has error handling
- [ ] No hardcoded values
- [ ] Tests pass
- [ ] No console.logs
- [ ] Types are complete
- [ ] Names are descriptive