githits-cli AGENTS.md

githits Agent Instructions

GitHits companion for the backend - provides MCP server and command-line tools for code example search.

We strive to produce high quality code that can easily be maintained. Focus is on long term development speed, not on quick wins.

This document contains the most important instructions that need to be kept always in context.

General

• Use very concise output and neutral tone
• If unclear about anything or stuck, please stop and ask for clarification
• Always verify assumptions
• Don't jump into coding, plan and assess the impact first
• Read more detailed documentation when needed
• Remember your MCP tools and use them when needed

Architecture

Philosophy: "Create architecture that is performant and easy to test"

• Focus on building structures that are performant and scalable
• Build architecture that is easy to test
• Isolate functionality into sensible small modules
• Follow single responsibility principle
• Prefer public helper modules to lots of private methods
• Use dependency injection for external services (REST client, etc.)
• Do not eagerly validate network/proxy/environment configuration while constructing command dependencies when the command has local-only or no-network paths. Defer validation until the first network operation and add regression tests for malformed env values on local paths.
• For MCP/agent-facing tools, avoid coupled optional flags and default-true booleans. Design schemas for real agent calls, including empty strings, empty arrays, and explicit false values.
• For MCP tool discovery, treat the tool name plus the first 80 description characters as a standalone selection surface. A verified Claude Desktop connector session exposed only that context during unguided tool selection; connector descriptions and MCP server instructions did not reach it. Lead with the natural user question and the tool's distinct job, treat 80 characters as a ceiling rather than a target, and keep registry counts/lists, argument mechanics, and follow-up routing after that boundary. Do not rely on neighboring tools for context. Add first-80 contract tests and run descriptor-only agent evals for description changes.
• For GraphQL/API-backed tools, treat minimal data fetching as part of the tool contract. Before adding or changing selected fields, compare the query against every consumer (text, verbose, JSON, MCP, CLI, and internal callers), use conditional fields or separate queries for mode-specific data, and add tests that assert the wire variables/selections for compact and detailed modes.