diff --git a/.claude/rules/trino-config-properties.md b/.claude/rules/trino-config-properties.md
new file mode 100644
index 00000000000..f4995a5cdb2
--- /dev/null
+++ b/.claude/rules/trino-config-properties.md
@@ -0,0 +1,37 @@
+---
+paths:
+  - "**/*Config.java"
+  - "**/*SessionProperties.java"
+---
+
+# Trino — configuration and session properties
+
+Naming:
+- Config property names use **dashes**, e.g. `hive.max-partitions-per-scan`.
+- Session property names use **snake_case**, e.g. `max_partitions_per_scan`.
+
+Adding a property:
+- Every `@Config` setter gets an `@ConfigDescription("…")`.
+- Every session property registration includes a description.
+- Credentials and other secrets get `@ConfigSecuritySensitive` so values are redacted in logs
+  and info endpoints.
+
+Renaming a config:
+- Add a `@Deprecated` setter with `@LegacyConfig(value = "old.name", replacedBy = "new.name")`
+  that writes to the same field as the new `@Config("new.name")` setter. The old name keeps
+  working as a backward-compatible alias.
+
+Removing a config:
+- Add the current name **and** any `@LegacyConfig` names to `@DefunctConfig` on the class so
+  startup fails loudly if the config is still set.
+- Remove the matching session property from `SystemSessionProperties.java` (or the connector's
+  session-properties class) if one exists.
+
+Testing a new config:
+- Add a matching `TestMyConfig` using Airlift's `ConfigAssertions` — see existing `Test*Config`
+  classes for the `testDefaults()` / `testExplicitPropertyMappings()` pattern.
+
+Other conventions:
+- Validation annotations (`@NotNull`, `@Min`, `@MinDuration`, etc.) go on setters, not fields.
+- Don't store the config object as a field — read values in the constructor and keep those
+  instead.
diff --git a/.gitignore b/.gitignore
index e94cc66740f..cb939110018 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,4 +34,5 @@ product-test-reports
 **/dependency-reduced-pom.xml
 core/trino-web-ui/src/main/resources/webapp/dist/
 .node
-.claude
+.claude/settings.local.json
+.claude/worktrees/
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000000..9aa72d4cd65
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,40 @@
+# Trino — Claude guidance
+
+**Before writing Java code, you must first read [`.github/DEVELOPMENT.md`](.github/DEVELOPMENT.md)
+in full** — it's the authoritative source for code-style rules (mocks, `var`, switch statements,
+method naming, `format()`, `TrinoException` error codes, AssertJ, Guava immutables, and more).
+This file intentionally does not duplicate those rules; skipping the read means missing them.
+Violations are also caught mechanically by modernizer
+([`.mvn/modernizer/violations.xml`](.mvn/modernizer/violations.xml)), checkstyle (from Airbase),
+and IntelliJ inspections via `mcp__idea__get_file_problems`.
+
+For other topics not covered here (Web UI build, release process, Vector API, IDE setup rationale),
+see the same `DEVELOPMENT.md`.
+
+## JetBrains MCP server
+
+Trino is developed in IntelliJ. If you run Claude Code with the JetBrains MCP server enabled,
+the assistant can drive the IDE directly. Install: https://github.com/JetBrains/mcp-jetbrains.
+
+When available, Claude should prefer these over shell equivalents:
+- `mcp__idea__reformat_file` after Java edits — applies the Airlift formatter; Claude cannot
+  reproduce it by hand.
+- `mcp__idea__get_file_problems` before committing — surfaces IntelliJ inspection results
+  (error-prone, unused imports, nullability) without a full Maven build.
+- `mcp__idea__search_symbol` / `mcp__idea__get_symbol_info` for symbol navigation in a codebase
+  with many overloaded names like `Metadata`, `Session`, `Block`.
+- `mcp__idea__rename_refactoring` for API renames — safer than text substitution.
+
+## Java formatting
+
+Run `mcp__idea__reformat_file` after every Java edit — it applies the Airlift scheme imported into
+IntelliJ. Rules not covered by the formatter:
+
+- No wildcard imports (e.g. `import io.trino.spi.*`) — checkstyle catches these on build; easier
+  to avoid writing them.
+- Braces required around single-statement `if` / `for` / `while` bodies — the formatter does not
+  add missing braces.
+- No `@author` in JavaDoc — commit history is the record.
+
+Topic-specific conventions live under [`.claude/rules/`](.claude/rules/) and auto-load when Claude
+reads matching files (e.g. `*Config.java` triggers the config-properties rule).