From 11b551c2befa7d9a8f4650b41794d9ea265ddc23 Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Sun, 4 Jan 2026 15:00:31 -0500
Subject: [PATCH] Add a CLAUDE.md (#22370)

## Summary

This is a starting point based on my own experiments. Feedback and
changes welcome -- I think we should iterate on this a lot as we go.
---
 CLAUDE.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..289f3bb944
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,64 @@
+# Ruff Repository
+
+This repository contains both Ruff (a Python linter and formatter) and ty (a Python type checker). The crates follow a naming convention: `ruff_*` for Ruff-specific code and `ty_*` for ty-specific code. ty reuses several Ruff crates, including the Python parser (`ruff_python_parser`) and AST definitions (`ruff_python_ast`).
+
+## Running Tests
+
+Run all tests (using `nextest` for faster execution):
+
+```sh
+cargo nextest run
+```
+
+Run tests for a specific crate:
+
+```sh
+cargo nextest run -p ty_python_semantic
+```
+
+Run a specific mdtest (use a substring of the test name):
+
+```sh
+MDTEST_TEST_FILTER="<filter>" cargo nextest run -p ty_python_semantic mdtest
+```
+
+Update snapshots after running tests:
+
+```sh
+cargo insta accept
+```
+
+## Running Clippy
+
+```sh
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+## Running Debug Builds
+
+Use debug builds (not `--release`) when developing, as release builds lack debug assertions and have slower compile times.
+
+Run Ruff:
+
+```sh
+cargo run --bin ruff -- check path/to/file.py
+```
+
+Run ty:
+
+```sh
+cargo run --bin ty -- check path/to/file.py
+```
+
+## Pull Requests
+
+When working on ty, PR titles should start with `[ty]` and be tagged with the `ty` GitHub label.
+
+## Development Guidelines
+
+- All changes must be tested. If you're not testing your changes, you're not done.
+- Get your tests to pass. If you didn't run the tests, your code does not work.
+- Follow existing code style. Check neighboring files for patterns.
+- Always run `uvx pre-commit run -a` at the end of a task.
+- Avoid writing significant amounts of new code. This is often a sign that we're missing an existing method or mechanism that could help solve the problem. Look for existing utilities first.
+- Avoid falling back to patterns that require `panic!`, `unreachable!`, or `.unwrap()`. Instead, try to encode those constraints in the type system.