diff --git a/AGENTS.md b/AGENTS.md
index df9f299..8f35039 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -62,6 +62,15 @@
 - 若锁文件变更：`pnpm install`（保持本地依赖与团队一致）
 - 新任务建议开分支：`git switch -c feature/<topic>`；提交信息用中文清晰描述变更意图
 
+### 类型生成与 Astro 同步（重要）
+
+- Astro 的高保真类型来自 `.astro/types.d.ts`，由 `astro dev` 或 `astro sync` 生成。
+- Node 要求：`>= 18.20.8`（建议 `>= 20`）。Node 版本不足会导致 `astro sync` 失败，类型退化为 `any`（如 `getCollection(...args: any[]): any`）。
+- 操作规范：
+  - 在“非沙盒/本机环境”执行：`astro sync` 或 `pnpm dev`，以生成 `.astro/types.d.ts`。
+  - 如在沙盒内执行需要更高权限，请先申请再运行，或直接在沙盒外执行。
+  - 若类型仍不生效：删除 `.astro/` 后重跑 `pnpm sync`；确保编辑器使用工作区 TypeScript 版本。
+
 ### 依赖版本策略
 
 - 版本范围由 pnpm 写入：不要在 `package.json` 手写 `latest` 或具体版本号。