Modify CLAUDE.md for slang project better (#7720)

This PR modified CLAUDE.md to avoid common mistakes that may waste the tokens.

Currently what we have is a default CLAUDE.md that gets generated automatically with "/init" and some of the information are outdated.

Removing the claude file edit hook, because ./extras/formatting.sh doesn't take an individual file name as its input.

1 files changed, 208 insertions, 185 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 8a01904db..c07b829f8 100755
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,209 +2,232 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Essential Build Commands
+Reference other instruction files as well:
+- `.github/copilot-instructions.md`
+- `.github/workflows/claude.yml`
 
-**Configure and build (recommended):**
-```bash
-cmake --preset default
-cmake --build --preset releaseWithDebugInfo  # or --preset debug, or --preset release
-```
-
-**Alternative Visual Studio workflow:**
-```bash
-cmake --preset vs2022  # or vs2019
-cmake --build --preset releaseWithDebugInfo
-```
+## Build System and Common Commands
 
-**Quick release build and package:**
-```bash
-cmake --workflow --preset release
-```
+**IMPORTANT:** On Windows, always use `cmake.exe` (not `cmake`) to ensure proper GPU test execution. Using `cmake` without the `.exe` extension may invoke WSL's cmake, which cannot run GPU tests.
 
-**Build only generators for cross-compilation:**
+### Building the Project
 ```bash
-cmake --workflow --preset generators --fresh
-```
-
-## Testing Commands
-
-**Run all tests:**
-```bash
-build/Release/bin/slang-test
-# or for debug builds:
-build/Debug/bin/slang-test
-```
-
-**Run specific test categories:**
-```bash
-slang-test -category smoke    # Basic smoke tests
-slang-test -category quick    # Quick tests  
-slang-test -category full     # Full test suite
-slang-test -category compute  # Compute shader tests
-```
-
-**Run tests with parallel execution:**
-```bash
-slang-test -use-test-server -server-count 8
-```
+# Configure with default settings (Ninja Multi-Config)
+cmake --preset default
 
-**Run specific API tests:**
-```bash
-slang-test -api vk           # Vulkan only
-slang-test -api dx12         # DirectX 12 only
-```
+# Configure with visual studio 2022 settings (Preferred on Windows)
+cmake.exe --preset vs2022
 
-**Full CI-style test run:**
-```bash
-slang-test -use-test-server -server-count 8 -category full -expected-failure-list tests/expected-failure-github.txt
+# Build Release/Debug binaries.
+# It can take from 5 minutes to 20 minutes depending on the machine.
+cmake --build --preset debug # Debug binary
+cmake --build --preset release # Release binary
 ```
 
-**Run single test:**
-```bash
-slang-test tests/compute/array-param
-```
+### Testing
+slang-test must run from repository root
 
-## Core Architecture Overview
-
-### Main Compilation Pipeline
-- **Front-end**: Source → AST → IR (with semantic checking and lowering)
-- **Back-end**: IR → Optimized IR → Target Code Generation
-
-### Key Source Directories
-
-**`source/core/`** - Foundation utilities, platform abstraction, collections, memory management
-
-**`source/compiler-core/`** - Shared compiler infrastructure
-- Lexical analysis, diagnostics, source locations
-- Downstream compiler integration (DXC, FXC, GLSLANG)
-- Artifact management and JSON utilities for tooling
-
-**`source/slang/`** - Main compiler implementation
-- `slang-parser.cpp` - Recursive descent parser
-- `slang-ast-*.cpp` - Abstract Syntax Tree and type system
-- `slang-check-*.cpp` - Semantic checking and type checking
-- `slang-ir*.cpp` - Intermediate representation and optimization passes
-- `slang-emit-*.cpp` - Target-specific code generators (HLSL, GLSL, SPIR-V, Metal, etc.)
-- `slang-lower-to-ir.cpp` - AST to IR transformation
-
-### IR System Characteristics
-- **SSA Form**: Single Static Assignment with block parameters
-- **Instruction-based**: Everything is an instruction (types, constants, operations)
-- **Typed IR**: Every instruction has a type
-- **Global Deduplication**: Types and constants automatically deduplicated
-
-### Code Generation Targets
-- `slang-emit-hlsl.cpp` - HLSL generation
-- `slang-emit-glsl.cpp` - GLSL generation  
-- `slang-emit-spirv.cpp` - Direct SPIR-V bytecode
-- `slang-emit-metal.cpp` - Metal Shading Language
-- `slang-emit-wgsl.cpp` - WebGPU Shading Language
-- `slang-emit-cuda.cpp` - CUDA C++ generation
-- `slang-emit-cpp.cpp` - Host C++ code generation
-
-## Key Build Configuration
-
-**CMake presets available:**
-- `default` - Ninja Multi-Config (recommended)
-- `vs2022` / `vs2019` - Visual Studio generators
-- `emscripten` - WebAssembly build
-- `generators` - Build only code generators
-
-**Important CMake options:**
-- `SLANG_ENABLE_TESTS=TRUE` - Enable test targets (default)
-- `SLANG_ENABLE_GFX=TRUE` - Enable graphics abstraction layer
-- `SLANG_ENABLE_SLANGC=TRUE` - Enable standalone compiler
-- `SLANG_LIB_TYPE=SHARED` - Build shared library (default)
-
-## Module and Generic System
-
-**Module compilation:**
-- Independent compilation with cross-module linking
-- Serialization support for caching and distribution
-- Built-in core modules for language features
-
-**Generics and interfaces:**
-- First-class generic types and functions
-- Interface-based programming with witness tables
-- Compile-time specialization and monomorphization
-
-## Development Notes
-
-**Language features:**
-- HLSL compatibility with Slang extensions
-- Automatic differentiation for neural graphics
-- Multi-target compilation (DX11/12, Vulkan, Metal, CUDA, CPU)
-- Capability system for platform feature management
-
-**Testing structure:**
-- Main tests in `tests/` directory
-- Categories: compute, autodiff, bugs, bindings, etc.
-- Expected failure lists for CI (`tests/expected-failure-*.txt`)
-
-**Cross-compilation:**
-First build generators for build platform, then configure with `SLANG_GENERATORS_PATH` pointing to them.
-
-## Debugging and Development Workflow
-
-**Using slangc for debugging:**
 ```bash
-# Basic compilation with target-specific output
-./build/Debug/bin/slangc -target cuda file.slang
-
-# Debug IR stages and optimization passes
-./build/Debug/bin/slangc -dump-ir -target cuda file.slang
+# Run all tests with multiple servers (takes from 10 to 30 minutes)
+./build/Release/bin/slang-test -use-test-server -server-count 8
 
-# HLSL output for debugging
-./build/Debug/bin/slangc -target hlsl file.slang -o output.hlsl
-```
+# Run specific test
+# The test file must be placed under "tests/" directory
+./build/Release/bin/slang-test tests/path/to/test.slang
 
-**Interactive debugging with slangi (interpreter):**
-```bash
-# Run bytecode interpreter for testing without GPU
-./build/Debug/bin/slangi file.slang
+# Run unit tests
+./build/Release/bin/slang-test slang-unit-test-tool/
 ```
 
-**Test-driven development:**
-```bash
-# CPU-based testing (no GPU required)
-slang-test tests/your-test.slang -cpu
-
-# Interpreter-based testing 
-slang-test tests/your-test.slang -slangi
+### Slang Command Line Usage
+**IMPORTANT:** Slang uses single dashes for multi-character options (not double dashes like most tools):
+- Use `-help` (not `--help`)
+- Use `-target spirv` (not `--target spirv`)
+- Use `-dump-ir` (not `--dump-ir`)
+- Use `-stage compute` (not `--stage compute`)
 
-# Test with specific backend
-slang-test tests/your-test.slang -api dx12  # or vk, metal, etc.
-```
+### AVOID These Debugging Options
+**DO NOT USE** these options as they are unmaintained, unreliable or unnecessary:
+- slangc with `-dump-ast`, `-dump-intermediate-prefix`, `-dump-intermediates`, `-dump-ir-ids`, `-serial-ir`, `-dump-repro`, `-load-repro` and `-extract-repro`.
+- slang-test with `-category` and `-api`
 
-## Code Formatting and Style
-
-**Before submitting changes:**
+### Code Formatting
 ```bash
-# Format code according to project standards
-./extras/formatting.sh
+# Format code before submitting PR
+./extras/formatting.sh --no-version-check --cpp --since HEAD
 ```
 
-**PR requirements:**
-- All PRs must be labeled "pr: non-breaking" or "pr: breaking"
-- Include regression tests under `tests/` directory
-- Breaking changes are rare and only for API/language compatibility issues
-
-## Test Structure and Patterns
+## Architecture Overview
+
+### Core Components
+
+**Compiler Pipeline**:
+- **Lexer** (`source/compiler-core/slang-lexer.cpp`): Tokenizes source code
+- **Preprocessor** (`source/slang/slang-preprocessor.cpp`): Handles #include, macros, conditionals
+- **Parser** (`source/slang/slang-parser.cpp`): Recursive descent parser producing AST
+- **Semantic Checker** (`source/slang/slang-check.cpp`): Type checking, name resolution, validation
+- **IR Generation** (`source/slang/slang-lower-to-ir.cpp`): Converts AST to Slang IR
+- **IR Passes** (`source/slang/slang-ir-*.cpp`): Optimization and lowering passes
+- **Code Emission** (`source/slang/slang-emit-*.cpp`): Target-specific code generation
 
-**Test file headers for different execution modes:**
-```bash
-# CPU execution (no GPU required)
-//TEST:COMPARE_COMPUTE(filecheck-buffer=CHECK):-output-using-type -cpu
-
-# Interpreter execution
-//TEST:INTERPRET(filecheck=CHECK):
-
-# HLSL compilation test
-//TEST(hlsl):COMPARE_HLSL: -entry main -target hlsl
-```
+**Key Directories**:
+- `source/core/`: Core utilities (strings, containers, file system, platform abstractions)
+- `source/compiler-core/`: Compiler infrastructure (diagnostics, downstream compilers)
+- `source/slang/`: Main compiler implementation (frontend, IR, backend)
+- `source/slangc/`: Command-line compiler tool
+- `tools/`: Development and testing tools
+- `include/`: Public API headers (`slang.h`, `slang-gfx.h`)
+- `external/`: - Third-party dependencies and submodules
+- `prelude/`: - Built-in language definitions and standard library
+- `examples/`: - Sample programs demonstrating Slang usage
+- `tests/`: - Comprehensive test suite
+- `docs/`: - Project documentation
+
+### Compilation Model
+
+**Key Concepts**:
+- **CompileRequest**: Bundles options, input files, and code generation requests
+- **TranslationUnit**: Collection of source files (HLSL: one per file, Slang: all files together)
+- **EntryPoint**: Function name + pipeline stage to compile
+- **Target**: Output format (DXIL, SPIR-V, etc.) + capability profile
+
+**Supported Targets**:
+- Direct3D 11/12 (HLSL output)
+- Vulkan (SPIR-V, GLSL output)
+- Metal (MSL output) - experimental
+- WebGPU (WGSL output) - experimental
+- CUDA/OptiX (C++ output)
+- CPU (C++ output, executables, libraries)
+
+## Development Workflow
+
+### Slang internal steps, as an example
+1. Update lexer for new tokens (slang-lexer.cpp)
+2. Extend parser for new syntax (slang-parser.cpp)
+3. Add semantic analysis (slang-check-*.cpp)
+4. Implement IR generation (slang-ir-*.cpp)
+5. Add code generation for each target backend
+6. Write comprehensive tests
+
+### Debugging tools
+
+#### slangc with `-dump-ir`
+slangc with `-dump-ir` option is most efficient way to investigate problems that can be observed at IR level.
+
+It will often require a use of `-target` and the most common combination is `-dump-ir -target spirv-asm`.
+When `-dump-ir` is used without `-target`, the compilation process may stop earlier than it should be.
+
+Since it dumps many lines, it will be good to store the result into a file for a further investigation.
+The dump prints multiple sections which of each is separated by `### ` header.
+Each section visualizes the IR state on multiple steps during the compilation.
+It is necessary to differentiate the information on one section from one section, because the issue might be observed at a specific section.
+
+#### slangc with `-target spirv-asm`
+slangc with `-target spirv-asm` is the most common way to see how the given slang shader is compiled into spirv code.
+
+When an environment variable, `SLANG_RUN_SPIRV_VALIDATION=1`, is set, it will also run a static SPIRV valdiation.
+
+You can skip the validation, if needed, with a command-line argument, `-skip-spirv-validation`.
+When SPIRV validation fails, the actual spirv code is not printed.
+You can skip the validation with the option and print the spirv code even when it fails the validation.
+
+#### slangc with `-target spirv-asm -emit-spirv-via-glsl`
+By default, slang uses `-emit-spirv-directly` and slang emits from slang shader to spirv directly.
+When `-emit-spirv-via-glsl` is used, slang will translate the input slang shader to glsl and let glslang to generate spirv code.
+This can be useful when we want to generate a reference spirv code for a comparison.
+
+### IR System
+- Slang uses a custom SSA-based IR (not LLVM)
+- IR instructions defined in `slang-ir-insts.h` (generated from Lua)
+- Extensive IR pass framework for optimization and lowering
+- Target-specific legalization passes before code emission
+
+### Language Server
+- Language Server Protocol implementation in `source/slang/slang-language-server.cpp`
+- Supports IntelliSense, completion, diagnostics, formatting
+- Used by VS Code and Visual Studio extensions
+
+### Module System
+- Slang supports separate compilation via modules
+- Modules can be compiled to IR and linked at runtime
+- Optional obfuscation for distributed modules
+- Core language features defined as modules in `prelude/`
+
+### Generated files
+- The enum values starting with `kIROp_` are defined in a generated file, `build/source/slang/fiddle/slang-ir-insts-enum.h.fiddle`
+
+### Git commit message
+- Don't mention Claude on the commit message
+
+## Cross-Platform Considerations
+
+**Supported Platforms**: Windows (x64/ARM64), Linux (x64/ARM64), macOS (x64/ARM64), WebAssembly
+
+**Platform Abstractions**: Use utilities in `source/core/` for file system, process management, platform detection
+
+**Graphics APIs**: Code generation supports all major APIs but runtime testing requires appropriate drivers/SDKs
+
+## Additional documents
+
+The most important documents are the end-user facing user-guide documents.
+And it can be found under `docs/user-guide/`.
+
+There is a dedicated repo, https://github.com/shader-slang/spec.git
+If needed, you should clone the repo under `external/` directory.
+
+### Formal Specification (`external/spec/specification/`)
+- `specification/index.bs` - Main specification document
+- `specification/types.md` - Type system specification
+- `specification/generics.md` - Generics and templates specification
+- `specification/interfaces.md` - Interface system specification
+- `specification/expressions.md` - Expression evaluation rules
+- `specification/declarations.md` - Declaration syntax and semantics
+- `specification/statements.md` - Statement execution semantics
+- `specification/checking.md` - Type checking rules
+- `specification/conversion.md` - Type conversion rules
+- `specification/overloading.md` - Overload resolution
+- `specification/lookup.md` - Name lookup rules
+- `specification/modules.md` - Module system
+- `specification/capabilities.md` - Capability system
+- `specification/autodiff.md` - Automatic differentiation
+- `specification/attributes.md` - Attribute system
+- `specification/lexical.md` - Lexical analysis
+- `specification/parsing.md` - Parsing rules
+- `specification/preprocessor.md` - Preprocessor behavior
+- `specification/execution.md` - Execution model
+- `specification/extensions.md` - Language extensions
+- `specification/subtyping.md` - Subtyping relationships
+- `specification/visibility.md` - Visibility and access control
+
+### Feature Proposals (`external/spec/proposals/`)
+**Template and Active Proposals:**
+- `000-template.md` - Template for new proposals
+- `001-where-clauses.md` - `where` clauses for generic constraints (Partially implemented)
+- `002-type-equality-constraints.md` - Type equality constraints in generics
+- `003-atomic-t.md` - Atomic operations and types
+- `004-initialization.md` - Initialization syntax improvements
+- `005-write-only-textures.md` - Write-only texture support
+- `007-variadic-generics.md` - Variadic generic types and functions (Implemented)
+- `008-tuples.md` - Tuple types built on variadic generics (Implemented)
+- `009-ifunc.md` - Function interface types for callbacks
+- `010-new-diff-type-system.md` - New automatic differentiation type system
+- `011-structured-binding.md` - Structured binding declarations
+- `012-language-version-directive.md` - Language version directives
+- `013-aligned-load-store.md` - Aligned memory load/store operations
+- `014-extended-length-vectors.md` - Extended vector length support
+- `015-descriptor-handle.md` - Descriptor handle types
+- `016-slangpy.md` - Python binding for Slang
+- `017-shader-record.md` - Shader record data structures
+- `018-packed-data-intrinsics.md` - Packed data manipulation intrinsics
+- `019-cooperative-vector.md` - Cooperative vector operations
+- `020-stage-switch.md` - Stage-specific code switching
+- `022-C++20-migration.md` - C++20 feature migration
+- `023-cooperative-matrix.md` - Cooperative matrix operations
+- `024-any-dyn-types.md` - Any and dynamic types
+- `025-lambda-1.md` - Lambda expressions with immutable capture (In Implementation)
+- `026-error-handling.md` - Error handling mechanisms
+- `027-tuple-syntax.md` - Tuple syntax improvements
+- `028-cooperative-matrix-2.md` - Extended cooperative matrix support
+- `029-conditional.md` - Conditional compilation features
+- `030-interface-method-default-impl.md` - Default interface method implementations (In Experiment)
 
-**Common test categories:**
-- `tests/compute/` - Compute shader tests
-- `tests/autodiff/` - Automatic differentiation tests  
-- `tests/bugs/` - Bug reproduction and regression tests
-- `tests/bindings/` - Resource binding tests