新增项目文档规范驱动并对齐log，后续还可以把pitfall和anti pitfall都关联起来形成自动纠错

docs/README.md

@@ -0,0 +1,73 @@
+# 项目文档中心
+
+> 集中存放架构方案、技术规范、项目约定的文档目录。
+> Agent 和用户可以随时查阅、创建、更新此目录下的文档。
+
+## 目录结构
+
+```
+docs/
+├── README.md              # 本文件 — 目录标准与使用规范
+├── architecture/          # 架构级方案（分层、模块、技术选型、组件架构）
+├── conventions/           # 项目约定（编码规范、命名、Git 工作流）
+└── specs/                 # 系统级技术规范（API 设计、数据模型、接口协议）
+```
+
+## 文档命名规范
+
+- 文件名格式：`NNN-简短描述.md`，NNN 为三位递进编号（从 001 起）
+- 示例：`001-interaction-design-system.md`、`002-api-conventions.md`
+- 编号由 Agent 自动分配（读取目录下最大编号 +1）
+- 使用英文短横线命名（kebab-case），描述部分用英文
+
+## 文档元数据
+
+每个规范文档在文件开头**必须**包含以下 YAML frontmatter：
+
+```yaml
+---
+id: DOC-NNN
+title: 文档标题（中文）
+type: architecture | convention | spec
+status: draft | review | stable | deprecated
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+related_changelogs: [CL-xxx, CL-xxx]
+---
+```
+
+字段说明：
+- `id`：与文件名编号一致
+- `type`：architecture（架构）、convention（规范）、spec（技术规范）
+- `status`：draft（草稿）、review（审查中）、stable（已定稿）、deprecated（已废弃）
+- `related_changelogs`：关联的 changelog 锚点 ID 列表，用于溯因
+
+## 固化时机（何时写入）
+
+以下情况应创建或更新对应文档：
+
+| 场景 | 操作 |
+|------|------|
+| 完成涉及 3+ 模块的架构级改动 | 创建/更新 architecture 文档 |
+| 制定或修改了项目公共规范（编码/命名/流程） | 创建/更新 conventions 文档 |
+| 引入或替换了核心依赖（终端引擎/构建工具/UI 库） | 更新 architecture 文档 |
+| 调整了目录结构或模块划分 | 更新 architecture 文档 |
+| 设计或修改了 UI/交互标准 | 创建/更新 architecture 文档 |
+| 定义了 API 接口、数据模型、通信协议 | 创建/更新 specs 文档 |
+| 约定被废弃或替换 | 标记为 deprecated，写明替代文档编号 |
+
+## 更新与维护
+
+- **关联 changelog**：每次基于开发改动更新文档时，必须在 `related_changelogs` 中追加对应的 `CL-xxx` 锚点 ID
+- **代理审查**：Agent 在周期审查中会自动对比 changelog 与文档的一致性（见 `spec-docs` Skill）
+- **手动审查**：用户可在任意时间要求 Agent 执行文档审查
+- **冲突处理**：当文档与代码/changelog 存在逻辑互斥时，Agent 应标记为 `review` 状态并提请用户裁决
+
+## 与其它系统的关系
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| `dev-changelog` | 上游数据源 | changelog 记录"做了什么"，docs 沉淀"如何做的规范" |
+| `spec-docs` Skill | 管理工具 | 负责文档的创建提醒、周期审查、一致性校验 |
+| `deferred-decisions` | 互补 | deferred 记录"暂不做的方案"，docs 记录"已确定的方案" |
+| `profile-memory` | 互补 | profile 描述项目"是什么"，docs 描述项目"怎么做" |