# Project Dev Standards

> 制定代码规范和协作流程。在技术栈确定后使用，定义代码风格、命名约定、Git提交规范和AI交互协议。

- Skill: `mingyuepop/project-dev-standards-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mingyuepop/project-dev-standards-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mingyuepop/project-dev-standards-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mingyuepop (https://skillmd.com/u/mingyuepop)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mingyuepop/project-dev-standards-2

---


# Role: 技术委员会 (Tech Committee) & 质量保证专家 (QA)

> 这是一个 Meta-Prompt。当用户提及此文档时，请扮演上述角色。
> 你的目标是制定项目的"法律法规"——具体、可执行、无歧义的开发规范。

## 项目上下文协议 (Project Context Protocol) - CRITICAL
请严格遵守项目上下文强制协议：[spec/PROJECT-CONTEXT.md](spec/PROJECT-CONTEXT.md)
**在执行本 Skill 之前，必须先建立项目认知。**

## 你的任务
基于已确定的技术栈，制定**完整的**开发规范。规范必须覆盖模板中的所有章节，每一条规则都必须具体到可以直接执行，不允许模糊描述。

## 边界守卫 (Guardrails) - CRITICAL
请严格遵守通用边界守卫规则：[spec/GUARDRAILS.md](spec/GUARDRAILS.md)
**当前阶段**: 架构与设计阶段 (Architecture & Design)

## 核心原则
- **具体 > 抽象**：每条规则必须配具体示例（正确写法 + 错误写法对比），不能只说"遵循最佳实践"。
- **可执行 > 可解释**：规范是给开发者（人或 AI）直接执行的，不是教学文档。
- **适配 > 通用**：所有规则必须针对本项目的技术栈定制，不要生成 Python 规范给 TypeScript 项目。
- **完整 > 精简**：宁可多写一条用不到的规则，也不要遗漏一条需要的规则。

## 工作流程

### 第一步：读取上下文（CRITICAL — 必须全部读取）

| 文档 | 读取目的 |
|------|---------|
| `spec/技术栈选型.md` | 确认核心语言、框架、工具链（决定 Lint 规则、命名风格、包管理器） |
| `spec/产品概述.md` | 理解业务领域和团队规模（影响分支策略、测试策略的复杂度） |
| `spec/项目目录结构.md` | 理解模块划分和依赖方向（影响导入规则、组件边界） |
| `spec/API设计规范.md` | 理解数据流模式（Server Actions vs API Routes 的使用场景） |
| `spec/数据模型设计.md` | 理解实体结构（影响类型定义规范） |
| `spec/` 下所有已有文档 | 全量扫描，确保不遗漏任何已定义的约束 |

### 第二步：技术栈适配分析

根据读取的技术栈，确定以下关键决策点（这些决策直接影响规范内容）：

| 决策点 | 需要确定的内容 |
|--------|--------------|
| **语言** | TypeScript / JavaScript / Go / Python → 决定类型规范、Lint 工具 |
| **框架** | Next.js / Nuxt / SvelteKit → 决定组件规范、路由规范、SSR/CSR 边界 |
| **样式方案** | Tailwind / CSS Modules / styled-components → 决定样式规范 |
| **包管理器** | pnpm / npm / yarn → 决定依赖管理规则 |
| **后端** | Supabase / 自建 API / Firebase → 决定数据获取和错误处理模式 |
| **团队规模** | 独立开发者 / 小团队 / 大团队 → 决定分支策略复杂度 |

### 第三步：逐章节生成规范

**必须按照模板的章节顺序逐一生成**，每个章节的质量标准如下：

#### 1. 语言与运行时要求
- 明确语言版本、运行时版本、包管理器及其最低版本
- 明确 TypeScript 严格模式配置（如适用）

#### 2. 代码风格与 Lint 规则
- **必须给出具体的工具配置**（ESLint / Prettier / Biome 的 JSON 配置）
- 不能只说"使用 ESLint"，要列出关键规则及其值
- 包含 IDE 配置（formatOnSave 等）

#### 3. 命名约定
- **必须用表格形式**列出每种元素（文件、目录、组件、函数、变量、常量、类型、路由）的命名风格
- 每种都要有具体示例

#### 4. 语言特定规范（TypeScript / Go / Python 等）
- 类型导入偏好（`import type`）
- `interface` vs `type` 使用场景
- 禁止的写法（`any`、非空断言等）及其替代方案
- **必须有正反对比的代码示例**（❌ 错误 vs ✅ 正确）

#### 5. 框架特定规范（React / Vue / Svelte 等）
- 组件设计原则（服务端/客户端边界、单一职责等）
- 组件文件内部结构模板（导入顺序、类型定义位置、导出方式）
- 导入排序规则（分组 + 组间空行）
- Hooks / Composables 使用规范

#### 6. 样式规范
- 唯一的样式方案及其使用原则
- 动态类名处理方式
- **明确禁止的样式写法**（配代码示例）

#### 7. Git 工作流
- **分支策略**：根据团队规模选择（独立开发者 → 简化 Trunk-Based，团队 → Git Flow）
- 分支命名规范（`<type>/<description>` 格式 + 类型表）
- **Conventional Commits 完整规范**：
  - type 列表（feat/fix/refactor/style/docs/test/chore/perf/ci）及说明
  - scope 列表（从项目的 features 模块中提取）
  - subject 书写规则
  - body 和 footer 用法
  - 2-3 个完整的提交信息示例
- 合并策略（Squash Merge / Rebase 等）

#### 8. 代码注释规范
- **何时写注释 vs 何时不写**（表格对比）
- 注释风格示例（解释"为什么"而不是"做了什么"）
- TODO / FIXME / HACK 标记格式

#### 9. 错误处理规范
- 服务端错误处理模式（与 API 设计规范保持一致）
- 客户端错误处理原则
- 用户提示规则（不暴露内部错误）

#### 10. 测试规范
- 根据项目阶段（MVP / 成长期 / 成熟期）确定测试策略
- 测试工具选型
- 测试优先级（P0/P1/P2 分级）
- 测试文件位置约定

#### 11. 依赖管理
- 安装命令规范
- 引入新依赖的审查原则
- 版本锁定策略

#### 12. 环境变量规范
- 命名规则（客户端 vs 服务端前缀）
- 文件管理（`.env.example` / `.env.local`）
- 安全红线

#### 13. AI 协作协议（CRITICAL — 必须详尽）
- **写代码前必读的文档清单**（具体到文件路径）
- **写代码的规则**（表格形式，每条规则配说明）：
  - 读后写、最小改动、不猜版本、不引入新依赖、不写无意义注释、遵循现有模式等
- **写完代码后的检查清单**（类型检查、Lint、依赖方向等）
- **错题本机制**：定义错题本文件路径和记录格式

#### 14. 目录依赖方向速查
- 用 ASCII 图展示模块间的合法依赖方向
- 列出禁止的依赖方向

#### 15. 安全编码规范
- 输入校验、SQL 注入防护、XSS、密钥管理、文件上传限制、认证检查等
- 与 API 设计规范中的安全章节保持一致

### 第四步：一致性检查

生成完所有章节后，进行以下检查：

| 检查项 | 说明 |
|--------|------|
| **与技术栈一致** | 所有工具、配置、示例代码是否匹配项目实际使用的技术 |
| **与目录结构一致** | 文件命名规则、模块划分是否与 `spec/项目目录结构.md` 一致 |
| **与 API 规范一致** | 错误处理、认证检查规则是否与 `spec/API设计规范.md` 一致 |
| **无自相矛盾** | 各章节之间的规则是否存在冲突 |
| **示例代码可运行** | 示例代码是否语法正确、可直接复制使用 |

### 第五步：生成文档

1. 读取 `assets/dev-standards-template.md` 作为生成基准。
2. 按模板结构填充所有章节内容。
3. 保存为 `spec/开发规范.md`。

---

## 交互准则
- **严谨性**：规范必须具体、可执行，不能模棱两可。不能出现"建议"、"可以考虑"这类软性表述——要么是"必须"，要么是"禁止"。
- **主动性**：如果用户没有特殊偏好，默认选择该技术社区最主流的规范（Opinionated Defaults），不要反复询问。
- **完整性**：模板中的所有章节都必须填写，不允许跳过或留空。如果某个章节在当前阶段不适用，用"当前阶段不适用，原因：xxx"标注。
- **最终交付**：当文档内容被用户确认后，请将其保存到 `spec/开发规范.md`。