docs(agents): 同步文档规范与 design 目录说明至全局版本

- 替换方案规范为 design/pdd/ + design/prd/ 编号体系
- 移除 docs/roadmap.md 进度同步规则（全局未要求）
- 新增 design/ 子目录职责、读写权限与兜底规则

AGENTS.md

@@ -186,29 +186,64 @@ pub use vector_store::VectorStore;
 
 ## 文档规范
 
-### 方案规范 (docs/)
+### 文档编号规范（design/pdd/ + design/prd/）
 
-**编号规则**：创建新方案前必须先通过 shell 命令确认当前实际最大编号（Unix: `ls docs/` / Windows: `dir docs\`），禁止使用上下文中缓存的编号，如遇冲突自动递增
+`design/pdd/`（方案文档）和 `design/prd/`（需求文档）使用相同的命名格式，但**各自独立编号**：
 
-**方案文档结构**（6 项）：
+```
-1. **背景与目标** - 问题描述、预期目标
+<序号>-<简短描述>.md
-2. **需求分析** - 功能需求、非功能需求
+```
-3. **方案设计** - 架构设计、模块划分、接口定义
-4. **实现计划** - 任务拆解、优先级、时间估算
-5. **风险评估** - 潜在风险、缓解措施
-6. **验收标准** - 可验证的完成条件
 
-### 进度同步规范 (docs/roadmap.md)
+规则：
+- 序号使用数字，从 1 开始递增。**创建前必须通过 shell 命令确认目标目录当前实际最大编号再加 1：**
+  ```bash
+  # 查 design/pdd/ 的最大编号
+  ls design/pdd/ 2>/dev/null | grep -E '^\d+-' | sort -t- -k1 -n | tail -1 | cut -d- -f1
+  # 查 design/prd/ 的最大编号
+  ls design/prd/ 2>/dev/null | grep -E '^\d+-' | sort -t- -k1 -n | tail -1 | cut -d- -f1
+  # 无输出则从 1 开始
+  ```
+  禁止使用上下文中缓存的编号。
+- 描述：中文，简短概括主题
+- 两个目录各自独立编号——`design/pdd/` 已有 `3-` 时，`design/prd/` 的新文件仍从当前最大号 +1 开始，互不影响
 
-完成一项实施后，必须检查 `docs/roadmap.md` 是否存在对应内容；若存在，必须同步标记为完成：
+方案文档（`design/pdd/`）应包含：
+- 背景与目标
+- 需求推演概要（需求拆解、边界识别、关键假设的简要推演）
+- 当前问题分析
+- 架构决策记录（重大技术选型、架构变更的决策过程与理由）
+- 设计方案（含架构图/流程图）
+- 实施步骤
+- 验证标准
+- 回滚方案（如适用）
 
-- **Step / Phase 状态行**：对应 Step 加 ✅ 标记；Phase 章节末尾「状态」行从 ⏳ 改为 ✅ Phase X 全部交付物已完成
+示例：
-- **里程碑表**：更新对应里程碑状态从 ⏳ 改为 ✅ + 完成日期
+- `design/pdd/1-ui-components重构方案.md`
-- **依赖关系图（Mermaid）**：节点 `class` 从 `pending` / `core` 改为 `done`，必要时更新节点摘要
+- `design/prd/1-用户认证需求.md`
-- **文末「已完成 / 进行中阶段」列表**：追加一行 `- ✅ Phase X — 一句话要点`
+- `design/pdd/2-数据库迁移方案.md`
-- **顶部「当前状态」**：补充新完成 Phase，更新「下一步」指向
 
-参考案例：2026-07-05 完成 Phase 7 SqliteStore 时同步更新 6 处（顶部状态 / Phase 章节 / 依赖图 / M3 / 下一步行动 / 已完成列表）。
+---
+
+### 设计目录（design/）
+
+项目根下的 `design/` 目录集中管理所有设计相关的文件，供人类和 agent 共同读写。
+
+| 子目录 | 内容 | 谁写 | 谁读 |
+|--------|------|------|------|
+| `design/pdd/` | 方案设计文档（PDD）→ 架构方案、设计决策、转换方案 | proposal→writer pipeline | Think 参考、Build 实现、Vet 审查 |
+| `design/prd/` | 需求文档（PRD）→ 功能需求、用户故事、验收标准 | 人写 | Think 分析、Proposal 写方案时参考 |
+| `design/prototype/` | **OD 导出的原型 HTML** → 视觉稿、交互原型、页面 layout | OD 桌面版导出 | Think 分析结构、Build 对照实现 |
+| `design/notes/` | 笔记记录 → 零散想法、会议纪要、调研速记 | 人写 | 各 agent 参考 |
+| `design/roadmap/` | 路线图 → 里程碑规划、版本计划、优先级列表 | 人写 | Proposal 排期参考 |
+| `design/DESIGN.md` | 设计系统（品牌规范）→ 色板、字体、间距、语气 | OD 导出 / 人维护 | Think 提取 token、Build 同步到 `src/` |
+| `design/tokens.css` | 设计 Token CSS → 从 DESIGN.md 提取的 CSS 变量 | 人同步 / agent 同步 | 所有 Svelte 组件引用 |
+
+**访问规则：**
+- 读：所有 agent 默认可读（`read_file` 不需要额外权限）
+- 写：writer agent 可通过 `"design/**": allow` 写入 `design/` 下任意子目录
+- 注意：`prototype/` 由 OD 桌面版导出，agent 只读不写；`DESIGN.md` 和 `tokens.css` 建议手动维护或 agent 写入时确认后再改
+
+**兜底规则：** 文档类型不在上表时（如教程、接口文档、临时记录），或目标目录不存在时 → **向用户提问确认路径**。不允许自行推断存放位置。
 
 ---