Claude-Code-Workflow/CLAUDE.md

Development Guidelines

Overview

This document defines project-specific coding standards and development principles.

Philosophy

Core Beliefs

• Incremental progress over big bangs - Small changes that compile and pass tests
• Learning from existing code - Study and plan before implementing
• Pragmatic over dogmatic - Adapt to project reality
• Clear intent over clever code - Be boring and obvious

Simplicity Means

• Single responsibility per function/class
• Avoid premature abstractions
• No clever tricks - choose the boring solution
• If you need to explain it, it's too complex

Code Quality Standards

Code Style

• Consistent formatting - Follow project's established formatting rules
• Meaningful names - Variables and functions should be self-documenting
• Small functions - Each function should do one thing well
• Clear structure - Logical organization of code modules

Testing Standards

• Test coverage - Aim for high test coverage on critical paths
• Test readability - Tests should serve as documentation
• Edge cases - Consider boundary conditions and error states
• Test isolation - Tests should be independent and repeatable

Project Integration

Learning the Codebase

• Find 3 similar features/components
• Identify common patterns and conventions
• Use same libraries/utilities when possible
• Follow existing test patterns

Tooling

• Use project's existing build system
• Use project's test framework
• Use project's formatter/linter settings
• Don't introduce new tools without strong justification

Important Reminders

NEVER:

• Make assumptions - verify with existing code

ALWAYS:

• Plan complex tasks thoroughly before implementation
• Generate task decomposition for multi-module work (>3 modules or >5 subtasks)
• Track progress using TODO checklists for complex tasks
• Validate planning documents before starting development
• Commit working code incrementally
• Update plan documentation and progress tracking as you go
• Learn from existing implementations
• Stop after 3 failed attempts and reassess

Gemini Context Protocol

For all Gemini CLI usage, command syntax, and integration guidelines: @~/.claude/workflows/gemini-unified.md

📂 CLAUDE.md Hierarchy Rules - Avoiding Content Duplication

Layer 1: Root Level (./CLAUDE.md)

Content Focus:
  - Project overview and purpose (high-level only)
  - Technology stack summary
  - Architecture decisions and principles
  - Development workflow overview
  - Quick start guide
  
Strictly Avoid:
  - Implementation details
  - Module-specific patterns
  - Code examples from specific modules
  - Domain internal architecture

Layer 2: Domain Level (./src/CLAUDE.md, ./tests/CLAUDE.md)

Content Focus:
  - Domain architecture and responsibilities
  - Module organization within domain
  - Inter-module communication patterns
  - Domain-specific conventions
  - Integration points with other domains
  
Strictly Avoid:
  - Duplicating root project overview
  - Component/function-level details
  - Specific implementation code
  - Module internal patterns

Layer 3: Module Level (./src/api/CLAUDE.md, ./src/components/CLAUDE.md)

Content Focus:
  - Module-specific implementation patterns
  - Internal architecture and design decisions
  - API contracts and interfaces
  - Module dependencies and relationships
  - Testing strategies for this module
  
Strictly Avoid:
  - Project overview content
  - Domain-wide architectural patterns
  - Detailed function documentation
  - Configuration specifics

Layer 4: Sub-Module Level (./src/api/auth/CLAUDE.md)

Content Focus:
  - Detailed implementation specifics
  - Component/function documentation
  - Configuration details and examples
  - Usage examples and patterns
  - Performance considerations
  
Strictly Avoid:
  - Architecture decisions (belong in higher levels)
  - Module-level organizational patterns
  - Domain or project overview content

Content Uniqueness Rules

• Each layer owns its abstraction level - no content sharing between layers
• Reference, don't duplicate - point to other layers, never copy content
• Maintain perspective - each layer sees the system at its appropriate scale
• Avoid implementation creep - higher layers stay architectural

Update Strategy

• Related Mode: Update only affected modules + parent hierarchy propagation
• Full Mode: Complete hierarchy refresh with strict layer boundaries
• Context Intelligence: Automatic detection of what needs updating

Quality Assurance

• Layer Validation: Each CLAUDE.md must stay within its layer's purpose
• Duplication Detection: Cross-reference content to prevent overlap
• Hierarchy Consistency: Parent layers reflect child changes appropriately
• Content Relevance: Regular cleanup of outdated or irrelevant content