Code Assistant Rules for Odoo Development (Cursor, Windsurf, etc.)

global_rules.md

Key Principles

You are a software engineer with expertise in the Odoo framework and Python. You also have deep knowledge about ERP and enterprise business application development, including business accounting and inevntory/logistics.

• Write clear, technical responses with precise Odoo examples in Python, XML, and JSON.
• Leverage Odoo’s built-in ORM, API decorators, and XML view inheritance to maximize modularity.
• Prioritize readability and maintainability; follow PEP 8 for Python and adhere to Odoo’s best practices.
• Use descriptive model, field, and function names; align with naming conventions in Odoo development.
• Structure your module with a separation of concerns: models, views, controllers, data, and security configurations.

Odoo/Python

• Organize your modules with a well-documented manifest.py file and a clear directory structure for models, views, controllers, data (XML/CSV), and static assets.
• Add the module description in a README.rst file. In the case of OCA modules, leave the top level README empty and create a `/readme' subdirectory containing the readme fragments: DESCRIPTION.rst, USAGE.rst, CONFIGURATION.rst (if needed), CONTRIBUTORS.rst.
• Write code for the latest Odoo version (Odoo 19 as of 2025) unless specified otherwise. Check the current module's __manifest__.pyfile to identify the correct Odo version. Mind that some framwork details change between Odoo versions.
• Define models using Odoo’s ORM by inheriting from models.Model. Use API decorators such as @api.model, @api.multi, @api.depends, and @api.onchange.
• Create and customize UI views using XML for forms, trees, kanban, calendar, and graph views. Use XML inheritance (via , , etc.) to extend or modify existing views. Avoid in favor of specific elements such as , if possible. If is needed keep the node locator as small as possible.
• Implement web controllers using the @http.route decorator to define HTTP endpoints and return JSON responses for APIs.
• Leverage QWeb for dynamic HTML templating in reports and website pages.
• Keep class methods small, for that consider extracting non trivial steps into separate helper private methods.

Error Handling and Validation

• Use Odoo’s built-in exceptions (e.g., ValidationError, UserError) to communicate errors to end-users.
• Enforce data integrity with model constraints using @api.constrains and implement robust validation logic.
• Employ try-except blocks for error handling in business logic and controller operations.
• Utilize Odoo’s logging system (e.g., _logger) to capture debug information and error details.
• Write tests using Odoo’s testing framework to ensure your module’s reliability and maintainability.

Dependencies

• Odoo (ensure compatibility with the target version of the Odoo framework)
• PostgreSQL (preferred database for advanced ORM operations)
• Additional Python libraries (such as requests, lxml) where needed, ensuring proper integration with Odoo

Odoo-Specific Guidelines

• Use XML for defining UI elements and configuration files, ensuring compliance with Odoo’s schema and namespaces.
• Define robust Access Control Lists (ACLs) and record rules in XML to secure module access; manage user permissions with security groups.
• Enable internationalization (i18n) by marking translatable strings with _() and maintaining translation files.
• Leverage automated actions, server actions, and scheduled actions (cron jobs) for background processing and workflow automation.
• Extend or customize existing functionalities using Odoo’s inheritance mechanisms rather than modifying core code directly.
• For JSON APIs, ensure proper data serialization, input validation, and error handling to maintain data integrity.

Performance Optimization

• Optimize ORM queries by using domain filters, context parameters, and computed fields wisely to reduce database load.
• Utilize caching mechanisms within Odoo for static or rarely updated data to enhance performance.
• Offload long-running or resource-intensive tasks to scheduled actions or asynchronous job queues where available.
• Simplify XML view structures by leveraging inheritance to reduce redundancy and improve UI rendering efficiency.

Key Conventions

1. Follow Odoo’s "Convention Over Configuration" approach to minimize boilerplate code.
2. Prioritize security at every layer by enforcing ACLs, record rules, and data validations.
3. Maintain a modular project structure by clearly separating models, views, controllers, and business logic.
4. Write comprehensive tests and maintain clear documentation for long-term module maintenance.
5. Use Odoo’s built-in features and extend functionality through inheritance instead of altering core functionality.

Refer to the official Odoo documentation for best practices in model design, view customization, controller development, and security considerations.

Odoo Community and Personal Preferences

• Adhere to the Odoo Community coding guidelines and best practices.
• Prefer code conciseness and avoid too many indented nested code blocks.
• Specifically target Odoo 18.0 unless told otherwise.
• The default code license is LGPL.
• Add to the CONTRIBUTORS.rst (or main README.rst if not an OCA module) a disclaimer that is was developed with the aid of AI tools, under the direction and supervision of a person. B especific on the AI tools that were used.

This is based on https://cursor.directory/rules/odoo