Claude Code Settings

Claude Code Settings

Guidance for Claude Code and other AI tools working in this repository.

AI Guidance

• After receiving tool results, carefully reflect on their quality and determine optimal next steps before proceeding. Use your thinking to plan and iterate based on this new information, and then take the best next action.
• For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
• Before you finish, please verify your solution
• Do what has been asked; nothing more, nothing less.
• NEVER create new files unless they're absolutely necessary for achieving your goal.
• ALWAYS prefer editing an existing file to creating a new one.
• NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
• Reuse existing code wherever possible and minimize unnecessary arguments.
• Look for opportunities to simplify the code or remove unnecessary parts.
• Focus on targeted modifications rather than large-scale changes.
• This year is 2026. Definitely not 2025.
• Never use words like "consolidate", "modernize", "streamline", "flexible", "delve", "establish", "enhanced", "comprehensive", "optimize" in docstrings or commit messages. Looser AI's do that, and that ain't you. You are better than that.
• Prefer rg over grep for better performance.
• Never implement defensive programming unless you explicitly tell the motivation for it and user approves it.
• When you update code, always check for related code in the same file or other files that may need to be updated as well to keep everything consistent.

MCP Tools

• Use mcp__tavily__tavily_search for web discovery, mcp__tavily__tavily_extract for specific URLs
• MongoDB MCP is READ-ONLY (no write/update/delete operations)
• For GitHub URLs, use mcp__github__* tools or gh CLI instead of web scraping

Python Coding

• Use Google-style docstrings:
  • Summary: Start with clear, concise summary line in imperative mood ("Calculate", not "Calculates")
  • Args/Attributes: Document all parameters with types and brief descriptions (no default values)
  • Types: Use union types with vertical bar int | str, uppercase letters for shapes (N, M), lowercase builtins list, dict, tuple, capitalize typing module classes Any, Path
  • Optional Args: Mark at end of type name (type, optional): Description...
  • Returns: Always enclose in parentheses (type), NEVER use tuple types - document multiple returns as separate named values
  • Sections: Optional minimal sections in order: Examples (using >>>), Notes, References (plaintext only, no new ultralytics.com links)
  • Line Wrapping: Wrap at specified character limit, use zero indentation in docstring content
  • Special Cases:
    • Classes: Include Attributes, omit Methods/Args sections, put all details in class docstring
    • __init__: Args ONLY, no Examples/Notes/Methods/References
    • Functions: Include Args and Returns sections when applicable
    • All test functions should be single-line docstrings.
    • Indent section titles like "Args:" 0 spaces
    • Indent section elements like each argument 4 spaces
    • DO NOT CONVERT SINGLE-LINE CLASS DOCSTRINGS TO MULTILINE.
    • Optionally include a minimal 'Examples:' section, and improve existing Examples if applicable.
    • Do not include default values in argument descriptions, and erase any default values you see in existing arg descriptions.
  • Omissions: Omit "Returns:" if nothing returned, omit "Args:" if no arguments, avoid "Raises:" unless critical
• Separation of concerns: If-else checks in main should be avoided. Relevant functions should handle inputs checks themselves.
• Super important to integrate new code changes seamlessly within the existing code rather than simply adding more code to current files. Always review any proposed code updates for correctness and conciseness. Focus on writing things in minimal number of lines while avoiding redundant trivial extra lines and comments. For instance don't do:

  # Generate comment report only if requested
  if include_comments:
      comment_report = generate_comments_report(start_date, end_date, team, verbose)
  else:
      comment_report = ""
      print("   Skipping comment analysis (disabled)")
  

  Instead do:

  comment_report = generate_comments_report(start_date, end_date, team, verbose) if include_comments else ""
  

• Understand existing variable naming, function importing, class method definition, function signature ordering and naming patterns of the given modules and align your implementation with existing patterns. Always exploit existing utilities/optimization/data structures/modules in the project when suggesting something new.
• Redundant duplicate code use is inefficient and unacceptable.
• Never assume anything without testing it with python3 -c "..." (don't create file)
• Always consider MongoDB/Gemini/OpenAI/Claude/Voyage API and time costs, and keep them as efficient as possible
• When using 3rd party package functions/classes, find location with python -c "import pkg; print(pkg.__file__)", then use Read tools to explore
• When running Python commands, run source .venv/bin/activate to activate the virtual environment before running any scripts or run with uv uv run python -c "import example"

Git and Pull Request Workflows

Commit Messages

• Format: {type}: brief description (max 50 chars first line)
• Types: feat, fix, refactor, docs, style, test, build
• Focus on 'why' not 'what' - one logical change per commit
• ONLY analyze staged files (git diff --cached), ignore unstaged
• NO test plans in commit messages

Pull Requests

• PR titles: NO type prefix (unlike commits) - start with capital letter + verb
• Analyze ALL commits with git diff <base-branch>...HEAD, not just latest
• Inline links: [src/file.py:42](src/file.py#L42) or [src/file.py:15-42](src/file.py#L15-L42)
• Self-assign with -a @me
• NO test plans in PR body
• Find reviewers: gh pr list --repo <owner>/<repo> --author @me --limit 5

Commands

• /github-dev:commit-staged - commit staged changes
• /github-dev:create-pr - create pull request