diff --git a/AGENTS.md b/AGENTS.md
index cb906f4..cf43f60 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -117,13 +117,19 @@
   **新增模型前先搜一遍 `__tablename__` 有没有被占用。**
 - 测试基线（**2026-09-12 合并主干 PR #7 + 本线记忆投影链路之后实测**）：
   `mypy app` → **245 个文件 0 错**；
-  `pytest tests`（全量）→ `2 failed, 1415 passed, 2 skipped`；
+  `pytest tests`（全量）→ `2 failed, 1421 passed, 1 skipped`；
   `pytest tests/integration` → `102 passed, 1 skipped`。
   ⚠️ **用例数会随开发增减，判断健康看"0 failed"而不是看绝对值**。
-  剩下那 2 个失败**都不是代码缺陷**，接手时不要"修"它们：
+  那 2 个失败**都不是代码缺陷**，接手时不要"修"它们：
   `tests/unit/service/test_offsite_document_recognition_adapter.py` 的 2 个用例 —— **环境相关**：
   它们断言请求体里是中文原文，而 httpx 会把中文序列化成 `\uXXXX`，字节序列自然不匹配。
   功能无影响；若要修，正确做法是断言 `json.loads(body)` 后的字段值（字节级断言不该用来测 JSON）。
+- **`ruff`：`ruff check app tests tools alembic` → 全部 `All checks passed`（0 错）。**
+  ⚠️ **检查范围要写对**：直接 `ruff check .`（全仓）会报 40 个错，**全部来自仓库根目录的两个
+  散落脚本 `hq.py` / `nl2sql_yc.py`**（袁聪线的演示脚本，不属本项目包结构）。
+  所以门禁命令用上面那条；报"ruff 干净"时**必须带范围**，否则会和别人的脚本混在一起。
+  （`pyproject.toml` 的 `[tool.ruff.lint]` 选的是 `E,F,I,B,UP`、`line-length=100`；
+  `tools/*.py` 另配了 `E501/I001/B007` 的 per-file-ignores。）
 - **mypy：`mypy app` → `Success: no issues found in 245 source files`（0 错）。**
   ⚠️ 曾在本机报 184 个错，**已查明是环境版本旧**，与代码质量无关 —— 复现矩阵：