arxiv-smart-mcp: Instructions file for Codex

Development Rules for arxivsmart

This file provides guidance to AI agents and AI-assisted development tools when working with this project. This includes Claude Code, Cursor IDE, GitHub Copilot, Windsurf, and any other AI coding assistants.

General Coding Principles

• Never assume any default values anywhere
• Always be explicit about values, paths, and configurations
• If a value is not provided, handle it explicitly (raise error, use null, or prompt for input)

Git Commit Guidelines

IMPORTANT: When creating git commits in this repository:

• NEVER include AI attribution in commit messages
• NEVER add "Generated with [AI tool name]" or similar phrases
• NEVER add "Co-Authored-By: [AI name]" or similar attribution
• NEVER run git add -A or git add . - always stage files explicitly
• Keep commit messages professional and focused on the changes made
• Commit messages should describe what changed and why, without mentioning AI assistance
• ALWAYS run git push after creating a commit to push changes to the remote repository
• NEVER use git -C <path> — always run git commands from the project root directory

Testing

• After every change to the code, the tests must be executed
• Always verify the service runs correctly with just start after modifications

Python Execution Rules

• Python code must be executed only via uv run ...
  • Example: uv run src/main.py
  • Never use: python src/main.py or python3 src/main.py
• The virtual environment must be created and updated only via uv sync
  • Never use: pip install, python -m pip, or uv pip
• All dependencies must be managed through uv and declared in pyproject.toml

Justfile Rules

• All Python execution in the justfile uses uv run, never python directly
• Use just init to set up the project
• Use just start to start the arxivsmart service (foreground)
• Use just stop to stop the running service
• Use just status to check service status and configuration
• Use just destroy to remove the virtual environment
• Use just help to see all available recipes with descriptions
• Use just (with no arguments) to see a list of all recipes
• Use just ci to run all validation checks (verbose)
• Use just ci-quiet to run all validation checks (silent, fail-fast)