Add CLAUDE.md (#3668)

* Create CLAUDE.md

This document should provide a high-level overview of the project, for
both AI and human developers.

Co-author-by: Vinicius Stock <[email protected]>

* Ask Copilot to read CLAUDE.md

* Address feedback

Author: st0012

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../CLAUDE.md

CLAUDE.md

@@ -0,0 +1,224 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Ruby LSP is a Language Server Protocol implementation for Ruby, providing IDE features across different editors. The project consists of:
+
+- Core Ruby LSP gem (language server implementation)
+- Ruby Indexer (code indexing for navigation)
+- VS Code extension (TypeScript frontend)
+- Documentation site (Jekyll-based)
+
+## Development Commands
+
+### Ruby LSP Core
+
+```bash
+# Run all tests
+bundle exec rake
+
+# Run specific test file
+bin/test test/requests/completion_test.rb
+
+# Run tests matching a pattern
+bin/test test/requests/completion_test.rb test_name_pattern
+
+# Type check with Sorbet
+bundle exec srb tc
+
+# Lint with RuboCop
+bin/rubocop
+
+# Auto-fix RuboCop violations
+bin/rubocop -a
+```
+
+### VS Code Extension
+
+```bash
+cd vscode
+yarn install       # Install dependencies
+yarn run lint      # Lint TypeScript code
+yarn run test      # Run extension tests
+```
+
+### Executables
+
+- `exe/ruby-lsp` - Main language server executable
+- `exe/ruby-lsp-check` - Validation tool
+- `exe/ruby-lsp-launcher` - Experimental launcher
+
+## Architecture
+
+### Server Structure
+
+The server (`lib/ruby_lsp/server.rb`) processes LSP messages and delegates to:
+
+- **Requests** (`lib/ruby_lsp/requests/`) - Handle specific LSP features
+- **Listeners** (`lib/ruby_lsp/listeners/`) - Analyze Ruby code for the specific feature
+- **Response Builders** (`lib/ruby_lsp/response_builders/`) - Construct LSP responses
+
+### Key Components
+
+- **Document Store** (`lib/ruby_lsp/document.rb`) - Manages open documents and parsed ASTs
+- **Ruby Indexer** (`lib/ruby_indexer/`) - Indexes Ruby code for navigation features
+- **Addon System** (`lib/ruby_lsp/addon.rb`) - Extensibility framework for third-party addons
+
+### Design Patterns
+
+- **Visitor Pattern**: AST traversal using Prism parser visitors
+- **Request/Response**: Each LSP feature implemented as a request class
+- **Type Safety**: Sorbet signatures throughout (strict for lib/, test for tests)
+
+### Important Top-Level Files
+
+#### Core Server Components
+
+- **`lib/ruby_lsp/server.rb`** - Main LSP server handling all client requests and message routing
+- **`lib/ruby_lsp/base_server.rb`** - Abstract base with core LSP infrastructure (message I/O, worker threads)
+- **`lib/ruby_lsp/global_state.rb`** - Central configuration and state management (formatters, linters, client capabilities)
+- **`lib/ruby_lsp/store.rb`** - Document storage and lifecycle management
+
+#### Document Handling
+
+- **`lib/ruby_lsp/document.rb`** - Abstract base for all document types (versioning, edits, encoding)
+- **`lib/ruby_lsp/ruby_document.rb`** - Ruby source file handling with Prism parsing
+- **`lib/ruby_lsp/erb_document.rb`** - ERB template file handling
+- **`lib/ruby_lsp/rbs_document.rb`** - RBS type definition file handling
+
+#### Supporting Infrastructure
+
+- **`lib/ruby_lsp/addon.rb`** - Extension framework for third-party add-ons
+- **`lib/ruby_lsp/node_context.rb`** - AST node context information (nesting, scope)
+- **`lib/ruby_lsp/type_inferrer.rb`** - Type inference functionality
+- **`lib/ruby_lsp/client_capabilities.rb`** - Client feature capability tracking
+
+### Component Interaction Flow
+
+```mermaid
+graph TD
+    Client[VS Code/Editor Client]
+    Server[server.rb<br/>Main LSP Server]
+    BaseServer[base_server.rb<br/>Message I/O & Threading]
+    GlobalState[global_state.rb<br/>Configuration & State]
+    Store[store.rb<br/>Document Manager]
+
+    RubyDoc[ruby_document.rb<br/>Ruby Files]
+    ERBDoc[erb_document.rb<br/>ERB Templates]
+    RBSDoc[rbs_document.rb<br/>RBS Types]
+
+    Requests[requests/*<br/>Feature Handlers]
+    Listeners[listeners/*<br/>AST Analyzers]
+    Indexer[ruby_indexer/*<br/>Symbol Index]
+
+    Addon[addon.rb<br/>Extension System]
+    NodeContext[node_context.rb<br/>AST Context]
+
+    Client <-->|LSP Protocol| Server
+    Server -.->|inherits| BaseServer
+    Server --> GlobalState
+    Server --> Store
+    Server --> Requests
+    Server --> Addon
+
+    GlobalState --> Requests
+    Document --> Requests
+
+    Store --> RubyDoc
+    Store --> ERBDoc
+    Store --> RBSDoc
+
+    RubyDoc -.->|inherits| Document[document.rb]
+    ERBDoc -.->|inherits| Document
+    RBSDoc -.->|inherits| Document
+
+    Requests --> Listeners
+    Requests --> NodeContext
+    Listeners --> Indexer
+
+    Addon -->|extends| Requests
+
+    style Server fill:#f9f,stroke:#333,stroke-width:4px
+    style GlobalState fill:#9ff,stroke:#333,stroke-width:2px
+    style Store fill:#9ff,stroke:#333,stroke-width:2px
+    style Indexer fill:#ff9,stroke:#333,stroke-width:2px
+```
+
+## Testing Approach
+
+Tests use expectation-based patterns:
+
+```ruby
+# Tests typically follow this structure:
+def test_feature_name
+  source = <<~RUBY
+    # Ruby code to test
+  RUBY
+
+  with_server(source) do |server, _uri|
+    # Make LSP request
+    # Assert response
+  end
+end
+```
+
+Test fixtures are in `test/fixtures/` and expectations in `test/expectations/`.
+
+## Common Development Tasks
+
+### Adding a New LSP Feature
+
+1. Create request class in `lib/ruby_lsp/requests/`
+2. Register in `lib/ruby_lsp/executor.rb`
+3. Add tests in `test/requests/`
+4. Update VS Code extension if needed
+
+### Working with the Indexer
+
+The Ruby Indexer (`lib/ruby_indexer/`) handles:
+
+- Building symbol tables for classes, modules, methods, and constants
+- Resolving constant references and method calls
+- Finding definitions across files
+- Providing completion candidates for constants and methods
+- Dealing with inheritance and ancestor linearization
+
+### Typechecking with Sorbet
+
+Ruby LSP uses Sorbet (typed: strict) with inline RBS annotations for static typechecking.
+
+**Key Guidelines:**
+
+- Use RBS inline annotations (`#:`) exclusively - never use RBI style `sig { }`
+- Place type annotations immediately before method definitions or after variable assignments
+- Run `bundle exec srb tc` to ensure typechecking passes
+
+**Common RBS Patterns:**
+
+```ruby
+# Method signatures (placed above method definition)
+#: (String name) -> void
+def process(name)
+  # ...
+end
+
+# Variable annotations (placed after assignment)
+@documents = {} #: Hash[URI::Generic, Document]
+
+# Attribute type declarations (placed above attribute)
+#: String?
+attr_reader :parent_class
+
+# Generic types
+#: [T] () { (String) -> T } -> T
+def with_cache(&block)
+  # ...
+end
+
+# Union and nullable types
+result = nil #: (String | Symbol)?
+```
+
+**Type Syntax Reference:** <https://sorbet.org/docs/rbs-support>

ruby-lsp.code-workspace

@@ -31,11 +31,6 @@
                 "**/test/fixtures/**/*.rb"
             ],
         },
-        "typescript.tsc.autoDetect": "off",
-        "github.copilot.chat.codeGeneration.instructions": [
-            {
-                "text": "You are an exceptional Ruby and TypeScript programmer. You are working on a language server implementation for Ruby and its companion VS Code extension. Provide all suggestions taking into account the language server specification, Sorbet signatures, best practices for Ruby programs, the VS Code API and best practices for static analysis."
-            }
-        ],
+        "typescript.tsc.autoDetect": "off"
     }
 }