Initial AGENTS.md and CLAUDE.md with LLM agent instructions for the repo

CLAUDE.md

@@ -0,0 +1,90 @@
+# Context
+
+You are in the CPython repo helping work on the implementation of the Python
+language runtime and standard library itself.
+
+Use the `gh` tool to get information about an issue or PR in the repo.
+Including using the GraphQL API via `gh` when appropriate.
+
+Source files in this repo can be very long.  Check their size to consider if
+you really need to read the entire thing.
+
+If tools such as `rg` (ripgrep), `gh`, `jq`, or `pre-commit` are not found, ask
+the user to install them. ALWAYS prefer using `rg` rather than `find` or `grep`.
+
+# Expanding your knowledge
+
+* ALWAYS load a `.claude/pr-{PR_NUMBER}.md` or `.claude/branch-{branch_name_without_slashes}.md` file when you are told a PR number or when the current git branch is not `main`.
+* Keep the file up to date as an engineering notebook of your learnings and project state as you work on a task and after you commit. The goal of our notebook is to make it easier to pick up and resume work later.
+
+## Optional developer guides and PEPs
+
+* If `REPO_ROOT/../devguide/` exists, its `developer-workflow/` and `documentation/` subdirs contain detailed info on how we like to work on code and docs.
+* PEPs might exist in a `REPO_ROOT/../peps/` tree.
+
+# Source code
+
+* The runtime is implemented in C as are many of the core types and extension modules
+* The Python standard library (stdlib) itself lives in the `Lib/` tree
+* stdlib C extension modules live in the `Modules/` Tree
+* builtins, objects, and the runtime itself live in `Objects/` and `Python/`
+* NEVER edit files in a `**/clinic/**` subdirectory; those are generated by argument clinic
+* Unittests for everything live in the `Lib/test/` tree. Ex:
+   * `Lib/zipfile/` contains the code for the stdlib `zipfile` module
+   * `Lib/test/test_zipfile**` are tests for `zipfile`
+   * `Modules/_csv.c` contains the code for the stdlib `csv` module
+   * `Lib/test/test_csv.py` are tests for `csv`
+* C header files are in the `Include/` tree
+* Documentation is written in .rst format in `Doc/` - this is source for the public facing official Python documentation.
+* CPython internals are documented for maintainers in @InternalDocs/README.md.
+* Build time tools such as Argument Clinic live under the `Tools/` tree
+
+## Coding style
+
+* For C, follow PEP-7. For Python, follow PEP-8.
+* Be consistent with existing nearby code style unless asked to do otherwise.
+* NEVER leave trailing whitespace on any line.
+* ALWAYS preserve the newline at the end of files.
+* We do not autoformat code in this codebase. If the user asks you to run ruff format on a specific file, it can be found in `Doc/venv/bin/ruff`.
+* NEVER add Python type annotations to Python code in the `Lib/` tree.
+
+## Building
+
+ONLY build in a `build/` subdirectory that you create at the repo root.
+
+* Use sub-agents when running configure and make build steps
+* `REPO_ROOT` is the root of the cpython git repo
+* let `BUILD_DIR=REPO_ROOT/build`
+* Setup: `cd BUILD_DIR && ../configure --with-pydebug`
+* `make -C BUILD_DIR -j $(nproc)` will rebuild
+* Check what OS you are running on. Let `BUILT_PY=BUILD_DIR/python` or `BUILD_DIR/python.exe` on macOS (.exe is used to avoid a case insensitive fs name conflict)
+* If you are on Windows, ask the user how to build.
+
+## Running our built Python and tests
+
+* ALWAYS use sub-agents when running builds or tests
+* NEVER use `pytest`. CPython tests are `unittest` based.
+* use `BUILT_PY` to run the interpreter we've built
+* Individual test files can be run directly using `BUILT_PY Lib/test/test_csv.py`
+* `BUILT_PY -m test test_zipfile -j $(nproc)` will properly run all `Lib/test/test_zipfile` tests
+* `BUILT_PY -m test` supports a `--match TESTNAME_GLOB` flag to run specific tests, pass `--help` to learn its other capabilities.  NEVER try to pass `-k` as this is not pytest based, use `--match` instead.
+* `make -C BUILD_DIR clinic` will regenerate argument clinic generated code. Do this after you've edited a corresponding input .c file in a way that changes a C extension module function signature or docstring
+* `make -C BUILD_DIR test` will run the entire test suite. Do that sparingly. Focus on specific tests first and ask before running the entire test suite.
+* Some tests are packages rather than a single .py file. These require `load_tests()` logic in their `test_package/__init__.py` file in order to work via `BUILT_PY -m test` commands.
+* To collect Python code coverage from part of the test suite, use `BUILT_PY -m test -j $(nproc) --coverage test_name --coveragedir .claude/coverage_dir/`; this uses a `trace` based mechanism as implemented using libregrtest.
+
+## Common workflows
+
+* After editing C code: `make -C BUILD_DIR && BUILT_PY -m test relevant_tests`
+* After editing stdlib Python: `BUILT_PY -m test relevant_tests --match specific_test_name_glob` (no rebuild needed)
+* After editing .rst documentation: `make -C BUILD_DIR/Doc check`
+* Before committing: `make -C BUILD_DIR patchcheck && pre-commit run --all-files`
+
+### Debugging
+
+* For interactive debugging (pdb, lldb, or gdb) or when working on an interactive feature such as the REPL: control a tmux session to drive that.
+
+## Scratch space
+
+* NEVER create throw away idea exploration files in the top directory of the repo. Use a `.claude/sandbox/` directory for those. They will never be committed.
+