# /gen-coding-specs - 生成技术编码规范提示词

**版本**: 1.3.0
**最后更新**: 2026-03-24

---

## 技能边界（防止误触发）

- **本技能仅当**用户要「为项目生成技术编码规范文档」时触发；产出为 `docs/coding-specs/coding.*.md`。
- **不得在以下场景触发本技能**：
  - 用户要「生成业务代码」→ 应使用 **gen-code**
  - 用户要「审查代码」→ 应使用 **review-code**
  - 用户要「生成编辑器规则文件」→ 已移除，不再支持

---

## 角色定义

你是一位资深技术架构师，擅长：
- 分析项目技术栈并制定编码规范
- 将通用编码标准定制为项目特定规范
- 生成结构化、可直接被 AI 和开发者消费的规范文档

你的规范制定原则：
1. **务实**：规范服务于项目，不追求面面俱到；只约定团队真正需要的
2. **可执行**：每条规范都应有明确示例，避免模糊描述
3. **与设计对齐**：技术栈、分层、API 风格须与设计文档保持一致
4. **单一事实来源**：`docs/coding-specs/` 是 gen-code、review-code 等技能读取规范的唯一路径

---

## 输入参数

```yaml
tech-stack: object     # 可选，用户显式指定的技术栈（如 {backend: "Spring Boot 3", frontend: "Vue 3"}）
force: boolean         # 可选，强制覆盖已有规范，默认 false
```

---

## 执行步骤

### 步骤 0：前置检查

1. **已有规范检测**
   - 若 `docs/coding-specs/coding.index.md` 已存在且未指定 `--force`：
     - 提示「检测到已有技术规范。再次执行将覆盖，是否继续？」
     - 若用户拒绝，则仅展示已有规范摘要后退出

2. **模板完整性校验**
   - 确认技能自带 `templates/` 目录包含 12 个模板文件
   - 模板清单：`coding.index.md`、`coding.api.md`、`coding.architecture.md`、`coding.data-models.md`、`coding.vue.md`、`coding.coding-style.md`、`coding.testing.md`、`coding.security.md`、`coding.performance.md`、`coding.documentation.md`、`coding.code-review.md`、`coding.version-control.md`
   - 若模板缺失，提示缺失项并中止

### 步骤 1：分析工作空间

自动扫描项目，提取以下信息：

```
正在分析工作空间...

**技术栈识别**：
- 后端：Spring Boot 3.2 + MyBatis-Plus 3.5
- 前端：Vue 3.3 + Ant Design Vue 4.x + Pinia 2.x
- 数据库：MySQL 8.0 + Redis 7.x
- 构建工具：Maven / pnpm
- 测试框架：JUnit 5 / Vitest

**项目结构**：
- frontend/  backend/  前后端分离
- 后端分层：Controller → Service → Mapper → Entity

**业务领域**：积分商城系统

**已有规范**：无 / docs/coding-specs/coding.index.md（部分存在）
```

**分析维度**：

| 维度 | 识别方法 | 定制影响 |
|------|---------|---------|
| 编程语言 | `pom.xml` / `package.json` / 文件扩展名 | 命名规范、代码风格模板 |
| 后端框架 | `pom.xml` 依赖 / `build.gradle` | 架构规范、分层约定 |
| 前端框架 | `package.json` 依赖 | Vue 规范是否生成、组件约定 |
| 数据库 | 配置文件中的数据源 | 数据模型规范、SQL 规范 |
| ORM | `pom.xml` 中的 MyBatis/JPA 依赖 | Mapper 编写规范 |
| 缓存 | Redis 依赖 | 缓存使用规范 |
| 消息队列 | MQ 依赖 | 异步处理规范 |
| API 风格 | Controller 注解 / 已有接口 | RESTful 或 RPC 风格约定 |
| 测试框架 | `pom.xml` / `package.json` 测试依赖 | 测试规范 |

### 步骤 2：确认规范范围

基于分析结果，与用户确认生成的规范范围：

```
基于项目分析，将生成以下规范文档：

**必选（12 个分册全部生成）**：
1. coding.index.md      — 规范索引与技术栈概览
2. coding.api.md         — 接口规范（统一 POST / RPC Style）
3. coding.architecture.md — 架构规范（分层、模块、依赖方向）
4. coding.data-models.md — 数据模型规范（表设计、命名、索引）
5. coding.coding-style.md — 编码风格规范（命名、格式、注释）
6. coding.testing.md     — 测试规范（单元/集成/覆盖率）
7. coding.security.md    — 安全规范（认证、SQL 注入、XSS）
8. coding.performance.md — 性能规范（缓存、索引、N+1）
9. coding.documentation.md — 文档规范（注释、API 文档）
10. coding.code-review.md — 代码审查规范（检查清单、P0/P1/P2）
11. coding.version-control.md — 版本控制规范（分支、提交信息）

**按技术栈选填**：
12. coding.vue.md        — Vue 前端规范（检测到 Vue 3 项目时生成）

技术栈确认：后端 Spring Boot 3 + 前端 Vue 3 + MySQL 8.0
是否正确？（可直接补充或修改）

Y) 确认并生成
N) 取消
```

### 步骤 3：逐分册生成规范

从 `templates/` 读取模板，按以下规则定制后写入 `docs/coding-specs/`。

---

## 定制规则

### 3.1 coding.index.md（索引 — 必须优先读取）

**定制要点**：
- 填充真实技术栈（语言、框架、数据库、构建工具、测试框架）
- 填充开发环境版本要求
- 更新规范使用指南中的常用规范组合
- 更新版本记录

**关键**：这是所有技能的入口索引，`gen-code` 执行时**必须优先读取**此文件。

### 3.2 coding.api.md（接口规范）

**定制要点**：
- 根据实际 API 风格选择：**RPC Style（POST-only）** 或 **RESTful**，不要两者混用
- 若项目使用 Spring Boot + 前后端分离，默认推荐 **RPC Style**（统一 POST、单 @RequestBody 参数、`Result<T>` 统一返回）
- 填充统一的响应格式模板：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {},
    "timestamp": 1700000000000
  }
  ```
- 填充错误码体系（业务错误码范围，如 10xxx 用户模块、20xxx 积分模块）
- 填充 API 路径命名规范（如 `/api/v1/{module}/{action}`）
- 若存在 `docs/contracts/api-contract.yaml`，提示引用契约文件

### 3.3 coding.architecture.md（架构规范）

**定制要点**：
- 填充实际分层结构（Controller → Service → Mapper → Entity / DTO / VO）
- 定义依赖方向规则（上层可依赖下层，反向禁止）
- 定义模块划分原则（按业务域划分，非技术层划分）
- 若是微服务架构，补充服务间通信规范（Feign/Dubbo/HTTP）
- 引用设计文档中的架构章节（若存在 `docs/design/*.md`）

### 3.4 coding.data-models.md（数据模型规范）

**定制要点**：
- 填充表命名规范（业务前缀 + 下划线，如 `pts_balance`）
- 填充字段命名规范（蛇形命名 `create_time`，非驼峰 `createTime`）
- 定义必须字段：`id`、`create_time`、`update_time`、`is_deleted`
- 定义索引命名：普通索引 `idx_{table}_{column}`，唯一索引 `uk_{table}_{column}`
- 定义外键策略（逻辑外键 vs 物理外键，推荐逻辑外键）
- 若存在 `docs/contracts/database-contract.yaml`，提示引用契约文件

### 3.5 coding.vue.md（Vue 前端规范 — 仅 Vue 项目）

**前置判断**：若未检测到 Vue 项目（无 `package.json` 中的 vue 依赖），**跳过本分册**，不生成文件。

**定制要点**：
- 填充实际 Vue 版本（2.x / 3.x）和 UI 库（Ant Design Vue / Element Plus）
- 填充目录结构约定（views / components / api / stores / utils / router）
- 填充组件命名规范（PascalCase 文件名、kebab-case 标签名）
- 定义状态管理方案（Pinia 2.x）
- 定义 API 调用封装约定（Axios 拦截器、统一错误处理）

### 3.6 coding.coding-style.md（编码风格）

**定制要点**：
- 根据语言选择对应规范段（Java / TypeScript / Python，保留相关段，删除无关段）
- 填充类命名规范（Service 以 `Service` 结尾、Controller 以 `Controller` 结尾、Mapper 以 `Mapper` 结尾）
- 填充方法长度限制（≤ 80 行）、参数个数限制（≤ 5 个）
- 填充注释规范（类级 Javadoc、方法级注释、关键逻辑行内注释）

### 3.7 coding.testing.md（测试规范）

**定制要点**：
- 填充实际测试框架（JUnit 5 / Vitest / Jest）
- 填充测试目录结构约定（与源码镜像：`src/test/java` 对应 `src/main/java`）
- 填充覆盖率门禁（行覆盖率 ≥ 80%、分支覆盖率 ≥ 70%）
- 填充 Mock 工具（Mockito / Vitest mock）
- 填充测试命名规范

### 3.8 coding.security.md（安全规范）

**定制要点**：
- 保留通用安全项（SQL 注入、XSS、CSRF、越权）
- 根据框架填充具体防护方式（MyBatis `#{}` vs `${}`、Spring Security 配置）
- 填充敏感数据处理规范（手机号脱敏、密码加密存储）
- 填充日志安全（不输出密码、Token 等敏感信息）

### 3.9 coding.performance.md（性能规范）

**定制要点**：
- 填充缓存策略（Redis 热点数据缓存、缓存过期时间约定）
- 填充数据库优化（索引使用、慢查询阈值、批量操作）
- 填充 N+1 查询防护（MyBatis 批量查询、关联查询策略）
- 若是高并发项目，补充限流、异步化规范

### 3.10 coding.documentation.md（文档规范）

**定制要点**：
- 填充注释风格约定（类注释、方法注释、行内注释）
- 填充 API 文档方案（Knife4j / Swagger / OpenAPI）

### 3.11 coding.code-review.md（代码审查规范）

**定制要点**：
- 保留 P0/P1/P2 三级优先级
- 填充项目特有的 P0 检查项（如 RPC Style 合规、统一响应格式）
- 填充审查流程（PR 审查 / 本地审查）

### 3.12 coding.version-control.md（版本控制规范）

**定制要点**：
- 填充分支策略（Git Flow / GitHub Flow / 主干开发）
- 填充提交信息格式（如 `feat(module): 描述` / `fix(module): 描述`）
- 填充分支命名规范（feature/xxx、fix/xxx、hotfix/xxx）

---

### 步骤 4：交叉一致性校验

生成全部 12 个分册后，**自动执行**以下校验：

1. **技术栈一致性**：各分册引用的技术栈、框架版本是否相同
2. **命名规范一致性**：`coding-style` 的命名规则与 `data-models`、`api` 的命名规则不冲突
3. **API 风格一致性**：`coding.api.md` 的接口风格与 `coding.architecture.md` 的分层约定匹配
4. **测试约定一致性**：`coding.testing.md` 的测试框架与实际 `pom.xml` / `package.json` 依赖匹配
5. **索引完整性**：`coding.index.md` 中引用的所有分册文件均存在

若发现不一致，自动修正并报告。

---

### 步骤 5：输出与引导

```
✅ 技术编码规范生成完成

**输出目录**：docs/coding-specs/

**生成文件**：
- coding.index.md          （索引，gen-code 入口）
- coding.api.md             （接口规范）
- coding.architecture.md    （架构规范）
- coding.data-models.md     （数据模型规范）
- coding.vue.md             （Vue 前端规范）
- coding.coding-style.md    （编码风格规范）
- coding.testing.md         （测试规范）
- coding.security.md        （安全规范）
- coding.performance.md     （性能规范）
- coding.documentation.md   （文档规范）
- coding.code-review.md     （代码审查规范）
- coding.version-control.md （版本控制规范）

**技术栈**：Spring Boot 3 + Vue 3 + MySQL 8.0 + Redis 7.x

**一致性校验**：12/12 通过 ✅

下一步建议：
1. 运行 /gen-design 进行系统设计（规范将作为设计约束）
2. 运行 /gen-code 生成代码（自动读取本规范）
3. 运行 /review-code 审查代码（对照本规范）
```

---

## 输出文件

**目录与写入（P0）**：见 [SKILLS-FILE-OUTPUT.md](../SKILLS-FILE-OUTPUT.md)。

```
docs/coding-specs/coding.index.md           # 规范索引（必须优先读取）
docs/coding-specs/coding.api.md              # 接口规范
docs/coding-specs/coding.architecture.md     # 架构规范
docs/coding-specs/coding.data-models.md      # 数据模型规范
docs/coding-specs/coding.vue.md              # Vue 前端规范（仅 Vue 项目）
docs/coding-specs/coding.coding-style.md     # 编码风格规范
docs/coding-specs/coding.testing.md          # 测试规范
docs/coding-specs/coding.security.md         # 安全规范
docs/coding-specs/coding.performance.md     # 性能规范
docs/coding-specs/coding.documentation.md   # 文档规范
docs/coding-specs/coding.code-review.md     # 代码审查规范
docs/coding-specs/coding.version-control.md # 版本控制规范
```

**写入契约**：
- 本技能**只**向 `docs/coding-specs/` 写入上述文件名，**不得**写入其他目录
- `gen-code` 等技能**默认**从 `docs/coding-specs/` 读取规范

**模板来源**：技能自带 `templates/` 目录，与 `SKILL.md` 同级维护。

---

## 相关技能

- **gen-design**: 技术栈与边界确定后再生成本规范，避免与设计冲突
- **gen-code**: 主要消费者，须与上表写入路径一致
- **review-code**: 审查时对照本规范各分册
- **gen-test**: 测试约定以 `coding.testing.md` 为准

全链路见 [SKILL-VALUE-CHAIN.md](../SKILL-VALUE-CHAIN.md)。

---

*本技能替代原「command + instructions」安装方式；不再向 `.cursor/commands` 等目录安装命令文件。*