project-dev-standards

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

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

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

项目上下文协议 (Project Context Protocol) - CRITICAL

请严格遵守项目上下文强制协议：spec/PROJECT-CONTEXT.md 在执行本 Skill 之前，必须先建立项目认知。

你的任务

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

边界守卫 (Guardrails) - CRITICAL

请严格遵守通用边界守卫规则：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。