diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..0a41c24f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,32 @@
+# AGENTS.md
+
+Notes for coding agents and new contributors. [CONTRIBUTING.md](CONTRIBUTING.md) still applies, including its AI usage policy: agents may be used for bugfixes, unit tests and documentation, not for new features.
+
+## Layout
+
+- `src/MiniExcel.Core`, `src/MiniExcel.OpenXml`, `src/MiniExcel.Csv`: the v2 library. The entry point is `MiniExcelV2` (exporters, importers, templaters, editors).
+- `src/MiniExcel.OpenXml.FluentMapping`: the mapping importer and exporter.
+- `src/MiniExcel`: the `MiniExcel` package, a facade that keeps the v1 static API working on top of v2.
+- `tests/MiniExcel.OpenXml.Tests`, `tests/MiniExcel.Csv.Tests`: xUnit tests.
+- `benchmarks/MiniExcel.Benchmarks`: BenchmarkDotNet benchmarks.
+
+## Code
+
+- Sync methods are generated by Zomp.SyncMethodGenerator from async methods marked `[CreateSyncVersion]`. Edit only the async method; the sync version is regenerated on build.
+- Reading and writing run per cell, so code on those paths should not allocate per call (LINQ closures, substrings, interpolated strings) or take locks.
+- The libraries target `netstandard2.0` as well as current .NET, so APIs that only exist in newer frameworks need a fallback or `#if NET`.
+
+## Build and test
+
+- Tests run on net8.0 through net11.0: `dotnet test tests/MiniExcel.OpenXml.Tests` and `dotnet test tests/MiniExcel.Csv.Tests`. A change should pass on all of them.
+- Every PR needs an issue and should add tests for its change.
+
+## Benchmarks
+
+- Query, create and template benchmarks are in `benchmarks/MiniExcel.Benchmarks/BenchmarkSections`. Performance changes should show before and after numbers from these, run on the same machine.
+- Select methods with a filter that includes the class name, e.g. `--filter '*QueryExcelBenchmark.MiniExcel*'`. The namespace contains "MiniExcel", so `*MiniExcel*` alone runs every benchmark registered in `Program.cs`.
+- The configured job is a short run (3 iterations), which is enough for large differences. For changes of around 10%, add `--iterationCount 15 --launchCount 3`.
+
+## Documentation
+
+- v2 usage is documented in `README_V2.md`. A new feature adds a numbered section there.