openide/AGENTS.md

project, languages, framework, build-system, repository

project	languages	framework	build-system	repository
IntelliJ IDEA Platform	Kotlin Java	IntelliJ Platform SDK	Bazel	monorepo

Critical: These guidelines MUST be followed at all times.

Project Invariants

• The repository is a large monorepo with multiple IDE products and plugins.
• Module/plugin directories may contain their own AGENTS/CLAUDE instructions; follow them when present.
• *.iml files are the source of truth and auto-generate BUILD.bazel files.
• User-visible strings belong in *.properties for localization.

Module-specific rules

Special handling applies to the directories below. If a file you touch lives under one of these roots, you must activate that module's rules first (read the referenced doc before edits or reviews). These rules override general guidelines if they conflict.

• Product DSL (community/platform/build-scripts/product-dsl/): read ./.claude/rules/product-dsl.md before changing anything in this tree.

• IJ Proxy MCP server (community/build/mcp-servers/ij-proxy/):

  • Tests: run bun run build and bun test.
  • Bazel: do not run Bazel build and tests here.

• AI Assistant activation (plugins/llm/activation/):

  • Activation: follow plugins/llm/activation/.ai/guidelines.md before edits or reviews.

Mandatory Rules

After Code Changes

• Full Bazel compilation after code changes: run ./bazel-build-all.cmd via terminal command tool (not JetBrains MCP terminal). Skip if only .js, .mjs, .md, .txt, or .json files are modified.
• After modifying *.iml, BUILD.bazel, or .idea/ files: run ./build/jpsModelToBazel.cmd.
• Run affected tests: ./tests.cmd -Dintellij.build.test.patterns=<FQN or wildcard> (FQN required; simple class names do not match), or node --test <file> for *.test.mjs. Module-specific rules may override the runner. Skip if plugin has no tests. See TESTING-internals.

After Writing Code

• Use get_file_problems with errorsOnly=false to check files for warnings. Fix any warnings related to the code changes made. You may ignore unrelated warnings.

Repository-wide rules

Preserve IDE-serialized .iml files in canonical form. Do not:

• add comments
• auto-format
• normalize (structure or whitespace)
• prune (remove) empty tags
• reorder elements or attributes

Tools (use in this order)

ijproxy (required when available)

• Read: mcp__ijproxy__read_file
• Edit/Write: mcp__ijproxy__apply_patch
• Search symbols (preferred): mcp__ijproxy__search_symbol
• Find files (glob): mcp__ijproxy__search_file
• Search text: mcp__ijproxy__search_text
• Search regex: mcp__ijproxy__search_regex
• List dir: mcp__ijproxy__list_dir

jetbrains MCP (fallback)

Direct JetBrains MCP connection. Use when ijproxy unavailable.

• Read: get_file_text_by_path
• Edit: replace_text_in_file
• Write: create_new_file
• Find by glob: find_files_by_glob
• Find by name: find_files_by_name_keyword
• Search text: search_in_files_by_text
• Search regex: search_in_files_by_regex
• List dir: list_directory_tree

Client fallback (no MCP)

• No MCP: use ./tools/fd.cmd (file search) and ./tools/rg.cmd (text/regex search). These are the only allowed shell file ops on repo paths.

IDE-backed semantic tools

Available via ijproxy or JetBrains MCP. Use these for semantic operations; avoid manual search/replace when a refactor exists.

• Default to search_symbol (if available) for classes/methods/fields; use search_text/search_regex mainly for strings, comments, and non-symbol matches.
• Inspections & symbol info: get_file_problems, get_symbol_info
• Refactors: rename (ijproxy) / rename_refactoring (JetBrains MCP); use for renames and avoid manual search/replace.
• Formatting: reformat_file
• Concurrency checks: find_threading_requirements_usages, find_lock_requirements_usages
• Project structure: get_project_modules, get_project_dependencies, get_repositories
• Run configs: get_run_configurations, execute_run_configuration

Tooling rules

• When ijproxy MCP is available, all repo file ops (read/search/edit/write) MUST use ijproxy tools. Do not use JetBrains MCP or generic tools.

• Fallback tools (JetBrains MCP / client) are allowed only when ijproxy is unavailable.

• For repo edits, use mcp__ijproxy__apply_patch. Generic apply_patch is forbidden unless ijproxy is unavailable.

• Never shell for file ops (cat, sed, find, grep) on repo paths, except the client fallback (./tools/fd.cmd, ./tools/rg.cmd) when no MCP is available.

• Shell OK for: git, build/test.

• Outside repo: native shell permitted.

Individual Preferences

Local Preferences: @./.ai/local.md