ado-mcp: Instructions file for Claude Code

🔄 Project Awareness & Context

• Check the tasks/ folder at the start of a new conversation to understand current project requirements, PRDs, and active tasks.
• Check CONTRIBUTING.md when working on tasks.
• Use consistent naming conventions, file structure, and architecture patterns as established in the codebase.
• Use venv_linux (the virtual environment) whenever executing Python commands, including for tests.
• Read NEW_TOOL_WORKFLOW.md when asked to create a new tool

🧱 Code Structure & Modularity

• Never create a file longer than 500 lines of code. If a file approaches this limit, refactor by splitting it into modules or helper files.
• Organize code into clearly separated modules, grouped by feature or responsibility. For agents this looks like:
  • agent.py - Main agent definition and execution logic
  • tools.py - Tool functions used by the agent
  • prompts.py - System prompts
• Use clear, consistent imports (prefer relative imports within packages).
• Use clear, consistent imports (prefer relative imports within packages).
• Use python_dotenv and load_env() for environment variables.
• Use logging module to add observability Any errors must include all relevant execution context so an llm can fix it.

🧪 Testing & Reliability

• Always create Pytest end to end tests for new features that a user can experience.
• Only create end to end tests using actual data and real connections - black box test how a user would test.
• ALWAYS use task test to run tests - never run pytest directly. This ensures proper environment variables are sourced.
• Tests run in parallel by default using pytest-xdist for faster execution (~15s vs 80s):
  • Use task test for parallel execution (default)
  • Use task test-sequential for debugging when you need sequential execution
  • Use task test-single TEST_NAME=path::to::test for individual test execution
• Tests require ADO credentials - AZURE_DEVOPS_EXT_PAT and ADO_ORGANIZATION_URL must be set via Taskfile.
• FastMCP converts Pydantic models to dictionaries - tests should expect dictionary responses, not Pydantic objects.
• Dedicated test pipelines are pre-created for pipeline run tests to avoid create/delete overhead.
• After updating any logic, check whether existing unit tests need to be updated. If so, do it. use task test to ensure everything still works
• Tests should live in a /tests folder mirroring the main app structure.
• Pytest fixture imports: When using pytest fixtures like telemetry_setup, always import them even if they appear "unused" to linters. The pyproject.toml is configured to allow F401 (unused imports) and F811 (fixture redefinitions) in test files.
• NEVER use mocking in tests.
  • Include at least:
    • 1 test for expected use
    • 1 edge case
    • 1 failure case
    • 1 test to ensure tools and resources are added to the mcp server.