Living version of CLAUDE.md

CLAUDE.md

Speech Processing Service Development Guide

Project Context

Real-time live speech processing service: raw audio → windowing → transcription → mind map graph construction

Core Development Principles

1. Test-Driven Development (TDD)

• Always write tests first - One test per core behavior
• Implement to fail - Then make tests pass with simplest code
• Incremental iterations - Stop when tests pass

2. Data Flow Architecture

• Think about concrete data flows: Input → Processing → Output
• Scoped, targeted implementations - Clean, purposeful data movement
• Focus on core logic - No unnecessary complexity

3. Minimal Core Implementation

• Solve exactly what's asked - Nothing more, nothing less
• No premature optimization - Logging, error handling, extras come later
• Edit don't create - Prefer modifying existing files

4. Git commits

• Periodic commits: Make git commits for your incremental code changes.
• Meaningful messages: Semantically meaningful commit messages that build a complete, accurate history of the app's state.
• Leverage git history: Periodically check the commit history to keep changes incremental and well-scoped.

Concrete Development Workflow

Phase 1: UNDERSTAND FIRST

1. Define the ask - Write exact requested behavior in one sentence
2. Map territory - Use Grep, Glob to find relevant code
3. Identify patterns - How does this codebase solve similar problems?
4. Define boundaries - What's the MINIMAL change needed?

⚠️ Gate Condition: Build your function call to TodosWrite with an ideal structure for Phase 3: IMPLEMENT.

Phase 2: VERIFY UNDERSTANDING SECOND

Data Flow Checklist:

• What data flows in?
• What data flows out?
• What's the simplest transformation between them?
• What existing pattern am I following?

⚠️ Gate Condition: Confirm you will follow the Phase 3: IMPLEMENT stage below for your work.

Phase 3: IMPLEMENT (!IMPORTANT: Always TDD Development)

1. Write tests - Test exact behavior requested
2. Simple implementations - Direct, minimal functionality to pass tests, nothing more
3. Verify with uv run python -m pytest tests/... - Run tests
4. Iterate solutions - Scoped, isolated refactors until tests pass
5. Commit changes - git add . && git commit -m "meaningful message"
6. Stop when main task done - Resist urges to improve and over-engineer

⚠️ Gate Condition: After ANY code change → MUST commit with meaningful message before proceeding

Testing Protocol

1. Write minimal test for exact behavior in the tests/ folder.
2. Implement simplest passing code
3. Run tests with uv run python -m pytest tests/ ... as pipe the output into tests/output/*
4. Stop immediately when tests pass

Implementation Constraints

Hard Boundaries

• One behavior per task - "and also..." means you've gone too far
• Follow don't lead - Use existing patterns, don't invent new ones
• No helpful additions - Don't add unrequested features
• Edit existing files - Avoid creating new files

Warning Signs (STOP IMMEDIATELY)

• Creating multiple new files
• Adding unrequested features
• Implementing complex abstractions
• Deviating from existing patterns
• Can't explain the data transformation simply

Tool Usage Protocol

We are in a Python UV Environment

⚠️ CRITICAL: !IMPORTANT All python tests must run with: uv run python -m pytest tests/...

Understanding Tools: Phase 1 and Phase 2

• Glob - Map codebase structure
• Read - Understand specific implementations
• Grep - Find patterns and conventions

Implementation Tools: Phase 3 - Implement

• Edit - Minimal changes to existing files
• Write - Only when no existing file fits
• MultiEdit - Related changes to same file

Verification Tools: Phase 3 - Verify

• Bash - Run tests and checks
• Read - Verify changes look correct

Success Criteria

• ✅ Specific requested behavior works
• ✅ Tests pass
• ✅ No over-engineering or scope creep
• ✅ Data flows cleanly through the system