[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. Multi-Agent Workflows & Context Injection

Automatic Context Injection for Sub-Agents

When using the Task tool to spawn sub-agents, the core project context (CLAUDE.md, project-structure.md, docs-overview.md) is automatically injected into their prompts via the subagent-context-injector hook. This ensures all sub-agents have immediate access to essential project documentation without the need of manual specification in each Task prompt.

5. 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

Automatic Context Injection:

• The kit's gemini-context-injector.sh hook automatically includes two key files for new sessions:
  • /docs/ai-context/project-structure.md - Complete project structure and tech stack
  • /MCP-ASSISTANT-RULES.md - Your project-specific coding standards and guidelines
• This ensures Gemini always has comprehensive understanding of your technology stack, architecture, and project standards

Usage patterns:

# New consultation session (project structure auto-attached by hooks)
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=[
        "src/core/pipelines/voice_pipeline.py"  # Your specific files
    ],
    preferred_approach="optimize"
)

# Follow-up in existing session
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

6. 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