vifo
19de7e24ec
从 docs-local 迁移以下文档： - backend/guides/: AI开发环境配置、Nacos配置、GitNexus指南、OpenCode工作流等 - backend/templates/: Superpowers设计模板、计划模板、审查清单 - backend/config-templates/: 应用配置模板、Nacos配置 - backend/design/: 数据库表结构规划 - backend/specs/: 项目文档治理、MQ统一推送设计 - backend/: 代码分析报告、Feign分析报告、文档治理报告 - frontend/design/: Admin-UI分模块打包设计
588 lines
20 KiB
Markdown
588 lines
20 KiB
Markdown
# 项目文档治理与 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 执行）
|