AI_Agent_Guidelines

AI Agent Development Guidelines for MARSYS Repository

These guidelines MUST be followed by any AI agent generating or modifying code within this repository. They complement Contributing_Rules.instructions.md and Framework_Development_Guide.instructions.md. Failure to adhere to these guidelines may result in incorrect, incoherent, or structurally unsound code.

1. Mandatory Pre-computation Analysis & Contextual Understanding

1.1. Vigilant Code Exploration: - Before modifying any existing file or writing new code that interacts with other modules, an agent MUST thoroughly examine all directly relevant source files. - If a file A imports a module, class, or function from file B (e.g., from marsys.module_b import MyClass), the agent MUST request to read and understand the relevant sections of file B (e.g., src/module_b.py) before making changes to file A or implementing interactions with MyClass. - For any task involving a specific class or function, the agent MUST locate its definition and analyze its existing usages (e.g., using list_code_usages) to understand its role, expected inputs/outputs, and interaction patterns. - Agents MUST utilize tools like read_file, semantic_search, grep_search, and list_code_usages proactively and extensively to gather this understanding. Do NOT rely solely on provided snippets or prior knowledge without verification against the current codebase.

1.2. Assumption Declaration: - If, after diligent effort, certain aspects of the codebase remain unclear or unverified, the agent MUST explicitly state any assumptions made about that code before proceeding. If critical information is missing, the agent SHOULD request clarification.

2. Structured Planning & Architectural Integrity

2.1. Mandatory Pre-Implementation Plan: - Before generating any code for modifications or new features, an agent MUST formulate and present a concise plan. - This plan MUST include: - A list of all files to be created. - A list of all files to be modified. - A clear justification for the choice of these files, explicitly referencing the project's established directory structure and module responsibilities (e.g., "New data processing utilities should be in src/utils/data_processing.py, not directly within an agent's file unless strictly local and private to that agent."). - A brief description of the intended changes or additions for each affected file.