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 CLI Guidelines

Triggering Mechanism

IMPORTANT: Actively recognize and respond to Gemini invocation needs:

• Semantic Intent Recognition: When user input contains semantic meaning indicating the need to call Gemini (e.g., "analyze this with Gemini", "get context for this", "understand the codebase"), immediately follow the guidelines to invoke Gemini
• Context Requirements: When dealing with tasks that require broader context understanding or cross-file analysis, proactively call Gemini to obtain comprehensive context
• Complex Problem Analysis: When encountering complex problems that require deep analysis or multi-faceted understanding, utilize Gemini for intelligent problem decomposition and analysis

When to Trigger Gemini

1. User explicitly or implicitly requests Gemini assistance
2. Task requires understanding of multiple interconnected files
3. Problem complexity exceeds single-file scope
4. Need for intelligent context inference
5. Require comprehensive codebase analysis

For all Gemini CLI usage, command syntax, and integration guidelines: @/.claude/workflows/gemini-cli-guidelines.md @/.claude/workflows/gemini-intelligent-context.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