update instructions

Author: pavel-kirienko

AGENTS.md

@@ -0,0 +1,20 @@
+# Instructions for clankers
+
+When reading source files, ingest them in their entirety instead of relying on search/grep tools.
+
+Read `README.md` and `CONTRIBUTING.rst` first.
+
+When implementing functional code changes, be sure to read the DSDL specification in <https://github.com/OpenCyphal/specification>.
+
+## Project Structure & Module Organization
+
+- Core library code lives in `pydsdl/`.
+- Key internal subpackages are `pydsdl/_expression/`, `pydsdl/_serializable/`.
+- Vendored dependencies are under `pydsdl/third_party/` (treat as external code; modify only when intentionally syncing).
+- Tests are mostly co-located with implementation. Larger suites are in `pydsdl/_test*.py`, they are never imported.
+- Documentation sources are in `docs/`.
+- Test and release automation is in `noxfile.py` and `.github/`.
+
+## Commit & Pull Request Guidelines
+
+Provide detailed commit messages explaining the rationale behind the changes. Aim for a brief title with a following expanded description explaining what has been done and why was it necessary.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.rst

@@ -3,10 +3,12 @@
 Development guide
 =================
 
-This document is intended for library developers only.
+This document is intended for library developers and AI agents only.
 If you just want to use the library, you don't need to read it.
 
-Development automation is managed by Nox; please see ``noxfile.py``.
+Development automation is managed by Nox; please read ``noxfile.py``.
+
+The coding style is PEP8 with max line length 120 characters.
 
 
 Writing tests
@@ -26,18 +28,16 @@ outside of test-enabled environments.
         import pytest  # OK to import inside test functions only (rarely useful)
         assert get_the_answer() == 42
 
+For targeted test runs: ``pytest pydsdl -k _unittest_whatever -v``.
+
 
 Supporting newer versions of Python
 +++++++++++++++++++++++++++++++++++
 
-Normally, this should be done a few months after a new version of CPython is released:
-
 1. Update the CI/CD pipelines to enable the new Python version.
 2. Update the CD configuration to make sure that the library is released using the newest version of Python.
 3. Bump the version number using the ``.dev`` suffix to indicate that it is not release-ready until tested.
 
-When the CI/CD pipelines pass, you are all set.
-
 
 Releasing
 +++++++++