Skip to content

General Principles

Guideline Metadata

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

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

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