# OpenSpec 归档目录

本目录用于存放大需求、新模块、架构调整、生成流程调整等 Spec 任务经 OpenSpec 流程沉淀后的长期文档。

## 目录结构

```text
specs/openspec/
├── 模块索引.md              # 本文件
├── <change-name>/         # 单个 Spec 任务的归档
│   ├── proposal.md        # 需求背景与目标
│   ├── design.md          # 设计方案
│   └── tasks.md           # 实现任务与验证
└── ...
```

## OpenSpec 工作目录

OpenSpec CLI 的活跃工作目录位于项目根目录：

```text
openspec/
├── changes/               # 进行中的 change
├── changes/archive/       # OpenSpec 自身归档的 change
└── specs/                 # OpenSpec 管理的 spec
```

## 工作流

### 简单修复 / 旧模块修复

- 直接修改代码/资源。
- 简短说明结果。
- 执行归档检查；没有长期信息变化时，不归档到本目录。

### 大需求 / 新模块

1. 使用 Claude Code 命令 `/opsx:propose "需求描述"` 创建 change。
2. 按 OpenSpec 流程生成 `proposal.md`、`design.md`、`tasks.md`。
3. 使用 `/opsx:apply` 执行实现。
4. 实现完成后使用 `/opsx:archive` 归档。
5. **同时**把结论同步到本目录和项目既有模块文档：
   - `specs/openspec/<change-name>/`
   - `modules/<module>/业务参考总入口.md`
   - `modules/<module>/progress.md`
   - `modules/<module>/tasks.md`
   - `rules/10-架构说明.md`（如涉及架构变化）
   - `modules/模块索引.md`（如新增模块）
   - `rules/30-模块登记规则.md`（如改变模块分类、状态定义或登记规则）

## 文档关联

- [工作流清单](../../rules/40-工作流清单.md)：任务分类、修复流程、Spec 流程、提交前检查、生成/构建流程。
- [大需求 / 新模块工作流](../../rules/60-新特性工作流.md)：新增/已有功能判断、模块登记、联动更新检查。
- [归档规则](../../rules/50-归档规则.md)：归档时机、内容、格式和关联更新原则。
- [模块索引](../../modules/模块索引.md)：项目功能、框架、编辑器工具模块总览。

## 同步要求

OpenSpec change 完成后，必须将结论同步到项目模块文档：

- `specs/openspec/<change-name>/` — OpenSpec 归档目录
- `modules/<module>/业务参考总入口.md`、`progress.md`、`tasks.md` — 相关模块文档
- `rules/10-架构说明.md`（如涉及架构变化）
- `modules/模块索引.md`（如新增模块）
- `rules/30-模块登记规则.md`（如改变模块分类、状态定义或登记规则）

## 与项目既有规则的关系

- 项目既有规则入口：`RULES.md`、`AGENTS.md`、`rules/`
- OpenSpec 负责大需求 / 新模块的 spec-driven 流程。
- 项目既有文档负责长期模块知识、架构说明和任务跟踪。
- 大需求 / 新模块完成后，OpenSpec 归档和项目归档都需要做。

## 命令速查

```bash
# 查看进行中的 changes
openspec list

# 查看 specs
openspec list --specs

# 创建新 change
openspec new change "change-name"

# 查看 change 状态
openspec status --change "change-name"

# 归档 change
openspec archive "change-name"
```

Claude Code 命令：

- `/opsx:propose "需求描述"` — 创建并生成 change 文档
- `/opsx:apply` — 按 design/tasks 实现
- `/opsx:archive` — 归档完成
- `/opsx:explore` — 探索性分析
- `/opsx:sync` — 同步 specs