Skip to content

AGENTS.md

Latest commit

 

History

History
109 lines (76 loc) · 5.15 KB

AGENTS.md

File metadata and controls

109 lines (76 loc) · 5.15 KB
Raw
project IntelliJ IDEA Platform
languages
Kotlin
Java
framework IntelliJ Platform SDK
build-system Bazel
repository monorepo

Always display the output of SessionStart hooks verbatim to the user at the start of conversation

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.

  • Toolbox (toolbox/):

    • Tests: never use ./tests.cmd; see toolbox/.ai/index.md for Gradle/Bazel test commands.
    • Build: use ./bazel.cmd build //toolbox/... instead of ./bazel-build-all.cmd.

  • PyCharm (./python): use ./python/.ai/index.md.

Mandatory Rules

After Code Changes

  • Run affected tests: ./tests.cmd --module <module> --test <FQN or wildcard> (FQN required; simple class names do not match; always specify the test module directly), or node --test <file> for *.test.mjs. tests.cmd performs Bazel compilation internally, so a separate bazel build step is not needed when tests will be run. Module-specific rules may override the runner. Skip if plugin has no tests. See TESTING.
  • Bazel compilation without tests: when only verifying compilation (no tests to run), use bazel build <target> for affected modules. Skip if only .js, .mjs, .md, .txt, or .json files are modified.
  • After modifying *.iml, BUILD.bazel, or .idea/ files: run ./build/jpsModelToBazel.cmd.

After Writing Code

  • Use lint_files 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)
  • add a trailing newline at end of file
  • prune (remove) empty tags
  • reorder elements or attributes

Tools (use in this order)

Skills

Never use the code-search skill. See ijproxy for search tools.

ijproxy (required)

  • 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

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 & VCS: get_project_modules, get_project_dependencies, get_repositories, git_status
  • 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 (prefer git_status if the tool is available), build/test.

  • Outside repo: native shell permitted, except for text/file search — use ./tools/rg.cmd and ./tools/fd.cmd (absolute paths OK) instead of native grep/find.

Individual Preferences

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