diff --git a/.gitignore b/.gitignore
index f93ea891be3c6716c8af872e04a9452c0b02add5..44264c8ebf7f2e35d7841cec162a6029cd51539b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,9 @@
 phpcs.xml.dist
 phpstan.neon
 phpstan-baseline.neon
+
+# IDE
+.idea
+
+# AI tooling
+.claude
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000000000000000000000000000000000..818febbba096aeab5b69f6f106618e21f40f1ebe
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,20 @@
+# MCP Drupal Module Development Guidelines
+
+## Commands
+- **PHPUnit Tests**: `vendor/bin/phpunit modules/path/to/tests` (single test)
+- **Code Style Check**: `vendor/bin/grumphp run` or `vendor/bin/phpcs`
+- **Install Dependencies**: `composer install`
+- **Drupal Test**: `./vendor/bin/phpunit --testsuite Functional`
+
+## Code Style
+- Follow **Drupal Coding Standards** (enforced via PHPCS)
+- Use **PSR-4** autoloading with `Drupal\mcp` namespace
+- Add `declare(strict_types=1)` to all PHP files
+- Use **type hints** and **return types** consistently
+- **Class naming**: `CamelCase` with `Mcp` prefix (e.g., `McpPluginBase`)
+- **Method naming**: `camelCase` (e.g., `getTools()`)
+- **Interface naming**: Use `Interface` suffix (e.g., `McpInterface`)
+- Organize code into **PSR-4 namespaces** by feature
+- Use **PHPDoc** comment blocks for all classes/methods
+- Follow **Drupal plugin patterns** for extensions
+- Avoid debug functions (var_dump, print_r, etc.)
\ No newline at end of file
diff --git a/README.md b/README.md
index b6010b2810e3449cb604c95f38b272623c3aef06..5c57e66b12c400874fe6597894f310bb86a5e539 100644
--- a/README.md
+++ b/README.md
@@ -45,3 +45,6 @@ from your Drupal website.
 - This module is under active development and is not yet ready for production use.
 - Use at your own risk.
 - Everything is subject to change.
+
+## Context Priming
+Read README.md, docs/*, and run git ls-files to understand this codebase.