Skip to content

AGENTS.md

Latest commit

 

History

History
36 lines (30 loc) · 5.39 KB

AGENTS.md

File metadata and controls

36 lines (30 loc) · 5.39 KB
Raw

System-Wide Recommendations for Agent Execution

1. Environment and Virtual Environment Setup

  • Activate the venv in the repository to run python: Always execute source .venv/bin/activate (or .venv\Scripts\activate on Windows) before running any Python commands. This ensures all dependencies are resolved correctly and the project is isolated.
  • Use uv run for direct execution: When running scripts without pre-activating the venv, use uv run python <script> or uv run pytest --ignore=tests/integration to leverage the virtual environment automatically.
  • Verify Python version: Ensure the Python version is 3.12 or higher (as specified in .python_version). Check with python --version after activating the venv.
  • Static type checking - we use mypy for static type checking of the CodeBoarding repo, we avoid the typing library where possible and use the default library types: dict, set, list etc. for Optional we use the | None notation.

2. Dependency and Repository Navigation

  • Always use relative paths from repository root: Reference files using paths like src/components/file.ts or agents/tools/module.py relative to /Users/svilen/Documents/Projects/CodeBoarding/. This ensures consistency across agent execution and makes file references portable.
  • Reference code locations with line numbers: When citing specific functions or code blocks, use the format file_path:line_number (e.g., main.py:45). For multiple tool calls that depend on file paths, complete sequential read/glob operations first before referencing results.
  • Check .env configuration: The .env file (generated by setup.py) contains critical runtime configuration including LLM API keys, repository paths, and monitoring settings. Always verify .env exists and is properly configured before executing analysis pipelines.

3. Code Quality and Testing Standards

  • Run tests with coverage requirements: Execute uv run pytest --cov=. --cov-report=term --cov-fail-under=80 --ignore=tests/integration to validate changes. The project enforces an 80% minimum code coverage threshold.
  • Format and lint before commits: Run uv run black . (line length: 120) and uv run mypy . to ensure code quality. These are enforced in pre-commit hooks and GitHub CI/CD workflows.
  • Respect project structure: Code is organized by functional domain (e.g., agents/, static_analyzer/, output_generators/, monitoring/). Place new code in the appropriate directory and follow existing module patterns.
  • Add imports at the top of the file: avoid function or class level imports - only consider them if they have significant impact on the execution.
  • Keep comments and docstrings terse: write a one-line summary. Add a short Why: line only when the rationale is non-obvious. Do NOT narrate diff history ("Previously X did Y"), name internal bug tickets ("V4 reproducer", "Bug C"), reference line numbers in third-party files (they rot), or re-state what type hints already say. If the prose is longer than the code it documents, delete the prose. See REVIEW.md §10 "Comment & Docstring Bloat" for the full checklist.
  • Don't re-paste module docstrings across submodules: a package-layout explanation belongs once in __init__.py, not copied into every sibling file.
  • Test docstrings should add information: if a test is named test_rejects_none, the docstring """Test that None is rejected.""" is pure noise — delete it. Only add a docstring when there's a non-obvious reason the test exists.

4. Execution Flow and Tool Patterns

  • Understand the analysis pipeline: CodeBoarding processes repositories in stages: ProjectScanner → StaticAnalyzer (via LSP clients) → DiagramGenerator (LLM agents) → Output generators. When investigating issues, trace through this pipeline in order.
  • Multiple LLM providers supported: The system supports OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, Ollama, and others. Configuration is provider-agnostic via environment variables; verify the correct provider is set in .env.
  • Language Server Protocol (LSP) integration: Static analysis runs via LSP servers configured in static_analysis_config.yml. Supported languages include Python, TypeScript, Go, PHP, and Java. LSP servers are installed by setup.py.

5. Git Workflow and Branch Management

  • Main branch is main: When creating PRs, the base branch is main. The current working branch for agent operations should respect this structure.
  • Commit messages should be descriptive: Reference related issues and describe the "why" rather than just the "what". Follow existing commit patterns in the repo history.
  • Run pre-commit hooks locally: Execute git commit with the pre-commit hooks enabled to catch formatting and type errors before pushing. This mirrors the CI/CD validation.

6. Output and Logging

  • Logging is centralized: Review logging_config.py for logging configuration. Structured logging is used throughout the project; integrate logs into this system rather than using ad-hoc print statements.
  • Multiple output formats supported: The project generates Markdown, HTML, MDX, and Sphinx documentation. When adding features, consider all output generators if they are affected.
  • Monitor execution stats: The monitoring/ directory provides StreamingStatsWriter for tracking LLM usage and performance metrics. Use this for tracking long-running operations.