obsidian-mcp-server copilot-instructions.md

Development Guidelines

This document contains critical information about working with this codebase. Follow these guidelines precisely.

Core Development Rules

1. Package Management

   • ONLY use uv, NEVER pip
   • Installation: uv add package
   • Running tools: uv run tool
   • Upgrading: uv add --dev package --upgrade-package package
   • FORBIDDEN: pip-compatible install subcommands through uv, @latest syntax

2. Code Quality

   • Type hints required for all code
   • Public APIs must have docstrings
   • Functions must be focused and small
   • Follow existing patterns exactly
   • Line length: 88 chars maximum

3. Testing Requirements

   • Framework: uv run pytest
   • Async testing: use anyio, not asyncio
   • Coverage: test edge cases and errors
   • New features require tests
   • Bug fixes require regression tests

4. Code Style

   • PEP 8 naming (snake_case for functions/variables)
   • Class names in PascalCase
   • Constants in UPPER_SNAKE_CASE
   • Document with docstrings
   • Use f-strings for formatting

• For commits fixing bugs or adding features based on user reports add:

  git commit --trailer "Reported-by:<name>"
  

  Where <name> is the name of the user.

• For commits related to a Github issue, add

  git commit --trailer "Github-Issue:#<number>"
  

• NEVER ever mention a co-authored-by or similar aspects. In particular, never mention the tool used to create the commit message or PR.

Development Philosophy

• Simplicity: Write simple, straightforward code
• Readability: Make code easy to understand
• Performance: Consider performance without sacrificing readability
• Maintainability: Write code that's easy to update
• Testability: Ensure code is testable
• Reusability: Create reusable components and functions
• Less Code = Less Debt: Minimize code footprint

Coding Best Practices

• Early Returns: Use to avoid nested conditions
• Descriptive Names: Use clear variable/function names (prefix handlers with "handle")
• Constants Over Functions: Use constants where possible
• DRY Code: Don't repeat yourself
• Functional Style: Prefer functional, immutable approaches when not verbose
• Minimal Changes: Only modify code related to the task at hand
• Function Ordering: Define composing functions before their components
• TODO Comments: Mark issues in existing code with "TODO:" prefix
• Simplicity: Prioritize simplicity and readability over clever solutions
• Build Iteratively Start with minimal functionality and verify it works before adding complexity
• Run Tests: Test your code frequently with realistic inputs and validate outputs
• Build Test Environments: Create testing environments for components that are difficult to validate directly
• Functional Code: Use functional and stateless approaches where they improve clarity
• Clean logic: Keep core logic clean and push implementation details to the edges
• File Organisation: Balance file organization with simplicity - use an appropriate number of files for the project scale