76 lines
3.4 KiB
Markdown
76 lines
3.4 KiB
Markdown
# 项目文档中心
|
||
|
||
> 集中存放架构方案、技术规范、项目约定的文档目录。
|
||
> Agent 和用户可以随时查阅、创建、更新此目录下的文档。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
docs/
|
||
├── README.md # 本文件 — 目录标准与使用规范
|
||
├── architecture/ # 架构级方案（分层、模块、技术选型、组件架构）
|
||
├── conventions/ # 项目约定（编码规范、命名、Git 工作流）
|
||
├── specs/ # 系统级技术规范（API 设计、数据模型、接口协议）
|
||
└── reference/ # 参考分析文档（竞品拆解、行业研究、设计参考）
|
||
```
|
||
|
||
## 文档命名规范
|
||
|
||
- 文件名格式：`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 | reference
|
||
status: draft | review | stable | deprecated
|
||
created: YYYY-MM-DD
|
||
updated: YYYY-MM-DD
|
||
related_changelogs: [CL-xxx, CL-xxx]
|
||
---
|
||
```
|
||
|
||
字段说明：
|
||
- `id`：与文件名编号一致
|
||
- `type`：architecture（架构）、convention（规范）、spec（技术规范）、reference（参考分析）
|
||
- `status`：draft（草稿）、review（审查中）、stable（已定稿）、deprecated（已废弃）
|
||
- `related_changelogs`：关联的 changelog 锚点 ID 列表，用于溯因
|
||
|
||
## 固化时机（何时写入）
|
||
|
||
以下情况应创建或更新对应文档：
|
||
|
||
| 场景 | 操作 |
|
||
|------|------|
|
||
| 完成涉及 3+ 模块的架构级改动 | 创建/更新 architecture 文档 |
|
||
| 制定或修改了项目公共规范（编码/命名/流程） | 创建/更新 conventions 文档 |
|
||
| 引入或替换了核心依赖（终端引擎/构建工具/UI 库） | 更新 architecture 文档 |
|
||
| 调整了目录结构或模块划分 | 更新 architecture 文档 |
|
||
| 设计或修改了 UI/交互标准 | 创建/更新 architecture 文档 |
|
||
| 定义了 API 接口、数据模型、通信协议 | 创建/更新 specs 文档 |
|
||
| 完成了竞品分析、行业调研、设计参考的深度研究 | 创建/更新 reference 文档 |
|
||
| 约定被废弃或替换 | 标记为 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 描述项目"怎么做" |
|