rag-manager/AGENTS.md

Claude Code Instructions - Python Development Standards

Environment Setup

• Virtual Environment: Always activate the virtual environment at .venv/bin/activate before any operations
• Package Management: Use uv exclusively for package management (not pip, poetry, or conda)
• Pre-execution: Always activate venv before running make targets or any Python commands

Type Safety & Linting Standards

Forbidden Practices

• Type Suppression: Using # type: ignore is strictly forbidden
• Generic Types: Using Any as a type is forbidden unless absolutely no other option exists
• Lint Circumvention: Never skip, circumvent, bypass, avoid, ignore, or sidestep precommit checks and lint errors
• Precommit Bypass: Using --no-verify to skip precommit checks is absolutely forbidden

Type Annotation Requirements

• Use modern typing with specific, descriptive types
• Prefer union types (str | None) over Optional[str] (Python 3.10+)
• Use generic type parameters for collections: list[str], dict[str, int]
• Leverage typing.Protocol for structural typing when appropriate
• Use typing.Final for constants
• Apply @overload for functions with multiple valid signatures

Linting Tools

• Primary Linter: Use Pyright (Pylance) for type linting
• Code Quality: Address all refactorlint suggestions without exception
• Error Handling: Never skip linter errors and failed tests unless explicitly instructed otherwise

Code Architecture & Design

File Organization

• Size Limit: If a file exceeds 700 lines, convert it into a package in its own self-contained directory
  • Example: foo.py becomes foo/ with __init__.py and sub-modules
• Module Creation: Creating new files and modules is forbidden without valid justification and explicit approval
• Code Reuse: Enabling redundancy is strictly forbidden
  • Recursively inspect neighboring/adjacent/tangential files and folders
  • Ensure reuse of existing code instead of creating new implementations

Implementation Standards

• No Shortcuts: Taking shortcuts or circumventing implementation design is forbidden
• Complete Implementation: If task 1 requires subtask C, then subtask C becomes part of the requirements
• No TODOs: Do not leave TODO comments; build the functionality instead
• Model Names: Do not change language model names (training data may not reflect current resources)

Code Style Conventions

Function Design

• Inline Returns: Use inline variable returns as functions to keep code neat
• Single Responsibility: Functions should have one clear purpose
• Pure Functions: Prefer pure functions where possible
• Named Expressions: Use walrus operator (:=) for complex conditions (addressing use-named-expression)

Control Flow Patterns

• Simplify Comparisons: Use direct length checks instead of comparing to zero (if items: not if len(items) > 0)
• Boolean Logic: Simplify boolean comparisons (if flag: not if flag is True)
• Conditional Merging: Merge nested if statements when logical
• Early Returns: Use guard clauses and early returns to reduce nesting
• Loop Optimization: Hoist statements from loops when possible

Data Structures

• Collections: Use appropriate collection types (set() for uniqueness, dict for mappings)
• Comprehensions: Prefer list/dict/set comprehensions over loops when readable
• Constant Sums: Use sum() for adding sequences of numbers
• Set Operations: Convert collections to sets for membership testing when appropriate

Error Handling

• Specific Exceptions: Raise specific errors instead of generic exceptions
• Custom Exceptions: Create domain-specific exception classes when needed
• Exception Chaining: Use raise ... from ... for exception chaining
• Context Managers: Use context managers for resource management

Testing Standards

Test Structure

• No Loops: Never use loops in tests (addressing no-loop-in-tests)
• No Conditionals: Never use conditional statements in tests (addressing no-conditionals-in-tests)
• Assertion Clarity: Use specific assertions (assert x == y not assert True)
• Test Isolation: Each test should be independent and atomic
• Module Imports: Do not import test modules in production code (addressing dont-import-test-modules)

Test Patterns

• Arrange-Act-Assert: Follow the AAA pattern consistently
• Parameterization: Use pytest.mark.parametrize for multiple test cases
• Fixtures: Create reusable fixtures for common test setup
• Mocking: Use appropriate mocking for external dependencies

Documentation Standards

Docstring Requirements

• Imperative Style: Write docstrings imperatively with proper punctuation
• Completeness: Document all public functions, classes, and modules
• Examples: Include usage examples in docstrings when helpful
• Type Information: Docstrings should complement, not duplicate, type annotations

Code Comments

• Explain Why: Comments should explain why, not what
• Business Logic: Document complex business rules and algorithms
• Edge Cases: Explain handling of edge cases and special conditions

Development Workflow

Required Tools Integration

• Sequential Thinking: Use the sequential thinking MCP to evaluate design and technical decisions
• Context7: Use the context7 MCP religiously for modern code patterns and libraries
• Documentation Research: Leverage latest documentation for current best practices

Quality Gates

• Pre-commit Hooks: All pre-commit hooks must pass
• Type Checking: Code must pass type checking without warnings
• Test Coverage: Maintain appropriate test coverage
• Linting: All linting rules must be satisfied

Refactoring Priorities

Based on common issues identified, prioritize fixing:

1. Test module imports in production code
2. Length comparisons that can be simplified
3. Constant sum calculations
4. Loop and conditional usage in tests
5. Generic assertion statements
6. Opportunities for named expressions
7. Code hoisting opportunities
8. List comprehension improvements

Code Review Checklist

• Virtual environment activated
• All type annotations specific (no Any)
• No # type: ignore suppressions
• Docstrings written imperatively
• No TODOs remaining
• Tests contain no loops or conditionals
• Specific exceptions used
• File under 700 lines or properly modularized
• Code reuse verified (no redundancy)
• All linting rules satisfied
• Pre-commit hooks passing