meshseeks CLAUDE.md

GLOBAL CODING STANDARDS

Reference guide for all project development. For detailed task planning, see TASK_PLAN_GUIDE.md

🔴 AGENT INSTRUCTIONS

IMPORTANT: As an agent, you MUST read and follow ALL guidelines in this document BEFORE executing any task in a task list. DO NOT skip or ignore any part of these standards. These standards supersede any conflicting instructions you may have received previously.

Project Structure

project_name/
├── docs/
│   ├── CHANGELOG.md
│   ├── memory_bank/
│   └── tasks/
├── examples/
├── pyproject.toml
├── README.md
├── src/
│   └── project_name/
├── tests/
│   ├── fixtures/
│   └── project_name/
└── uv.lock

• Package Management: Always use uv with pyproject.toml, never pip
• Mirror Structure: examples/, tests/ mirror the project structure in src/
• Documentation: Keep comprehensive docs in docs/ directory

Module Requirements

• Size: Maximum 500 lines of code per file
• Documentation Header: Every file must include:
  • Description of purpose
  • Links to third-party package documentation
  • Sample input
  • Expected output
• Validation Function: Every file needs a main block (if __name__ == "__main__":) that tests with real data

Architecture Principles

• Function-First: Prefer simple functions over classes
• Class Usage: Only use classes when:
  • Maintaining state
  • Implementing data validation models
  • Following established design patterns
• Async Code: Never use asyncio.run() inside functions - only in main blocks
• Type Hints: Use the typing library for clear type annotations to improve code understanding and tooling
  • Type hints should be used for all function parameters and return values
  • Use type hints for key variables where it improves clarity
  • Prefer concrete types over Any when possible
  • Do not add type hints if they significantly reduce code readability

  # Good type hint usage:
  from typing import Dict, List, Optional, Union, Tuple
  
  def process_document(doc_id: str, options: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
      """Process a document with optional configuration."""
      # Implementation
      return result
      
  # Simple types don't need annotations inside functions if obvious:
  def get_user_name(user_id: int) -> str:
      name = "John"  # Type inference works here, no annotation needed
      return name
  

• NO Conditional Imports:
  • Never use try/except blocks for imports of required packages
  • If a package is in pyproject.toml, import it directly at the top of the file
  • Handle specific errors during usage, not during import
  • Only use conditional imports for truly optional features (rare)