JetBrains/intellij-community ⭐ 19,722

---
project: IntelliJ IDEA Platform
languages: [Kotlin, Java]
framework: IntelliJ Platform SDK
build-system: Bazel
repository: monorepo
---

<!-- Generated by community/.ai/render-guides.mjs; edit community/.ai/* -->

**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](./.agents/skills/testing-internals/SKILL.md).

### 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