# 项目文档中心

> 集中存放架构方案、技术规范、项目约定的文档目录。
> 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 描述项目"怎么做" |