diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..65e0dcc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,39 @@
+# AGENTS.md
+
+## Build & Test
+
+```bash
+dotnet build              # Build all projects
+dotnet test               # Run all tests
+dotnet test --filter "FullyQualifiedName~ClassName.MethodName"  # Run single test
+```
+
+## Architecture
+
+- **3-project solution** (`src/Resonance.sln`):
+  - `Core` — class library: audio file scanning, metadata reading (ATL), SQLite persistence (Dapper)
+  - `Core.Tests` — xUnit + FluentAssertions + Moq
+  - `AtlFieldExtractor` — CLI that dumps ATL metadata fields from WAV files to `.atl.txt`
+- **No Avalonia UI yet** — README mentions it but only the Core library exists.
+- Target framework: `net10.0` (requires .NET 10 SDK — currently `10.0.103`).
+
+## Known Issues / Gotchas
+
+- **Table name mismatch**: `Database.InitializeDatabase()` creates table `sounds`, but `AddEntry()` / `AddEntries()` / `EntryExists()` reference `audio_files`. Any call to insert or query will fail at runtime. `Database` currently has no test coverage.
+- **Tests create temp files/directories** under `Path.GetTempPath()` and clean them up via `IDisposable`. Don't rely on a real audio directory for tests.
+- **`AudioMetadataReader` tests** use real WAV files from `data/source/` (not in git). When files are absent, tests silently return early (`if (wavFiles.Length == 0) return;`) — they pass without actually running assertions, not `Skip.If`. Running `dotnet test` will report 12 passes regardless of whether the fixture files exist.
+- **`.atl.txt` fixture files** are generated by `AtlFieldExtractor`. If the WAV files or the ATL library version change, re-run the extractor to regenerate them before running metadata tests.
+
+## Data / Test Fixtures
+
+- **`data/source/`** 包含有版权保护的 WAV 音频文件，**不会提交到 git**。按厂商分子目录：`Boom/`、`Wow Sound/`、`The Odessy/`、`Sound Idea/`。
+  - 每个 WAV 旁有对应的 `.atl.txt` 文件（由 `AtlFieldExtractor` 生成），记录了 ATL 库解析出的完整元数据，供测试断言参考。
+  - Boom 目录下的文件元数据最丰富（标准标签 + iXML 自定义字段 + BWF bext 字段 + 嵌入封面）；Sound Idea 目录下的文件元数据最少（仅基础技术参数，无任何附加字段）。
+- **`AudioMetadataReader` 测试**使用 `data/source/Boom/` 和 `Sound Idea/` 中的 WAV 文件。文件不在 git 仓库中，测试通过 `if (wavFiles.Length == 0) return;` 静默返回（测试仍然 pass，但未执行实际断言）。
+- **路径解析**：测试运行时从 `bin/Debug/net10.0/` 启动，需向上回溯 6 级到达仓库根目录，再拼接 `data/source/`。
+
+## Conventions
+
+- Code and comments are in **Chinese**.
+- Namespace: `OCES.Resonance.Core` (Core), `OCES.Resonance.AtlFieldExtractor` (extractor), `OCES.Resonance.Core.Tests` (tests).
+- Git commit style: `WIP: <description>` (no conventional commits).