# 项目文档治理与 Superpowers 流程规范化

> **设计日期**: 2026-06-02  
> **版本**: v1.0  
> **状态**: 已批准（待实施）  
> **目标**: 建立完整的项目文档体系，将 Superpowers 工作流融入项目规范

---

## 一、项目背景

### 1.1 现状分析

当前项目（睿核科技 - rui）是一个基于 Spring Cloud 的微服务通用平台框架，已开发支付模块（rui-payment）等业务模块。项目文档和代码规范主要维护在 `AGENTS.md` 中。

### 1.2 存在的问题

通过对现有 `AGENTS.md`（668 行）和项目文档体系的分析，发现以下 **7 类问题**：

| 问题类型 | 具体表现 | 影响 |
|---------|---------|------|
| **结构混乱** | 规范、指南、规则混杂，无清晰层级 | 查找信息困难，新成员上手慢 |
| **缺少导航** | 无目录、无文档地图 | 无法快速定位需要的规范 |
| **Superpowers 缺失** | 完全没有工作流说明 | 团队无法按标准流程协作 |
| **格式错误** | 多处 `**` 标记不匹配、表格格式问题 | 阅读体验差，可能误解 |
| **内容缺失** | 无环境搭建指南、无模块创建指引、无代码审查规范 | 新人无法自助上手 |
| **职责越界** | GitNexus 工具配置与项目规范混在一起 | 文档职责不清晰 |
| **信息孤岛** | 未引用 `docs/` 下的其他文档 | 文档之间无关联 |

### 1.3 目标定义

1. **建立标准**：重构 AGENTS.md，使其成为项目的"宪法"
2. **查漏补缺**：系统检查现有文档和代码，生成分类问题清单
3. **融入流程**：将 Superpowers 工作流融入项目规范
4. **持续可用**：建立可复用的模板和检查清单

---

## 二、整体工作流设计

采用 **三阶段流水线**，每阶段都有明确的输入、输出和验收标准：

```
┌─────────────────────────────────────────────────────────────────┐
│  阶段一：重构 AGENTS.md（建立标准）                                │
│  输入：现有 AGENTS.md + 项目文档体系                               │
│  输出：新版 AGENTS.md（项目宪法）                                  │
│  验收：文档结构清晰、规范完整、Superpowers 流程融入               │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│  阶段二：全面查漏补缺（基于标准）                                  │
│  输入：新版 AGENTS.md + 现有项目所有文档和代码                      │
│  输出：分类问题清单（高/中/低优先级）                              │
│  验收：检查覆盖率 100%、问题可追踪、有优先级                        │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│  阶段三：修复与规范化（建立流程）                                  │
│  输入：问题清单                                                   │
│  输出：修复后的文档/代码 + Superpowers 工作流模板 + 改进报告        │
│  验收：高优先级问题全部修复、流程可运行、报告完整                   │
└─────────────────────────────────────────────────────────────────┘
```

---

## 三、阶段一：重构 AGENTS.md

### 3.1 现有文档诊断

**格式问题清单**：
- 第 173 行：`SecurityUtils` 后的 `**` 未闭合
- 第 176-178 行：多处 `**` 标记不匹配
- 表格格式在部分终端渲染异常

**内容缺失清单**：
- 缺少项目级 README.md
- 缺少开发环境搭建指南
- 缺少 Superpowers 工作流说明
- 缺少代码审查规范
- 缺少模块创建标准流程

**结构问题清单**：
- 无文档地图/目录
- GitNexus 配置与项目规范混杂
- 章节间无逻辑递进关系

### 3.2 新版结构设计

```
AGENTS.md（项目宪法 - 所有开发者必读）
├── 1. 文档地图（新增）← 60秒了解项目文档体系
├── 2. 项目概览（精简）← 技术栈、仓库结构
├── 3. 环境准备（新增）← 开发环境、初始化步骤
├── 4. Superpowers 工作流（新增）← 四阶段开发流程
├── 5. 编码规范（合并优化）← 所有代码规范集中
├── 6. 基础设施速查（优化）← 工具类、注解、复用原则
├── 7. 模块开发指南（新增）← 如何创建标准业务模块
├── 8. 运维规范（合并）← Git、数据库、Nacos、构建
├── 9. 协作规范（优化）← 对话管理、工作边界
└── 10. 附录（新增）← 错误码、数据类型、文档索引
```

### 3.3 章节详细设计

#### 第 1 章：文档地图（新增）

目标：让新成员在 60 秒内了解项目文档体系

内容：
- 文档体系全景图
- 快速导航（按角色：新手/开发者/架构师）
- 文档更新规则（谁维护、何时更新）

#### 第 2 章：项目概览（精简现有内容）

保留：
- 项目名称、类型
- 精简版仓库结构（突出 app/ 和 backend/）
- 技术栈表格

移除：
- 过详细的技术说明（迁移到专门文档）

#### 第 3 章：环境准备（新增）

内容：
- 开发环境要求（JDK 21、Maven、MySQL、Node.js 等）
- 项目初始化步骤（clone → 配置 → 构建 → 运行）
- IDE 配置建议（IntelliJ IDEA 插件、代码风格）
- 验证清单（如何确认环境就绪）

#### 第 4 章：Superpowers 工作流（新增）

核心内容，四阶段流程：

**Phase 1: Brainstorming（头脑风暴）**
- 目标：明确需求、确定方案
- 输入：用户原始需求
- 输出：批准的设计方向
- 检查清单：
  - [ ] 是否已探索项目上下文？
  - [ ] 是否已提出澄清问题？
  - [ ] 是否已对比 2-3 种方案？
  - [ ] 用户是否已确认方向？

**Phase 2: Spec Writing（规格编写）**
- 目标：编写详细设计文档
- 输入：批准的设计方向
- 输出：设计文档（保存到 `docs/superpowers/specs/`）
- 检查清单：
  - [ ] 是否包含背景与目标？
  - [ ] 是否包含详细设计？
  - [ ] 是否包含验收标准？
  - [ ] 是否已完成自我审查？
  - [ ] 用户是否已审查批准？

**Phase 3: Plan Writing（计划编写）**
- 目标：编写可执行的实施计划
- 输入：批准的设计文档
- 输出：实施计划（保存到 `docs/superpowers/plans/`）
- 检查清单：
  - [ ] 是否已分解为具体任务？
  - [ ] 每个任务是否有明确的验收标准？
  - [ ] 是否有风险评估？
  - [ ] 用户是否已审查批准？

**Phase 4: Implementation（实施执行）**
- 目标：按计划执行任务
- 输入：实施计划
- 输出：代码 + 文档更新
- 检查清单：
  - [ ] 是否按任务逐个执行？
  - [ ] 每个任务是否已完成验证？
  - [ ] 是否已更新实施跟踪文档？
  - [ ] 是否已完成最终审查？

#### 第 5 章：编码规范（合并优化现有章节）

合并内容：
- 基础编码规范（Lombok、命名、注释）
- 模块 Bean 注入规范
- Mapper 规范
- Controller 规范
- URL 路由规范
- 异常处理规范
- 日志规范
- 测试规范

优化点：
- 统一用表格展示"正确 vs 错误"示例
- 增加常见错误模式说明
- 增加检查工具建议（如 Checkstyle 规则）

#### 第 6 章：基础设施速查（优化）

优化内容：
- 工具类速查表（增加使用场景列）
- 注解速查表（增加参数说明）
- 复用原则（增加反例说明）

#### 第 7 章：模块开发指南（新增）

内容：
- 何时需要新建模块
- 模块命名规范
- 模块标准结构（common/core/provider/api/task）
- 创建步骤清单
- AutoConfiguration 配置
- 模块间依赖规则

#### 第 8 章：运维规范（合并现有章节）

合并内容：
- Git 提交规范
- 数据库脚本执行规则
- Nacos 配置管理规则
- 构建与发布规范
- 前端构建规则

#### 第 9 章：协作规范（优化现有章节）

优化内容：
- OpenCode `/new` 使用指南（增加决策树）
- 工作边界规则（增加流程图）
- 框架问题处理流程（增加模板）

#### 第 10 章：附录（新增）

内容：
- 错误码分配表（完整区间划分）
- 数据类型对照表（MySQL ↔ Java ↔ JDBC）
- 相关文档索引（docs/ 下所有文档的导航）
- 术语表

### 3.4 职责分离

**GitNexus 配置迁移**：

将 AGENTS.md 中的 GitNexus 部分（第 626-668 行）迁移到独立文档：`docs/gitnexus-guide.md`

原因：
- AGENTS.md 是"项目规范"，GitNexus 是"工具配置"
- 职责分离后，AGENTS.md 更聚焦
- GitNexus 指南可以独立更新

---

## 四、阶段二：全面查漏补缺

### 4.1 检查策略

基于新版 AGENTS.md 的 10 个章节，设计 **4 维度检查清单**：

#### 维度一：文档体系完整性（检查 `docs/` 目录）

| 检查项 | 检查内容 | 优先级 | 当前状态 |
|--------|---------|--------|---------|
| 1.1 | 是否存在 `README.md` 项目总览 | 🔴 高 | ❌ 缺失 |
| 1.2 | 每个业务模块是否有独立设计文档 | 🔴 高 | ⚠️ 仅支付模块有 |
| 1.3 | 是否存在环境搭建指南 | 🔴 高 | ❌ 缺失 |
| 1.4 | 是否存在数据库变更记录 | 🟡 中 | ❌ 缺失 |
| 1.5 | API 文档是否完整 | 🟡 中 | 待确认 |
| 1.6 | 文档之间是否有交叉引用 | 🟡 中 | ❌ 无引用 |
| 1.7 | 实施跟踪文档是否最新 | 🟢 低 | ⚠️ 支付模块显示完成 |

#### 维度二：AGENTS.md 规范落地（检查代码库）

| 检查项 | 检查内容 | 优先级 | 检查方式 |
|--------|---------|--------|---------|
| 2.1 | 所有 Entity 是否继承 BaseEntity | 🔴 高 | 代码扫描 |
| 2.2 | 是否使用 Lombok | 🔴 高 | 代码扫描 |
| 2.3 | Service 是否使用构造器注入 | 🔴 高 | 代码扫描 |
| 2.4 | Mapper SQL 是否使用 `#prefix#` | 🔴 高 | 正则匹配 |
| 2.5 | Controller 是否按规范分类 | 🟡 中 | 目录检查 |
| 2.6 | 标准 CRUD 是否继承 BaseController | 🟡 中 | 代码扫描 |
| 2.7 | 异常处理是否统一用 BizException | 🟡 中 | 代码扫描 |
| 2.8 | Git 提交是否符合规范格式 | 🟢 低 | 提交历史检查 |

#### 维度三：项目结构与配置

| 检查项 | 检查内容 | 优先级 | 当前状态 |
|--------|---------|--------|---------|
| 3.1 | 模块命名是否符合规范 | 🔴 高 | ✅ 符合 |
| 3.2 | 每个模块是否有 AutoConfiguration | 🔴 高 | 待确认 |
| 3.3 | `application-dev.yml` 是否在 `.gitignore` | 🔴 高 | ✅ 符合 |
| 3.4 | Nacos 配置是否已推送 | 🟡 中 | 待确认 |
| 3.5 | 数据库脚本是否已执行 | 🟡 中 | 待确认 |

#### 维度四：Superpowers 流程就绪度

| 检查项 | 检查内容 | 优先级 | 当前状态 |
|--------|---------|--------|---------|
| 4.1 | 是否存在 `docs/superpowers/` 目录 | 🔴 高 | ❌ 缺失 |
| 4.2 | 是否存在设计文档模板 | 🔴 高 | ❌ 缺失 |
| 4.3 | 是否存在实施计划模板 | 🔴 高 | ❌ 缺失 |
| 4.4 | 是否存在代码审查清单 | 🟡 中 | ❌ 缺失 |

### 4.2 输出格式

每个问题按以下格式记录：

```markdown
### 🔴 HIGH-001: 缺少 README.md

| 属性 | 内容 |
|------|------|
| **检查项** | 文档体系完整性 - 1.1 |
| **问题描述** | 项目根目录缺少 README.md，新成员无法快速了解项目 |
| **影响范围** | 所有新加入的开发者 |
| **建议修复** | 创建 README.md，包含项目简介、技术栈、快速开始、文档索引 |
| **参考标准** | AGENTS.md 第 1 章 |
| **优先级** | 🔴 高 |
```

### 4.3 问题分类与优先级

**优先级定义**：

| 优先级 | 定义 | 修复时限 |
|--------|------|---------|
| 🔴 高 | 阻碍开发或违反核心规范 | 立即修复 |
| 🟡 中 | 影响效率或存在风险 | 1 周内修复 |
| 🟢 低 | 优化建议 | 下次迭代处理 |

---

## 五、阶段三：修复与规范化

### 5.1 修复计划（按优先级）

#### 🔴 高优先级（必须立即修复）

| 序号 | 任务 | 输出物 | 验收标准 |
|------|------|--------|---------|
| H1 | 创建 README.md | `/README.md` | 包含项目简介、技术栈、快速开始、文档索引 |
| H2 | 重构 AGENTS.md | `/AGENTS.md` | 10 章结构完整、格式正确、无遗漏 |
| H3 | 创建 Superpowers 目录结构 | `docs/superpowers/` | 目录存在且结构正确 |
| H4 | 创建设计文档模板 | `docs/superpowers/templates/design-template.md` | 包含所有必需章节 |
| H5 | 创建实施计划模板 | `docs/superpowers/templates/plan-template.md` | 包含任务分解和验收标准 |
| H6 | 迁移 GitNexus 指南 | `docs/gitnexus-guide.md` | 内容完整、AGENTS.md 中已移除 |

#### 🟡 中优先级（建议 1 周内修复）

| 序号 | 任务 | 输出物 | 验收标准 |
|------|------|--------|---------|
| M1 | 补充环境搭建指南 | `docs/environment-setup.md` | 步骤可执行、有验证方法 |
| M2 | 创建代码审查清单 | `docs/superpowers/templates/review-checklist.md` | 覆盖主要规范点 |
| M3 | 检查模块 AutoConfiguration | 代码修复 | 每个可复用模块都有 |
| M4 | 检查 Nacos 配置同步 | 配置确认 | 所有配置已推送 |

#### 🟢 低优先级（可选优化）

| 序号 | 任务 | 输出物 | 验收标准 |
|------|------|--------|---------|
| L1 | 补充数据库变更记录 | `docs/database-changelog.md` | 记录所有表结构变更 |
| L2 | 统一文档交叉引用 | 各文档更新 | 相关文档间有链接 |
| L3 | 检查测试覆盖率 | 报告 | 核心业务覆盖 ≥ 80% |

### 5.2 Superpowers 工作流模板

#### 模板一：设计文档模板

```markdown
# <模块/功能名称> 设计文档

> **设计日期**: YYYY-MM-DD  
> **版本**: v1.0  
> **状态**: 设计中/已批准  
> **目标**: <一句话描述目标>

---

## 一、背景与目标

### 1.1 现状分析
<描述当前现状、存在的问题>

### 1.2 目标定义
<明确本次设计的目标，建议 3-5 条>

---

## 二、详细设计

### 2.1 整体架构
<架构图、流程图>

### 2.2 核心组件
<各组件的职责、接口>

### 2.3 数据流
<数据如何流转>

### 2.4 接口设计
<API 定义>

### 2.5 数据库设计
<表结构、索引>

### 2.6 错误处理
<异常场景、错误码>

---

## 三、验收标准

- [ ] <可验证的验收条件 1>
- [ ] <可验证的验收条件 2>
- [ ] <可验证的验收条件 3>

---

## 四、风险与依赖

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| <风险 1> | 高/中/低 | <措施> |
```

#### 模板二：实施计划模板

```markdown
# <模块/功能名称> 实施计划

> **计划日期**: YYYY-MM-DD  
> **版本**: v1.0  
> **状态**: 待执行/执行中/已完成  
> **关联设计**: <链接到设计文档>

---

## 一、任务清单

### Phase 1: <阶段名称>

| 序号 | 任务 | 负责人 | 预估工时 | 状态 | 验证方式 |
|------|------|--------|---------|------|---------|
| 1.1 | <具体任务> | <负责人> | <工时> | ⬜ | <如何验证> |

---

## 二、进度跟踪

| 日期 | 完成任务 | 遇到的问题 | 解决方案 |
|------|---------|-----------|---------|
| YYYY-MM-DD | <任务> | <问题> | <方案> |

---

## 三、完成总结

- **实际工时**: <X 小时>
- **偏差分析**: <与预估的差异及原因>
- **经验教训**: <可复用的经验>
```

#### 模板三：代码审查清单

```markdown
# 代码审查清单

## 基础规范
- [ ] 使用 Lombok，无手写 getter/setter
- [ ] Service 使用构造器注入
- [ ] Entity 继承 BaseEntity
- [ ] 类名不加 Rui 前缀（除非冲突）

## Mapper 规范
- [ ] SQL 使用 `#prefix#` 占位符
- [ ] 无硬编码表前缀

## Controller 规范
- [ ] 标准 CRUD 继承 BaseController
- [ ] URL 路径符合规范
- [ ] 使用正确注解（@Inner、@AuthIgnore 等）

## 异常与日志
- [ ] 使用 BizException 而非 RuntimeException
- [ ] 返回 Result.ok()/Result.fail()
- [ ] 日志无敏感信息

## 测试
- [ ] 核心逻辑有单元测试
- [ ] 测试命名符合规范
```

### 5.3 改进报告模板

```markdown
# 项目文档治理改进报告

> **报告日期**: YYYY-MM-DD  
> **治理范围**: 项目文档体系 + AGENTS.md + Superpowers 流程  
> **执行人**: <执行者>

---

## 一、检查统计

| 维度 | 检查项数 | 发现问题 | 已修复 | 待修复 |
|------|---------|---------|--------|--------|
| 文档体系完整性 | X | Y | Z | W |
| 代码规范落地 | X | Y | Z | W |
| 项目结构与配置 | X | Y | Z | W |
| Superpowers 就绪度 | X | Y | Z | W |
| **合计** | **X** | **Y** | **Z** | **W** |

## 二、问题分布

<图表或表格展示问题分布>

## 三、关键改进

1. <改进 1：重构 AGENTS.md>
2. <改进 2：建立 Superpowers 流程>
3. <改进 3：...>

## 四、后续建议

1. <建议 1>
2. <建议 2>
```

---

## 六、验收标准

### 6.1 阶段验收标准

| 阶段 | 验收标准 | 验证方式 |
|------|---------|---------|
| 阶段一 | AGENTS.md 结构清晰、内容完整、格式正确 | 人工审查 |
| 阶段二 | 检查覆盖率 100%、问题清单完整 | 逐项核对 |
| 阶段三 | 高优先级问题全部修复、模板可用 | 实际使用验证 |

### 6.2 最终验收标准

- [ ] 新成员可在 30 分钟内通过 AGENTS.md 了解项目规范
- [ ] Superpowers 四阶段流程可在项目中完整运行
- [ ] 所有文档间有交叉引用，无信息孤岛
- [ ] 代码规范有自动化检查手段（或明确的手动检查清单）

---

## 七、风险与依赖

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 重构 AGENTS.md 期间，团队仍在开发新功能 | 中 | 使用分支管理，重构完成后再合并 |
| 检查清单不够全面，遗漏问题 | 中 | 基于 AGENTS.md 逐条设计检查项，确保覆盖 |
| 团队成员不习惯 Superpowers 流程 | 低 | 提供培训和模板，逐步推广 |
| 文档更新后无人维护 | 中 | 明确文档负责人，纳入代码审查 |

---

## 八、附录

### 8.1 术语表

| 术语 | 说明 |
|------|------|
| Superpowers | OpenCode 的规范化工作流框架 |
| Brainstorming | 头脑风暴阶段，明确需求和方案 |
| Spec | 设计文档/规格说明书 |
| AGENTS.md | 项目规范文档（项目宪法） |

### 8.2 相关文档

| 文档 | 路径 | 说明 |
|------|------|------|
| AGENTS.md | `/AGENTS.md` | 项目规范（待重构） |
| 支付模块设计 | `docs/支付模块架构设计.md` | 示例设计文档 |
| 支付模块跟踪 | `docs/支付模块实施跟踪.md` | 示例跟踪文档 |

### 8.3 参考标准

- 本设计文档本身遵循 Superpowers 流程编写
- 模板设计参考了行业最佳实践

---

> **文档结束**  
> 下一步：进入实施计划阶段（由 Superpowers Plan Writer 执行）