Skip to content

CLAUDE.md

Latest commit

 

History

History
219 lines (177 loc) · 9.09 KB

CLAUDE.md

File metadata and controls

219 lines (177 loc) · 9.09 KB

[PROJECT NAME] - AI Context Template (claude-master)

1. Project Overview

  • Vision: [Describe your project's vision and goals]
  • Current Phase: [Current development phase and status]
  • Key Architecture: [High-level architecture description]
  • Development Strategy: [Development approach and strategy notes]

2. Project Structure

⚠️ CRITICAL: AI agents MUST read the Project Structure documentation before attempting any task to understand the complete technology stack, file tree and project organization.

[Project Name] follows a [describe architecture pattern]. For the complete tech stack and file tree structure, see docs/ai-context/project-structure.md.

3. Coding Standards & AI Instructions

General Instructions

  • Your most important job is to manage your own context. Always read any relevant files BEFORE planning changes.
  • When updating documentation, keep updates concise and on point to prevent bloat.
  • Write code following KISS, YAGNI, and DRY principles.
  • When in doubt follow proven best practices for implementation.
  • Do not commit to git without user approval.
  • Do not run any servers, rather tell the user to run servers for testing.
  • Always consider industry standard libraries/frameworks first over custom implementations.
  • Never mock anything. Never use placeholders. Never omit code.
  • Apply SOLID principles where relevant. Use modern framework features rather than reinventing solutions.
  • Be brutally honest about whether an idea is good or bad.
  • Make side effects explicit and minimal.
  • Design database schema to be evolution-friendly (avoid breaking changes).

File Organization & Modularity

  • Default to creating multiple small, focused files rather than large monolithic ones

  • Each file should have a single responsibility and clear purpose

  • Keep files under 350 lines when possible - split larger files by extracting utilities, constants, types, or logical components into separate modules

  • Separate concerns: utilities, constants, types, components, and business logic into different files

  • Prefer composition over inheritance - use inheritance only for true 'is-a' relationships, favor composition for 'has-a' or behavior mixing

  • Follow existing project structure and conventions - place files in appropriate directories. Create new directories and move files if deemed appropriate.

  • Use well defined sub-directories to keep things organized and scalable

  • Structure projects with clear folder hierarchies and consistent naming conventions

  • Import/export properly - design for reusability and maintainability

Type Hints (REQUIRED)

  • Always use type hints for function parameters and return values
  • Use from typing import for complex types
  • Prefer Optional[T] over Union[T, None]
  • Use Pydantic models for data structures
# Good
from typing import Optional, List, Dict, Tuple

async def process_audio(
    audio_data: bytes,
    session_id: str,
    language: Optional[str] = None
) -> Tuple[bytes, Dict[str, Any]]:
    """Process audio through the pipeline."""
    pass

Naming Conventions

  • Classes: PascalCase (e.g., VoicePipeline)
  • Functions/Methods: snake_case (e.g., process_audio)
  • Constants: UPPER_SNAKE_CASE (e.g., MAX_AUDIO_SIZE)
  • Private methods: Leading underscore (e.g., _validate_input)
  • Pydantic Models: PascalCase with Schema suffix (e.g., ChatRequestSchema, UserSchema)

Documentation Requirements

  • Every module needs a docstring
  • Every public function needs a docstring
  • Use Google-style docstrings
  • Include type information in docstrings
def calculate_similarity(text1: str, text2: str) -> float:
    """Calculate semantic similarity between two texts.

    Args:
        text1: First text to compare
        text2: Second text to compare

    Returns:
        Similarity score between 0 and 1

    Raises:
        ValueError: If either text is empty
    """
    pass

Security First

  • Never trust external inputs - validate everything at the boundaries
  • Keep secrets in environment variables, never in code
  • Log security events (login attempts, auth failures, rate limits, permission denials) but never log sensitive data (audio, conversation content, tokens, personal info)
  • Authenticate users at the API gateway level - never trust client-side tokens
  • Use Row Level Security (RLS) to enforce data isolation between users
  • Design auth to work across all client types consistently
  • Use secure authentication patterns for your platform
  • Validate all authentication tokens server-side before creating sessions
  • Sanitize all user inputs before storing or processing

Error Handling

  • Use specific exceptions over generic ones
  • Always log errors with context
  • Provide helpful error messages
  • Fail securely - errors shouldn't reveal system internals

Observable Systems & Logging Standards

  • Every request needs a correlation ID for debugging
  • Structure logs for machines, not humans - use JSON format with consistent fields (timestamp, level, correlation_id, event, context) for automated analysis
  • Make debugging possible across service boundaries

State Management

  • Have one source of truth for each piece of state
  • Make state changes explicit and traceable
  • Design for multi-service voice processing - use session IDs for state coordination, avoid storing conversation data in server memory
  • Keep conversation history lightweight (text, not audio)

API Design Principles

  • RESTful design with consistent URL patterns
  • Use HTTP status codes correctly
  • Version APIs from day one (/v1/, /v2/)
  • Support pagination for list endpoints
  • Use consistent JSON response format:
    • Success: { "data": {...}, "error": null }
    • Error: { "data": null, "error": {"message": "...", "code": "..."} }

4. MCP Server Integrations

Gemini Consultation Server

When to use:

  • Complex coding problems requiring deep analysis or multiple approaches
  • Code reviews and architecture discussions
  • Debugging complex issues across multiple files
  • Performance optimization and refactoring guidance
  • Detailed explanations of complex implementations
  • Highly security relevant tasks

IMPORTANT: Include project context in new sessions:

  • Include /docs/ai-context/project-structure.md in the attached_files array when starting a new consultation session
  • This provides Gemini with comprehensive understanding of our technology stack, file organization, and project architecture
  • Not needed for follow-up questions in the same session (context is retained)

Usage patterns:

# New consultation session (always include project structure)
mcp__gemini__consult_gemini(
    specific_question="How should I optimize this voice pipeline?",
    problem_description="Need to reduce latency in real-time audio processing",
    code_context="Current pipeline processes audio sequentially...",
    attached_files=[
        "docs/ai-context/project-structure.md",  # Include for new sessions
        "agents/tutor-server/src/core/pipelines/ptt_live_api/core.py"
    ],
    preferred_approach="optimize"
)

# Follow-up in existing session (no need to re-attach project structure)
mcp__gemini__consult_gemini(
    specific_question="What about memory usage?",
    session_id="session_123",
    additional_context="Implemented your suggestions, now seeing high memory usage"
)

Key capabilities:

  • Persistent conversation sessions with context retention
  • File attachment and caching for multi-file analysis
  • Specialized assistance modes (solution, review, debug, optimize, explain)
  • Session management for complex, multi-step problems

Important: Treat Gemini's responses as advisory feedback. Evaluate the suggestions critically, incorporate valuable insights into your solution, then proceed with your implementation.

Context7 Documentation Server

Repository: Context7 MCP Server

When to use:

  • Working with external libraries/frameworks (React, FastAPI, Next.js, etc.)
  • Need current documentation beyond training cutoff
  • Implementing new integrations or features with third-party tools
  • Troubleshooting library-specific issues

Usage patterns:

# Resolve library name to Context7 ID
mcp__context7__resolve_library_id(libraryName="react")

# Fetch focused documentation
mcp__context7__get_library_docs(
    context7CompatibleLibraryID="/facebook/react",
    topic="hooks",
    tokens=8000
)

Key capabilities:

  • Up-to-date library documentation access
  • Topic-focused documentation retrieval
  • Support for specific library versions
  • Integration with current development practices

5. Post-Task Completion Protocol

After completing any coding task, follow this checklist:

1. Type Safety & Quality Checks

Run the appropriate commands based on what was modified:

  • Python projects: Run mypy type checking
  • TypeScript projects: Run tsc --noEmit
  • Other languages: Run appropriate linting/type checking tools

2. Verification

  • Ensure all type checks pass before considering the task complete
  • If type errors are found, fix them before marking the task as done