From e7401f6109927fc474dca9f9277ac79a177ec2ee Mon Sep 17 00:00:00 2001 From: TommyLike Date: Sun, 8 Mar 2026 09:46:42 +0800 Subject: [PATCH] Add more spec command and hook --- CLAUDE.md | 17 +- README.md | 119 +++++--- .../project/.claude/commands/README.md | 16 +- .../project/.claude/commands/adr.md | 66 +++++ .../project/.claude/commands/api-design.md | 65 +++++ .../project/.claude/commands/debug.md | 54 ++++ .../project/.claude/commands/refactor.md | 66 +++++ .../project/.claude/commands/release-note.md | 47 +++ .../.claude/commands/security-check.md | 69 +++++ specification-example/team/CLAUDE.md | 5 + .../team/docs/standards/api-design.md | 268 ++++++++++++++++++ .../team/docs/standards/database.md | 216 ++++++++++++++ .../team/docs/standards/git-workflow.md | 161 +++++++++++ .../team/docs/standards/observability.md | 219 ++++++++++++++ .../team/docs/standards/release.md | 236 +++++++++++++++ 15 files changed, 1573 insertions(+), 51 deletions(-) create mode 100644 specification-example/project/.claude/commands/adr.md create mode 100644 specification-example/project/.claude/commands/api-design.md create mode 100644 specification-example/project/.claude/commands/debug.md create mode 100644 specification-example/project/.claude/commands/refactor.md create mode 100644 specification-example/project/.claude/commands/release-note.md create mode 100644 specification-example/project/.claude/commands/security-check.md create mode 100644 specification-example/team/docs/standards/api-design.md create mode 100644 specification-example/team/docs/standards/database.md create mode 100644 specification-example/team/docs/standards/git-workflow.md create mode 100644 specification-example/team/docs/standards/observability.md create mode 100644 specification-example/team/docs/standards/release.md diff --git a/CLAUDE.md b/CLAUDE.md index 36590be..b2d0c99 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,9 @@ --- ## 依赖 + 依赖Prettier组件用于格式化markdown等文件, 安装指令: + ``` npm install --save-dev --save-exact prettier ``` @@ -48,7 +50,12 @@ specification-example/ │ │ └── typescript.md # TypeScript 专项规范 │ ├── docs-writing.md # 文档写作规范 │ ├── security.md # 安全开发规范 -│ └── testing.md # 测试策略与规范 +│ ├── testing.md # 测试策略与规范 +│ ├── git-workflow.md # Git 分支、Commit、PR 流程 +│ ├── api-design.md # API 设计（REST/gRPC） +│ ├── database.md # 数据库设计与迁移 +│ ├── observability.md # 日志、指标、链路追踪 +│ └── release.md # 发布流程与回滚 ├── project/ # Layer 2：项目级规范模板 │ ├── CLAUDE.md # 项目 Claude 入口模板（含占位符，需按项目填写） │ ├── .claude/ @@ -58,7 +65,13 @@ specification-example/ │ │ ├── README.md # 命令列表索引 │ │ ├── review.md # /review：全面代码 Review │ │ ├── test.md # /test：生成单元测试 -│ │ └── migrate.md # /migrate：创建数据库迁移 +│ │ ├── migrate.md # /migrate：创建数据库迁移 +│ │ ├── debug.md # /debug：系统性排查 Bug +│ │ ├── release-note.md # /release-note：生成发布说明 +│ │ ├── adr.md # /adr：创建架构决策记录 +│ │ ├── security-check.md # /security-check：安全专项检查 +│ │ ├── refactor.md # /refactor：安全重构 +│ │ └── api-design.md # /api-design：设计 API 接口 │ └── docs/standards/ │ ├── build.md # 构建规范（每个项目必须填写） │ └── architecture.md # 项目架构说明（可选，覆盖团队层） diff --git a/README.md b/README.md index 13eda9c..aa756ef 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Claude 开发规范体系 -本仓库定义了团队使用 Claude Code 进行协作开发时的**三层规范体系**，确保 AI 辅助开发在团队、项目、个人三个维度上保持一致性。 +本仓库定义了团队使用Claude Code进行协作开发时的**三层规范体系**，确保AI辅助开发在团队、项目、个人三个维度上保持团队要求一致且个人风格保留。 --- @@ -39,7 +39,7 @@ Layer 1 · 团队层 本仓库 spec/teams/ ## 目录结构 ``` -README.md # 本文件，体系总览 +README.md # 本文件，体系总览 │ ├── spec/ # ★ 插件读取的实际规范内容 │ ├── teams/ # Layer 1：团队级规范（对所有项目生效） @@ -50,7 +50,12 @@ README.md # 本文件，体系总览 │ │ ├── coding/.md │ │ ├── testing.md │ │ ├── security.md -│ │ └── docs-writing.md +│ │ ├── docs-writing.md +│ │ ├── git-workflow.md # Git 分支、Commit、PR 流程 +│ │ ├── api-design.md # API 设计（REST/gRPC） +│ │ ├── database.md # 数据库设计与迁移 +│ │ ├── observability.md # 日志、指标、链路追踪 +│ │ └── release.md # 发布流程与回滚 │ └── project-templates/ # Layer 2：项目初始化模板 │ └── golang/ # Go 项目模板 │ ├── CLAUDE.md @@ -88,17 +93,22 @@ Claude Code 插件会在以下时机自动将 `spec/` 中的规范注入到对 团队所有成员都应参与规范的演进，而非只有技术负责人才能修改。 -| 文件 | 说明 | 维护方式 | -| ------------------------------------------------------- | -------------------------------------- | ---------------------------- | -| `spec/teams/docs/standards/architecture.md` | 架构原则与 ADR 机制 | 架构师主导，PR Review 决策 | -| `spec/teams/docs/standards/coding/base.md` | 通用编码规范（语言无关） | 全员提 PR，技术负责人 Review | -| `spec/teams/docs/standards/coding/go.md` | Go 专项规范 | Go 开发者维护 | -| `spec/teams/docs/standards/coding/python.md` | Python 专项规范 | Python 开发者维护 | -| `spec/teams/docs/standards/coding/typescript.md` | TypeScript 专项规范 | 前端/TS 开发者维护 | -| `spec/teams/docs/standards/testing.md` | 测试策略与规范 | 全员提 PR | -| `spec/teams/docs/standards/security.md` | 安全开发规范 | 安全负责人 + 全员提 PR | -| `spec/teams/docs/standards/docs-writing.md` | 文档写作规范 | 全员提 PR | -| `spec/project-templates//docs/standards/build.md` | 构建规范模板，**项目初始化后必须填写** | 项目负责人负责，开发者补充 | +| 文件
| 说明 | 维护方式 | +|---------------------------------------------------------|-----------------------|---------------------| +| `spec/teams/docs/standards/architecture.md` | 架构原则与 ADR 机制 | 架构师主导，PR Review 决策 | +| `spec/teams/docs/standards/coding/base.md` | 通用编码规范（语言无关） | 全员提 PR，技术负责人 Review | +| `spec/teams/docs/standards/coding/go.md` | Go 专项规范 | Go 开发者维护 | +| `spec/teams/docs/standards/coding/python.md` | Python 专项规范 | Python 开发者维护 | +| `spec/teams/docs/standards/coding/typescript.md` | TypeScript 专项规范 | 前端/TS 开发者维护 | +| `spec/teams/docs/standards/testing.md` | 测试策略与规范 | 全员提 PR | +| `spec/teams/docs/standards/security.md` | 安全开发规范 | 安全负责人 + 全员提 PR | +| `spec/teams/docs/standards/docs-writing.md` | 文档写作规范 | 全员提 PR | +| `spec/teams/docs/standards/git-workflow.md` | Git 工作流规范（分支、Commit、PR） | 全员提 PR，技术负责人 Review | +| `spec/teams/docs/standards/api-design.md` | API 设计规范（REST/gRPC） | 架构师主导，全员提 PR | +| `spec/teams/docs/standards/database.md` | 数据库设计与迁移规范 | DBA + 后端开发者维护 | +| `spec/teams/docs/standards/observability.md` | 日志与可观测性规范 | SRE / 后端开发者维护 | +| `spec/teams/docs/standards/release.md` | 发布流程与回滚规范 | 技术负责人主导，全员提 PR | +| `spec/project-templates//docs/standards/build.md` | 构建规范模板，**项目初始化后必须填写** | 项目负责人负责，开发者补充 | > **参考示例见 `specification-example/`，搜索 `[团队填写]` 找到所有待集体决策的空白。** @@ -106,11 +116,11 @@ Claude Code 插件会在以下时机自动将 `spec/` 中的规范注入到对 Commands 是效率工具，鼓励全员贡献。好的个人命令应提升为项目或团队命令。 -| 层级 | 位置 | 维护者 | 当前内容 | -| ------ | ------------------------------------------------- | ------------ | ---------------------------------------------- | -| 团队层 | `spec/project-templates//.claude/commands/` | 技术负责人 | 新项目初始化时注入 | -| 项目层 | `/.claude/commands/` | 项目团队全员 | `/review` `/test` `/migrate`（示例，按需扩展） | -| 个人层 | `~/.claude/commands/` | 个人自维护 | 不提交仓库，个人沉淀 | +| 层级 | 位置 | 维护者 | 当前内容 | +|-----|---------------------------------------------------|--------|---------------------------------------| +| 团队层 | `spec/project-templates//.claude/commands/` | 技术负责人 | 新项目初始化时注入 | +| 项目层 | `/.claude/commands/` | 项目团队全员 | 9 个示例命令（见下方列表，按需扩展） | +| 个人层 | `~/.claude/commands/` | 个人自维护 | 不提交仓库，个人沉淀 | **协作流程：** @@ -123,30 +133,41 @@ Commands 是效率工具，鼓励全员贡献。好的个人命令应提升为 ↓ 新项目初始化时自动包含 ``` -**扩展建议：** 以下场景适合沉淀为团队命令（欢迎贡献）： +**已提供的示例命令：** + +| 命令 | 用途 | +| --- | --- | +| `/review` | 对当前改动做全面代码 Review | +| `/test` | 为指定文件或功能生成单元测试 | +| `/migrate` | 创建数据库迁移文件 | +| `/debug` | 系统性排查 Bug（假设 → 验证 → 修复） | +| `/release-note` | 从 git log 生成发布说明 | +| `/adr` | 创建架构决策记录（ADR） | +| `/security-check` | 对当前改动做安全专项检查 | +| `/refactor` | 指导安全重构（保持行为不变） | +| `/api-design` | 设计 API 接口（遵循 API 规范） | + +**欢迎继续贡献新命令：** -- `/debug`：系统性排查 bug（读日志 → 假设 → 验证） -- `/release-note`：从 git log 生成发布说明 -- `/security-check`：针对 PR 的安全专项检查 - `/onboard`：新成员项目快速上手引导 -- `/adr`：创建架构决策记录（ADR） +- 更多领域命令（按团队实际需求沉淀） ### Hooks 配置（.claude/settings.json） Hooks 是 Claude Code 的自动化防护层，应随项目成熟度逐步加强。 -| 层级 | 位置 | 维护者 | 提交仓库 | -| ------------------ | --------------------------------- | ---------- | ---------------------------- | +| 层级 | 位置 | 维护者 | 提交仓库 | +|-----------|-----------------------------------|-------|------------------| | 项目层（团队共享） | `/.claude/settings.json` | 项目负责人 | **是**（质量门禁对全员生效） | -| 个人层（个人偏好） | `~/.claude/settings.json` | 个人 | 否 | +| 个人层（个人偏好） | `~/.claude/settings.json` | 个人 | 否 | **当前项目模板已包含的 Hooks（`project/.claude/settings.json`）：** -| Hook | 事件 | 作用 | -| -------------- | -------------------------- | ------------------------------------- | -| 阻止 push main | `PreToolUse` (Bash) | 防止 Claude 直接推送到保护分支 | +| Hook | 事件 | 作用 | +|--------------|----------------------------|------------------------| +| 阻止 push main | `PreToolUse` (Bash) | 防止 Claude 直接推送到保护分支 | | 自动 lint | `PostToolUse` (Edit/Write) | 文件修改后自动检查，结果反馈给 Claude | -| 完成通知 | `Stop` | 长任务完成后发送桌面通知 | +| 完成通知 | `Stop` | 长任务完成后发送桌面通知 | **建议逐步补充的 Hooks：** @@ -195,10 +216,15 @@ cp specification-example/personal/CLAUDE.md ~/.claude/CLAUDE.md 团队级规范存放在本仓库 `spec/teams/docs/standards/`，涵盖： -- 编码规范（通用 + 各语言专项） +- 编码规范（通用 + Go / Python / TypeScript 专项） - 测试策略 - 安全开发要求 - 文档写作规范 +- Git 工作流（分支、Commit、PR 流程） +- API 设计（REST/gRPC） +- 数据库设计与迁移 +- 日志与可观测性 +- 发布流程与回滚 插件会自动将这些规范注入 Claude 上下文，通常无需手动阅读全部，但遇到规范相关问题时可直接查阅。 @@ -212,7 +238,7 @@ cp specification-example/personal/CLAUDE.md ~/.claude/CLAUDE.md - 项目根目录 `CLAUDE.md`（含团队规范引用） - `.claude/settings.json`（Hooks：防护 + 自动 lint + 完成通知） -- `.claude/commands/`（`/review` `/test` `/migrate` 等基础命令） +- `.claude/commands/`（9 个基础命令：`/review` `/test` `/migrate` `/debug` `/release-note` `/adr` `/security-check` `/refactor` `/api-design`） - `docs/standards/build.md`（待填写的构建规范模板） **方式二：手动复制** @@ -264,17 +290,22 @@ git commit -m "feat: add / command for <用途>" ## 文件命名约定 -| 规范类型 | 文件名 | 层级 | -| ---------- | --------------------------------- | ------------ | -| 架构规范 | `docs/standards/architecture.md` | 团队 / 项目 | -| 编码基础 | `docs/standards/coding/base.md` | 团队 | -| 语言规范 | `docs/standards/coding/.md` | 团队 | -| 测试规范 | `docs/standards/testing.md` | 团队 | -| 安全规范 | `docs/standards/security.md` | 团队 | -| 文档规范 | `docs/standards/docs-writing.md` | 团队 | -| 构建规范 | `docs/standards/build.md` | 项目（必填） | -| 自定义命令 | `.claude/commands/.md` | 项目 / 个人 | -| Hooks 配置 | `.claude/settings.json` | 项目 / 个人 | +| 规范类型 | 文件名 | 层级 | +| ------------ | --------------------------------- | ------------ | +| 架构规范 | `docs/standards/architecture.md` | 团队 / 项目 | +| 编码基础 | `docs/standards/coding/base.md` | 团队 | +| 语言规范 | `docs/standards/coding/.md` | 团队 | +| 测试规范 | `docs/standards/testing.md` | 团队 | +| 安全规范 | `docs/standards/security.md` | 团队 | +| 文档规范 | `docs/standards/docs-writing.md` | 团队 | +| Git 工作流 | `docs/standards/git-workflow.md` | 团队 | +| API 设计 | `docs/standards/api-design.md` | 团队 | +| 数据库设计 | `docs/standards/database.md` | 团队 | +| 可观测性 | `docs/standards/observability.md` | 团队 | +| 发布流程 | `docs/standards/release.md` | 团队 | +| 构建规范 | `docs/standards/build.md` | 项目（必填） | +| 自定义命令 | `.claude/commands/.md` | 项目 / 个人 | +| Hooks 配置 | `.claude/settings.json` | 项目 / 个人 | --- diff --git a/specification-example/project/.claude/commands/README.md b/specification-example/project/.claude/commands/README.md index 69dbd43..76a7d75 100644 --- a/specification-example/project/.claude/commands/README.md +++ b/specification-example/project/.claude/commands/README.md @@ -4,11 +4,17 @@ ## 命令索引 -| 命令 | 文件 | 说明 | -| ---------- | ------------ | -------------------------------- | -| `/review` | `review.md` | 对当前 git 改动做全面代码 Review | -| `/test` | `test.md` | 为指定文件或功能描述生成单元测试 | -| `/migrate` | `migrate.md` | 创建数据库迁移文件 | +| 命令 | 文件 | 说明 | +| ----------------- | ------------------- | -------------------------------- | +| `/review` | `review.md` | 对当前 git 改动做全面代码 Review | +| `/test` | `test.md` | 为指定文件或功能描述生成单元测试 | +| `/migrate` | `migrate.md` | 创建数据库迁移文件 | +| `/debug` | `debug.md` | 系统性排查 Bug（假设→验证→修复） | +| `/release-note` | `release-note.md` | 从 git log 生成发布说明 | +| `/adr` | `adr.md` | 创建架构决策记录（ADR） | +| `/security-check` | `security-check.md` | 对当前改动做安全专项检查 | +| `/refactor` | `refactor.md` | 指导安全重构（保持行为不变） | +| `/api-design` | `api-design.md` | 设计 API 接口（遵循 API 规范） | ## 如何新增命令 diff --git a/specification-example/project/.claude/commands/adr.md b/specification-example/project/.claude/commands/adr.md new file mode 100644 index 0000000..c35d195 --- /dev/null +++ b/specification-example/project/.claude/commands/adr.md @@ -0,0 +1,66 @@ +# 创建架构决策记录（ADR） + +为以下决策创建 ADR 文档：$ARGUMENTS + +## 执行步骤 + +### 1. 确定编号 + +查看现有 ADR 文件，确定下一个序号： + +```bash +ls docs/adr/ 2>/dev/null || echo "目录不存在，将创建 docs/adr/" +``` + +### 2. 生成 ADR 文件 + +文件路径：`docs/adr/NNNN-.md` + +使用以下模板： + +```markdown +# NNNN. <决策标题> + +**日期：** YYYY-MM-DD +**状态：** 提议（Proposed）/ 已接受（Accepted）/ 已废弃（Deprecated）/ 已取代（Superseded by NNNN） + +## 背景 + +描述导致此决策的上下文和问题。包括： +- 当前面临的问题或需求 +- 相关的技术约束和业务约束 +- 已有的系统现状 + +## 决策 + +明确说明做出的决策。 + +## 备选方案 + +### 方案 A：<名称> +- **描述：** ... +- **优点：** ... +- **缺点：** ... + +### 方案 B：<名称> +- **描述：** ... +- **优点：** ... +- **缺点：** ... + +## 结论 + +解释为什么选择了当前方案，关键 trade-off 是什么。 + +## 影响 + +- 对现有系统的影响 +- 需要的后续工作 +- 潜在风险及应对措施 +``` + +### 3. 注意事项 + +- ADR 一旦状态为 Accepted，**不修改原文**，只能通过新 ADR 取代 +- 标题简明扼要，反映核心决策点 +- 备选方案的分析必须客观，列出各方案的 trade-off +- 如果取代了旧 ADR，在旧 ADR 中标注 `Superseded by NNNN` diff --git a/specification-example/project/.claude/commands/api-design.md b/specification-example/project/.claude/commands/api-design.md new file mode 100644 index 0000000..e16078d --- /dev/null +++ b/specification-example/project/.claude/commands/api-design.md @@ -0,0 +1,65 @@ +# 设计 API 接口 + +为以下需求设计 API 接口：$ARGUMENTS + +请参考 `docs/standards/api-design.md` 中定义的 API 设计规范。 + +## 执行步骤 + +### 1. 需求分析 + +- 明确接口服务的对象（前端 / 移动端 / 其他服务 / 第三方） +- 列出需要支持的操作（CRUD / 查询 / 动作） +- 确认是否有现有相关接口（避免重复或冲突） + +### 2. 资源建模 + +确定核心资源及其关系： + +``` +资源：<名称> +属性：id, field1, field2, ... +关系：belongs_to <父资源>, has_many <子资源> +``` + +### 3. 接口设计 + +为每个操作设计 endpoint： + +``` +<HTTP方法> <URL路径> +描述：... +请求参数：... +请求体：{ ... } +成功响应：{ code: 0, data: { ... } } +错误响应：{ code: <错误码>, message: "..." } +``` + +### 4. 输出格式 + +输出完整的接口列表，包含： + +| 方法 | 路径 | 描述 | 认证 | +| --- | --- | --- | --- | +| GET | /v1/resources | 获取列表 | 是 | +| POST | /v1/resources | 创建资源 | 是 | +| ... | ... | ... | ... | + +每个接口的详细说明： + +- 请求参数 / 请求体定义 +- 响应结构（成功 + 错误） +- 分页方式（如为列表接口） +- 权限要求 + +### 5. 检查清单 + +设计完成后自查： + +- [ ] URL 使用复数名词，kebab-case +- [ ] HTTP 方法语义正确（GET 不改数据，PUT 幂等） +- [ ] 统一响应格式（code + message + data） +- [ ] 错误码按规范编号 +- [ ] 分页参数与团队规范一致 +- [ ] 列出了所有可能的错误码 +- [ ] 兼容性考虑（是否会破坏现有接口） diff --git a/specification-example/project/.claude/commands/debug.md b/specification-example/project/.claude/commands/debug.md new file mode 100644 index 0000000..d22e6d0 --- /dev/null +++ b/specification-example/project/.claude/commands/debug.md @@ -0,0 +1,54 @@ +# 系统性排查 Bug + +请系统性排查以下问题：$ARGUMENTS + +## 排查流程 + +按以下步骤逐一执行，**不要跳步**： + +### 1. 收集信息 + +- 阅读相关错误日志、异常堆栈 +- 确认问题复现条件（环境、输入、操作路径） +- 检查最近的代码变更（`git log --oneline -10`、`git diff`） + +### 2. 形成假设 + +基于收集到的信息，列出 **1-3 个可能的原因**，按可能性排序： + +``` +假设 1（最可能）：... +假设 2：... +假设 3：... +``` + +### 3. 逐一验证 + +从最可能的假设开始，**每次只验证一个假设**： + +- 说明验证方法（加日志 / 读代码 / 写测试 / 检查数据） +- 执行验证 +- 得出结论：证实 or 排除 + +### 4. 定位根因 + +确认根因后： + +- 解释为什么会出现这个问题（根因，而非表象） +- 说明影响范围（是否影响其他功能） + +### 5. 修复方案 + +提出修复方案前，先说明： + +- 修复方案（代码变更） +- 是否需要同步修复其他位置 +- 如何验证修复生效 +- 是否需要补充测试用例 + +## 注意事项 + +- 不要在未定位根因时就尝试修复 +- 不要一次修改多个地方——最小化变更，逐步验证 +- 优先通过阅读代码和日志定位，避免盲目加 print/log +- 如果涉及第三方服务，先确认对方状态（API 可用性、版本变更） diff --git a/specification-example/project/.claude/commands/refactor.md b/specification-example/project/.claude/commands/refactor.md new file mode 100644 index 0000000..aa5ff66 --- /dev/null +++ b/specification-example/project/.claude/commands/refactor.md @@ -0,0 +1,66 @@ +# 安全重构 + +对以下代码进行重构：$ARGUMENTS + +## 核心原则 + +**重构 = 在不改变外部行为的前提下改善代码结构。** + +## 执行步骤 + +### 1. 理解现状 + +- 阅读目标代码及其调用方和被调用方 +- 确认当前行为（有哪些测试覆盖） +- 列出代码的坏味道（Code Smell） + +### 2. 确认测试覆盖 + +在动手重构前，确认测试覆盖情况： + +- 如果已有充分测试 → 继续 +- 如果测试不足 → **先补测试，再重构** +- 展示当前测试覆盖情况，等待用户确认 + +### 3. 制定重构计划 + +列出重构步骤，每步应该是： + +- 独立的、可编译的变更 +- 有明确的目的（消除哪个坏味道） +- 可通过已有测试验证 + +常见重构手法： + +| 手法 | 适用场景 | +| --- | --- | +| 提取函数 | 函数过长、职责混杂 | +| 内联函数 | 间接层过多、函数体比函数名更清晰 | +| 提取变量 | 复杂表达式 | +| 重命名 | 名称不能反映意图 | +| 移动函数/字段 | 功能放错了位置 | +| 引入参数对象 | 参数过多 | +| 以多态取代条件 | 大量 if-else / switch | +| 拆分循环 | 一个循环做多件事 | + +### 4. 逐步执行 + +每次只做一个重构步骤： + +1. 执行重构 +2. 运行测试确认行为不变 +3. 确认通过后进入下一步 + +### 5. 验证结果 + +重构完成后： + +- 运行全部相关测试 +- 对比重构前后的公开接口（应完全一致） +- 说明改善了什么（可读性 / 可维护性 / 可测试性） + +## 禁止事项 + +- **不在重构中混入功能变更**——如果需要改行为，分开做 +- **不在没有测试的情况下大规模重构** +- **不为重构而重构**——必须有明确的改善目标 diff --git a/specification-example/project/.claude/commands/release-note.md b/specification-example/project/.claude/commands/release-note.md new file mode 100644 index 0000000..9a8bd0f --- /dev/null +++ b/specification-example/project/.claude/commands/release-note.md @@ -0,0 +1,47 @@ +# 生成发布说明 + +根据 Git 提交历史，生成本次发布的 Release Note。 + +## 执行步骤 + +### 1. 获取变更范围 + +确定上次发布的 Tag 和当前 HEAD 之间的所有变更： + +```bash +# 获取最新 Tag +git describe --tags --abbrev=0 + +# 查看自上次 Tag 以来的所有 commit +git log <上次Tag>..HEAD --oneline --no-merges +``` + +如果用户指定了范围，使用 $ARGUMENTS 作为 git log 的范围参数。 + +### 2. 分类整理 + +按 Conventional Commits 类型分类，使用 Keep a Changelog 格式输出： + +```markdown +## [版本号] - YYYY-MM-DD + +### Added +- 新增 xxx 功能 (#PR编号) + +### Changed +- 优化 xxx 行为 (#PR编号) + +### Fixed +- 修复 xxx 问题 (#PR编号) + +### Breaking Changes +- 移除 xxx 接口，请使用 yyy 代替 (#PR编号) +``` + +### 3. 输出规则 + +- 每条记录关联 PR 编号或 commit hash +- 面向使用者而非开发者描述（说影响，不说实现） +- Breaking Changes 必须单独列出，并说明迁移方法 +- 忽略 `chore`、`ci`、`style` 类型的 commit（不影响功能） +- 如果 commit message 不规范，根据代码变更内容推断分类 diff --git a/specification-example/project/.claude/commands/security-check.md b/specification-example/project/.claude/commands/security-check.md new file mode 100644 index 0000000..b809446 --- /dev/null +++ b/specification-example/project/.claude/commands/security-check.md @@ -0,0 +1,69 @@ +# 安全专项检查 + +对当前改动执行安全专项 Review。 + +请参考 `docs/standards/security.md` 中定义的安全规范。 + +## 检查范围 + +获取当前改动： + +```bash +git diff --cached --name-only 2>/dev/null || git diff HEAD~1 --name-only +``` + +如果用户指定了文件，检查 $ARGUMENTS 指定的文件。 + +## 检查维度 + +按以下维度逐一检查，**每个维度独立给出结论**： + +### 1. 输入验证 + +- 所有外部输入（HTTP 参数、消息体、URL 参数）是否经过校验 +- 是否使用白名单方式验证（而非黑名单） +- 文件上传是否验证类型和大小 + +### 2. 注入防护 + +- SQL 操作是否使用参数化查询 / ORM +- 是否存在命令注入风险（拼接 shell 命令） +- 模板渲染是否防御 XSS（输出转义） + +### 3. 认证与权限 + +- 需要认证的接口是否校验了 Token/Session +- 是否存在越权风险（水平越权：访问他人数据；垂直越权：普通用户执行管理操作） +- 权限检查是否在数据访问之前 + +### 4. 敏感数据 + +- 是否有硬编码的密钥、Token、密码 +- 日志中是否输出了敏感信息（密码、身份证号、信用卡号） +- 响应中是否返回了不必要的敏感字段 + +### 5. 依赖安全 + +- 新增依赖是否有已知漏洞 +- 是否使用了固定版本（而非 latest 或 `^`） + +### 6. 加密与通信 + +- 敏感数据传输是否使用 HTTPS/TLS +- 密码存储是否使用 bcrypt/argon2（而非 MD5/SHA） +- 加密密钥是否通过密钥管理服务获取（而非硬编码） + +## 输出格式 + +``` +## 安全检查结果 + +### 🔴 必须修复 +- [文件:行号] 问题描述 → 修复建议 + +### 🟡 建议改进 +- [文件:行号] 问题描述 → 改进建议 + +### 🟢 检查通过 +- 简要列出已通过的检查项 +``` diff --git a/specification-example/team/CLAUDE.md b/specification-example/team/CLAUDE.md index f5180fd..242077e 100644 --- a/specification-example/team/CLAUDE.md +++ b/specification-example/team/CLAUDE.md @@ -15,6 +15,11 @@ Claude 在本项目中工作时，请阅读并遵循以下规范文件： - **测试规范** → `docs/standards/testing.md` - **安全规范** → `docs/standards/security.md` - **文档写作规范** → `docs/standards/docs-writing.md` +- **Git 工作流规范** → `docs/standards/git-workflow.md` +- **API 设计规范** → `docs/standards/api-design.md` +- **数据库设计规范** → `docs/standards/database.md` +- **日志与可观测性规范** → `docs/standards/observability.md` +- **发布流程规范** → `docs/standards/release.md` --- diff --git a/specification-example/team/docs/standards/api-design.md b/specification-example/team/docs/standards/api-design.md new file mode 100644 index 0000000..17fa157 --- /dev/null +++ b/specification-example/team/docs/standards/api-design.md @@ -0,0 +1,268 @@ +# API 设计规范 + +> 本文件定义团队 HTTP/gRPC API 的设计约定。 +> 所有对外和对内的接口设计均应遵循本规范，确保服务间协作一致性。 + +--- + +## RESTful 设计原则 + +### URL 设计 + +``` +# 格式 +/<version>/<resource>/<id>/<sub-resource> + +# 示例 +GET /v1/users # 获取用户列表 +POST /v1/users # 创建用户 +GET /v1/users/123 # 获取单个用户 +PUT /v1/users/123 # 全量更新用户 +PATCH /v1/users/123 # 部分更新用户 +DELETE /v1/users/123 # 删除用户 +GET /v1/users/123/orders # 获取用户的订单列表 +``` + +**规则：** + +- 资源名使用**复数名词**（`users` 而非 `user`），kebab-case +- URL 中不包含动词（用 HTTP 方法表达语义） +- 嵌套不超过 2 层（`/users/123/orders`，不要 `/users/123/orders/456/items`） +- 非 CRUD 操作使用动词后缀：`POST /v1/orders/123/cancel` + +### HTTP 方法语义 + +| 方法 | 语义 | 幂等 | 安全 | +| --- | --- | --- | --- | +| GET | 查询，不改变状态 | 是 | 是 | +| POST | 创建资源 / 触发操作 | 否 | 否 | +| PUT | 全量替换资源 | 是 | 否 | +| PATCH | 部分更新资源 | 否 | 否 | +| DELETE | 删除资源 | 是 | 否 | + +### 版本策略 + +> [团队填写] 选择版本方案： +> +> - **URL Path 版本**（推荐）：`/v1/users`，简单直观 +> - **Header 版本**：`Accept: application/vnd.api+json; version=1` + +**版本升级规则：** + +- PATCH 版本：Bug 修复，无需升级 API 版本 +- 新增可选字段：不升级版本 +- 删除字段 / 修改字段类型 / 变更行为：必须升级 Major 版本 + +--- + +## 请求与响应格式 + +### 统一响应结构 + +**成功响应：** + +```json +{ + "code": 0, + "message": "success", + "data": { + "id": "abc-123", + "name": "example" + } +} +``` + +**列表响应（含分页）：** + +```json +{ + "code": 0, + "message": "success", + "data": { + "items": [...], + "pagination": { + "total": 100, + "page": 1, + "page_size": 20, + "has_next": true + } + } +} +``` + +**错误响应：** + +```json +{ + "code": 10001, + "message": "user not found", + "details": [ + { + "field": "user_id", + "reason": "no user with id 'abc-123'" + } + ] +} +``` + +### HTTP 状态码使用 + +| 状态码 | 含义 | 使用场景 | +| --- | --- | --- | +| 200 | OK | GET/PUT/PATCH/DELETE 成功 | +| 201 | Created | POST 创建成功 | +| 204 | No Content | DELETE 成功（无返回体） | +| 400 | Bad Request | 请求参数校验失败 | +| 401 | Unauthorized | 未认证（Token 缺失或过期） | +| 403 | Forbidden | 已认证但无权限 | +| 404 | Not Found | 资源不存在 | +| 409 | Conflict | 资源冲突（重复创建、版本冲突） | +| 422 | Unprocessable Entity | 参数格式正确但业务校验失败 | +| 429 | Too Many Requests | 限流 | +| 500 | Internal Server Error | 服务端未预期错误 | + +--- + +## 错误码体系 + +### 编号规则 + +``` +<服务编号><模块编号><序号> + +示例： +10001 - 用户服务(1) + 用户模块(00) + 第1个错误 +20101 - 订单服务(2) + 支付模块(01) + 第1个错误 +``` + +> [团队填写] 各服务编号分配表： +> +> | 编号 | 服务 | +> | --- | --- | +> | 1 | [填写] | +> | 2 | [填写] | + +### 通用错误码 + +| 错误码 | 含义 | +| --- | --- | +| 0 | 成功 | +| 400xx | 通用参数错误 | +| 401xx | 认证错误 | +| 403xx | 权限错误 | +| 404xx | 资源不存在 | +| 429xx | 限流 | +| 500xx | 服务内部错误 | + +--- + +## 分页规范 + +### 偏移量分页（适合管理后台） + +``` +GET /v1/users?page=2&page_size=20 + +# 默认值 +page_size: 20（最大 100） +page: 1 +``` + +### 游标分页（适合移动端 / 信息流） + +``` +GET /v1/users?cursor=eyJpZCI6MTIzfQ&limit=20 + +# 响应中返回 next_cursor +{ + "data": { + "items": [...], + "next_cursor": "eyJpZCI6MTQzfQ", + "has_next": true + } +} +``` + +> [团队填写] 默认分页方式：偏移量 / 游标 + +--- + +## 查询与过滤 + +``` +# 等值过滤 +GET /v1/users?status=active&role=admin + +# 范围过滤 +GET /v1/orders?created_at_gte=2024-01-01&created_at_lte=2024-12-31 + +# 排序（默认降序） +GET /v1/users?sort_by=created_at&sort_order=desc + +# 模糊搜索 +GET /v1/users?q=john + +# 字段选择（可选） +GET /v1/users?fields=id,name,email +``` + +**命名约定：** + +- 过滤参数使用 snake_case +- 范围过滤后缀：`_gte`（>=）、`_lte`（<=）、`_gt`（>）、`_lt`（<） +- 布尔参数使用 `is_` 前缀：`is_active=true` + +--- + +## 接口兼容性 + +### 不兼容变更（必须升级版本） + +- 删除已有字段 +- 修改字段类型（如 `string` → `int`） +- 修改字段语义（如 `status` 枚举值含义变化） +- 修改 URL 路径 +- 新增必填参数 + +### 兼容变更（无需升级版本） + +- 新增可选请求参数 +- 新增响应字段 +- 新增新的 API endpoint +- 新增错误码 + +--- + +## gRPC 规范 + +> [团队填写] 如团队使用 gRPC，补充以下约定： + +### Proto 文件组织 + +``` +proto/ +├── <service>/ +│ └── v1/ +│ ├── <service>.proto # Service 定义 +│ └── <resource>.proto # Message 定义 +└── common/ + └── v1/ + └── pagination.proto # 公共消息定义 +``` + +### 命名约定 + +- Package：`<company>.<service>.v1` +- Service：`PascalCase`，以 `Service` 结尾 +- RPC 方法：`PascalCase`，动词开头（`GetUser`、`ListOrders`、`CreateOrder`） +- Message：`PascalCase`，Request/Response 后缀 +- 字段：`snake_case` + +--- + +## API 文档要求 + +- HTTP API 使用 OpenAPI 3.0 规范描述，文件为 `openapi.yaml` +- gRPC API 的文档写在 Proto 文件注释中 +- 每个 endpoint 必须包含：描述、请求参数说明、响应示例、错误码列表 +- API 文档与代码同步更新，不允许文档落后于实现 diff --git a/specification-example/team/docs/standards/database.md b/specification-example/team/docs/standards/database.md new file mode 100644 index 0000000..fefe320 --- /dev/null +++ b/specification-example/team/docs/standards/database.md @@ -0,0 +1,216 @@ +# 数据库设计与迁移规范 + +> 本文件定义团队数据库设计、命名和迁移操作的统一约定。 +> Claude 在生成 Migration 或修改数据库相关代码时必须遵循本规范。 + +--- + +## 命名规范 + +### 表名 + +- 使用 **snake_case**，**复数形式** +- 关联表命名：`<表A>_<表B>`，按字母序排列 +- 不使用数据库保留字 + +``` +✅ users, orders, order_items, user_roles +❌ User, OrderItem, user_role, data, status +``` + +### 字段名 + +- 使用 **snake_case** +- 布尔字段使用 `is_` / `has_` / `can_` 前缀 +- 时间字段使用 `_at` 后缀 +- 外键使用 `<关联表单数>_id` + +``` +✅ user_id, is_active, created_at, has_permission +❌ userId, active, createTime, permission +``` + +### 索引命名 + +``` +idx_<table>_<columns> # 普通索引 +udx_<table>_<columns> # 唯一索引 +fk_<table>_<ref_table> # 外键约束 + +示例： +idx_orders_user_id +udx_users_email +idx_orders_status_created_at +``` + +--- + +## 主键策略 + +> [团队填写] 选择主键类型： +> +> - **UUID v4**：全局唯一，适合分布式系统，无序 +> - **UUID v7**：时间有序 UUID，兼顾唯一性和索引性能（推荐） +> - **自增 ID**：简单高效，但分布式场景受限 +> - **Snowflake**：有序长整型，需要额外基础设施 + +--- + +## 必备字段 + +每张业务表必须包含以下字段： + +```sql +id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 或按团队主键策略 +created_at TIMESTAMP NOT NULL DEFAULT NOW(), +updated_at TIMESTAMP NOT NULL DEFAULT NOW(), +deleted_at TIMESTAMP NULL -- 软删除标记 +``` + +**规则：** + +- 所有时间字段存储为 **UTC** +- 使用**软删除**（`deleted_at IS NOT NULL` 表示已删除），不物理删除业务数据 +- `updated_at` 通过数据库触发器或 ORM 自动维护 + +--- + +## 字段设计原则 + +### 类型选择 + +| 场景 | 推荐类型 | 避免 | +| --- | --- | --- | +| 主键 | UUID / BIGINT | INT（容量不足） | +| 金额 | DECIMAL(19,4) | FLOAT / DOUBLE | +| 状态枚举 | VARCHAR + 应用层约束 | 数据库 ENUM（变更困难） | +| JSON 数据 | JSONB（PostgreSQL） | TEXT 存 JSON | +| 长文本 | TEXT | VARCHAR(9999) | +| 布尔 | BOOLEAN | TINYINT | + +### 约束要求 + +- NOT NULL：除非业务上确实允许空值，否则必须 NOT NULL +- DEFAULT：有合理默认值的字段必须设置 DEFAULT +- 唯一约束：业务上唯一的字段（email、手机号）必须加唯一索引 +- 外键：[团队填写] 是否使用数据库外键约束（推荐应用层维护，避免数据库外键） + +--- + +## 索引设计 + +### 何时加索引 + +- WHERE 条件中频繁使用的字段 +- JOIN 关联字段 +- ORDER BY / GROUP BY 字段 +- 唯一性约束字段 + +### 索引原则 + +1. **单表索引不超过 5 个**（写入性能考虑） +2. **联合索引遵循最左前缀原则**，高选择性字段在前 +3. **覆盖索引**优先于回表查询 +4. **不要在低基数字段单独建索引**（如 `status` 只有 3 个值） +5. **大表加索引必须走 Migration + Online DDL**，不允许直接 ALTER + +--- + +## Migration 规范 + +### 文件命名 + +``` +migrations/<timestamp>_<description>.sql + +示例： +migrations/20240315143000_create_users_table.sql +migrations/20240315150000_add_email_index_to_users.sql +``` + +- 时间戳格式：`YYYYMMDDHHmmss` +- 描述使用 snake_case，说明变更内容 +- 每个 Migration 文件必须包含 **UP** 和 **DOWN** 部分 + +### Migration 文件结构 + +```sql +-- +migrate Up +CREATE TABLE users ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + email VARCHAR(255) NOT NULL, + name VARCHAR(100) NOT NULL, + is_active BOOLEAN NOT NULL DEFAULT true, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW(), + deleted_at TIMESTAMP NULL +); + +CREATE UNIQUE INDEX udx_users_email ON users (email) WHERE deleted_at IS NULL; + +-- +migrate Down +DROP INDEX IF EXISTS udx_users_email; +DROP TABLE IF EXISTS users; +``` + +### Migration 规则 + +1. **已部署的 Migration 文件禁止修改**——只能通过新 Migration 修正 +2. **每个 Migration 只做一件事**（不要在一个文件中建表 + 改另一张表） +3. **必须可回滚**——DOWN 部分必须完整 +4. **大表变更必须评估影响**： + - 新增列：必须有 DEFAULT 值或允许 NULL + - 删除列：先停止代码引用 → 部署 → 再删列（两步走） + - 加索引：使用 `CONCURRENTLY`（PostgreSQL）避免锁表 +5. **数据回填（Backfill）** 不放在 Migration 中，单独编写脚本 +6. **涉及大表 DDL，提前知会 DBA** + +### 数据回填规范 + +```sql +-- 文件：scripts/backfill_20240315_user_status.sql +-- 说明：将所有未设置 status 的用户默认设置为 active +-- 影响行数预估：约 50000 行 +-- 是否可重复执行：是 + +UPDATE users +SET status = 'active', updated_at = NOW() +WHERE status IS NULL; +``` + +**要求：** + +- 回填脚本必须**幂等**（可重复执行） +- 注明预估影响行数 +- 大批量数据分批处理（每批 1000-5000 行） + +--- + +## 查询规范 + +### 必须遵守的规则 + +1. **禁止 SELECT \***——明确列出需要的字段 +2. **禁止无 WHERE 的 UPDATE / DELETE** +3. **分页查询必须有排序条件**——否则结果不确定 +4. **大表查询必须走索引**——未命中索引的慢查询需优化 +5. **多租户场景**：所有查询必须携带 `tenant_id` 过滤 + +### 慢查询标准 + +> [团队填写] 慢查询阈值： +> +> - 单次查询 > [填写] ms 视为慢查询 +> - 慢查询必须记录日志并定期 Review + +--- + +## Claude 行为约束 + +Claude 在执行数据库相关操作时必须遵守： + +1. **生成 Migration 时**：必须包含 UP 和 DOWN，并遵循命名规范 +2. **修改表结构前**：展示完整 SQL 并等待用户确认 +3. **不执行 DROP TABLE / TRUNCATE**：除非用户明确要求并确认 +4. **不生成 SELECT \***：必须明确列出字段 +5. **涉及已上线表的变更**：提醒用户评估影响并考虑两步走策略 diff --git a/specification-example/team/docs/standards/git-workflow.md b/specification-example/team/docs/standards/git-workflow.md new file mode 100644 index 0000000..8f8408e --- /dev/null +++ b/specification-example/team/docs/standards/git-workflow.md @@ -0,0 +1,161 @@ +# Git 工作流规范 + +> 本文件定义团队 Git 协作流程的统一约定。 +> 所有团队成员在使用 Claude Code 时，Claude 应遵循本规范进行分支、提交和合并操作。 + +--- + +## 分支策略 + +### 主分支 + +| 分支 | 用途 | 保护规则 | +| --- | --- | --- | +| `main` | 生产代码，始终可部署 | 禁止直接 push，必须通过 PR 合并 | +| `develop` | 开发主线（如采用 Git Flow） | 禁止直接 push，必须通过 PR 合并 | + +> [团队填写] 选择分支模型： +> +> - **Trunk-based**：只有 `main`，短生命周期 feature 分支，频繁合并 +> - **GitHub Flow**：`main` + feature 分支，PR 合并后直接部署 +> - **Git Flow**：`main` + `develop` + feature/release/hotfix 分支 + +### 分支命名规范 + +``` +feat/<ticket-id>-<short-desc> # 新功能 +fix/<ticket-id>-<short-desc> # Bug 修复 +hotfix/<ticket-id>-<short-desc> # 生产紧急修复 +refactor/<ticket-id>-<short-desc> # 重构（不改变行为） +chore/<short-desc> # 构建、CI、依赖等非业务变更 +docs/<short-desc> # 纯文档修改 +``` + +**规则：** + +- `<ticket-id>` 为任务跟踪系统的编号（如 JIRA-123） +- `<short-desc>` 使用 kebab-case，不超过 5 个单词 +- 分支生命周期不超过 [团队填写] 个工作日，超期需拆分 + +--- + +## Commit 规范 + +### 格式 + +采用 [Conventional Commits](https://www.conventionalcommits.org/) 格式： + +``` +<type>(<scope>): <subject> + +<body> + +<footer> +``` + +### Type 类型 + +| Type | 含义 | 示例 | +| --- | --- | --- | +| `feat` | 新功能 | `feat(user): add email verification` | +| `fix` | Bug 修复 | `fix(order): correct price calculation` | +| `refactor` | 重构（不改变行为） | `refactor(auth): extract token service` | +| `docs` | 文档修改 | `docs: update API guide` | +| `test` | 测试相关 | `test(user): add registration edge cases` | +| `chore` | 构建、CI、依赖 | `chore: upgrade Go to 1.22` | +| `perf` | 性能优化 | `perf(query): add index for user lookup` | +| `ci` | CI/CD 变更 | `ci: add lint step to pipeline` | + +### 规则 + +- Subject 使用英文，小写开头，不加句号，不超过 72 字符 +- Body 说明 **为什么**改，而非**改了什么** +- 涉及 Breaking Change 时，在 footer 添加 `BREAKING CHANGE: <说明>` +- 每个 commit 应是一个独立的、可编译通过的变更 +- 不允许出现 `fix typo`、`update`、`wip` 等无意义 commit message + +--- + +## Pull Request 流程 + +### PR 创建要求 + +1. PR 标题遵循 Commit 规范格式（合并时作为 squash commit message） +2. PR 描述必须包含： + - **变更内容**：1-3 句话说明做了什么 + - **关联任务**：链接到任务跟踪系统 + - **测试方式**：如何验证本次变更 + - **影响范围**：是否涉及数据库变更、配置变更、API 变更 +3. 单个 PR 不超过 [团队填写] 行变更（建议 400 行），超过需拆分 + +### Review 要求 + +| 条件 | 要求 | +| --- | --- | +| 最少 Reviewer 数 | [团队填写]（建议 1-2 人） | +| CI 检查 | 必须全部通过（lint + test + build） | +| 代码覆盖率 | 新代码覆盖率不低于 [团队填写]% | +| Review 响应 SLA | 提交后 [团队填写] 小时内完成首次 Review | + +### 合并策略 + +> [团队填写] 选择合并方式： +> +> - **Squash and Merge**（推荐）：PR 的所有 commit 合并为一个，保持主线整洁 +> - **Merge Commit**：保留完整 commit 历史 +> - **Rebase and Merge**：线性历史，无 merge commit + +### 合并后操作 + +- 合并后自动删除 feature 分支 +- 如需 cherry-pick 到其他分支，在 PR 中说明 + +--- + +## Hotfix 流程 + +紧急生产修复的特殊流程： + +``` +1. 从 main 创建 hotfix/<ticket-id>-<desc> 分支 +2. 修复 + 测试（可缩减为最小必要测试） +3. 提 PR 到 main，标记为 urgent +4. 至少 1 人 Review 后合并 +5. 立即部署 +6. 如有 develop 分支，同步 cherry-pick 到 develop +7. 事后补充完整测试 +``` + +--- + +## Tag 与版本号 + +采用 [Semantic Versioning](https://semver.org/)： + +``` +v<MAJOR>.<MINOR>.<PATCH> + +MAJOR：不兼容的 API 变更 +MINOR：向下兼容的新功能 +PATCH：向下兼容的 Bug 修复 +``` + +**规则：** + +- 发布 Tag 格式：`v1.2.3` +- Pre-release 格式：`v1.2.3-rc.1` +- Tag 必须在 main 分支上打 +- 每个 Tag 必须有对应的 CHANGELOG 条目 + +--- + +## Claude Code 行为约束 + +Claude 在执行 Git 操作时必须遵守： + +1. **不直接 push 到 main/develop**（Hook 已阻止） +2. **不使用 `--force` push**，除非用户明确要求且确认影响 +3. **不使用 `git add .`**，应逐个选择要暂存的文件 +4. **不跳过 pre-commit hook**（不使用 `--no-verify`） +5. **Commit message 必须符合 Conventional Commits 格式** +6. **创建分支前**，先确认当前分支状态（是否有未提交改动） diff --git a/specification-example/team/docs/standards/observability.md b/specification-example/team/docs/standards/observability.md new file mode 100644 index 0000000..5710fee --- /dev/null +++ b/specification-example/team/docs/standards/observability.md @@ -0,0 +1,219 @@ +# 日志与可观测性规范 + +> 本文件定义团队在日志、指标（Metrics）、链路追踪（Tracing）方面的统一约定。 +> Claude 在编写涉及日志输出、错误处理、监控集成的代码时应遵循本规范。 + +--- + +## 可观测性三支柱 + +| 支柱 | 用途 | 工具 | +| --- | --- | --- | +| 日志（Logging） | 记录离散事件，排查问题细节 | [团队填写] | +| 指标（Metrics） | 量化系统行为，触发告警 | [团队填写] | +| 链路追踪（Tracing） | 跟踪请求在服务间的流转 | [团队填写] | + +--- + +## 日志规范 + +### 日志级别 + +| 级别 | 使用场景 | 示例 | +| --- | --- | --- | +| ERROR | 需要人工介入的错误，影响业务功能 | 数据库连接失败、支付回调处理失败 | +| WARN | 异常但可自动恢复，需关注趋势 | 重试成功、缓存击穿降级到 DB | +| INFO | 关键业务动作，正常运行轨迹 | 用户登录、订单创建、服务启动 | +| DEBUG | 开发调试信息，生产环境默认关闭 | 请求参数详情、SQL 查询、缓存命中 | + +**规则：** + +- 生产环境默认日志级别：`INFO` +- ERROR 不能用于预期内的业务异常（如"用户不存在"应为 WARN 或 INFO） +- 每条 ERROR 日志必须有对应的告警或处理方式 +- 不在循环中打 INFO 日志（避免日志洪水） + +### 结构化日志格式 + +所有日志必须使用 **JSON 结构化格式**输出： + +```json +{ + "timestamp": "2024-03-15T10:30:00.123Z", + "level": "INFO", + "service": "user-service", + "trace_id": "abc123def456", + "span_id": "span789", + "caller": "handler/user.go:42", + "message": "user login success", + "user_id": "u-123", + "latency_ms": 45, + "http_method": "POST", + "http_path": "/v1/auth/login", + "http_status": 200 +} +``` + +### 必备字段 + +| 字段 | 说明 | 必须 | +| --- | --- | --- | +| `timestamp` | ISO 8601 格式，UTC 时区 | 是 | +| `level` | 日志级别 | 是 | +| `service` | 服务名称 | 是 | +| `trace_id` | 链路追踪 ID | 是 | +| `message` | 日志消息（人类可读） | 是 | +| `caller` | 代码位置（文件:行号） | 是 | +| `error` | 错误详情（仅 ERROR/WARN 级别） | 条件 | + +### 上下文字段 + +根据场景附加业务上下文字段： + +``` +# HTTP 请求 +http_method, http_path, http_status, latency_ms, client_ip + +# 数据库操作 +db_operation, db_table, db_latency_ms, rows_affected + +# 消息队列 +mq_topic, mq_partition, mq_offset, mq_consumer_group + +# 用户上下文 +user_id, tenant_id, request_id +``` + +### 日志禁忌 + +1. **禁止记录敏感信息**：密码、Token、信用卡号、身份证号 +2. **禁止使用 fmt.Println / console.log 输出日志**——必须用日志框架 +3. **禁止日志消息中拼接变量**——使用结构化字段 + +``` +❌ log.Info("user " + userId + " login from " + ip) +✅ log.Info("user login", "user_id", userId, "client_ip", ip) +``` + +--- + +## 指标（Metrics）规范 + +### 命名规范 + +``` +<service>_<domain>_<metric>_<unit> + +示例： +user_service_http_request_duration_seconds +order_service_payment_total_count +user_service_db_connection_pool_size +``` + +**规则：** + +- 使用 snake_case +- 单位后缀：`_seconds`、`_bytes`、`_count`、`_total`、`_ratio` +- 不使用缩写（`req` → `request`） + +### 必备指标（RED 方法） + +每个服务必须暴露以下指标： + +| 指标 | 类型 | 说明 | +| --- | --- | --- | +| `<service>_http_request_total` | Counter | 请求总数（按 method、path、status 分组） | +| `<service>_http_request_duration_seconds` | Histogram | 请求延迟分布 | +| `<service>_http_request_errors_total` | Counter | 错误请求数（HTTP 5xx） | + +### 业务指标 + +> [团队填写] 各服务需暴露的核心业务指标，例如： +> +> - 订单创建数、支付成功率、用户注册数 +> - 缓存命中率、消息队列积压量 + +--- + +## 链路追踪规范 + +### 集成要求 + +- 使用 [团队填写] （推荐 OpenTelemetry）作为 Tracing SDK +- 所有 HTTP/gRPC 入口自动创建 Span +- 跨服务调用自动传播 Trace Context（W3C TraceContext 标准） + +### Span 命名 + +``` +# HTTP +HTTP <method> <path> +示例：HTTP GET /v1/users + +# gRPC +<package>.<Service>/<Method> +示例：user.v1.UserService/GetUser + +# 数据库 +DB <operation> <table> +示例：DB SELECT users + +# 消息队列 +MQ <operation> <topic> +示例：MQ PUBLISH order.created +``` + +### Span 属性 + +每个 Span 应携带必要属性： + +``` +# HTTP Span +http.method, http.url, http.status_code, http.request_content_length + +# DB Span +db.system, db.statement (脱敏), db.operation, db.name + +# 用户上下文 +user.id, tenant.id +``` + +### 采样策略 + +> [团队填写] 链路追踪采样率： +> +> - 开发/测试环境：100% +> - 生产环境：[填写]%（建议 1%-10%，根据流量调整） +> - ERROR 请求：100%（错误请求始终采集） + +--- + +## 告警规范 + +### 告警分级 + +| 级别 | 定义 | 响应要求 | +| --- | --- | --- | +| P0 | 核心业务完全不可用 | [团队填写] 分钟内响应 | +| P1 | 核心业务部分受损或严重降级 | [团队填写] 分钟内响应 | +| P2 | 非核心功能异常 | 工作时间内处理 | +| P3 | 预警，趋势异常 | 下个迭代处理 | + +### 告警规则设计原则 + +1. **有告警必须有 Runbook**——告警触发后怎么排查、怎么处理 +2. **避免告警疲劳**——不产生大量无法 actionable 的告警 +3. **使用错误率而非错误数**——避免流量波动导致误告警 +4. **设置合理阈值**——基于历史数据 P99 值，而非拍脑袋 + +--- + +## Claude 行为约束 + +Claude 在编写日志和监控相关代码时必须遵守： + +1. **使用结构化日志**——不使用字符串拼接 +2. **正确选择日志级别**——不滥用 ERROR +3. **不记录敏感信息**——密码、Token 等必须脱敏 +4. **添加 trace_id 传播**——跨函数调用保持 context 传递 +5. **新增 API 时提醒添加指标**——至少包含 RED 三项基础指标 diff --git a/specification-example/team/docs/standards/release.md b/specification-example/team/docs/standards/release.md new file mode 100644 index 0000000..f36ab56 --- /dev/null +++ b/specification-example/team/docs/standards/release.md @@ -0,0 +1,236 @@ +# 发布流程规范 + +> 本文件定义团队从代码合并到生产上线的完整发布流程。 +> Claude 在协助发布相关操作时（生成 CHANGELOG、打 Tag、创建 Release）应遵循本规范。 + +--- + +## 发布策略 + +> [团队填写] 选择发布策略： +> +> - **滚动发布（Rolling Update）**：逐批替换实例，无停机 +> - **蓝绿部署（Blue-Green）**：两套环境切换，快速回滚 +> - **金丝雀发布（Canary）**：先小比例放量验证，逐步全量 +> - **灰度发布**：按用户/地域/比例逐步放量 + +--- + +## 发布前检查清单 + +每次发布前必须确认以下条件全部满足： + +### 代码就绪 + +- [ ] PR 已合并到 main 分支 +- [ ] 所有 CI 检查通过（lint + test + build） +- [ ] Code Review 已获得所需数量的 Approve +- [ ] 无未解决的 Review Comment + +### 数据库就绪 + +- [ ] Migration 文件已合并 +- [ ] Migration 已在 staging 环境验证通过 +- [ ] 涉及大表变更已通知 DBA 并获得确认 +- [ ] 回滚 Migration（DOWN）已验证可用 + +### 配置就绪 + +- [ ] 新增环境变量已在目标环境配置 +- [ ] Feature Flag 已设置为正确状态 +- [ ] 第三方服务的 API Key / 密钥已配置 + +### 文档就绪 + +- [ ] CHANGELOG 已更新 +- [ ] API 文档已同步（如有接口变更） +- [ ] Runbook 已更新（如有运维变更） + +### 回滚方案 + +- [ ] 回滚步骤已明确记录 +- [ ] 回滚触发条件已定义 +- [ ] 数据库回滚方案已准备（如有 Migration） + +--- + +## 版本号与 Tag + +### 版本号规范 + +采用 [Semantic Versioning](https://semver.org/)： + +``` +v<MAJOR>.<MINOR>.<PATCH> + +v1.0.0 → 首个正式版本 +v1.1.0 → 新增向下兼容的功能 +v1.1.1 → Bug 修复 +v2.0.0 → 不兼容的 API 变更 +``` + +### 预发布版本 + +``` +v1.2.0-rc.1 # Release Candidate +v1.2.0-beta.1 # Beta 版本 +``` + +### Tag 操作 + +```bash +# 在 main 分支上打 Tag +git tag -a v1.2.0 -m "Release v1.2.0: <简要说明>" +git push origin v1.2.0 +``` + +**规则：** + +- Tag 只在 main 分支上打 +- Tag 名称必须以 `v` 开头 +- 每个 Tag 必须有对应的 CHANGELOG 条目 +- 不删除已发布的 Tag（特殊情况除外） + +--- + +## CHANGELOG 管理 + +### 格式 + +遵循 [Keep a Changelog](https://keepachangelog.com/) 格式： + +```markdown +# Changelog + +## [Unreleased] + +### Added +- 新增用户邮箱验证功能 (#123) + +### Changed +- 优化订单查询接口响应速度 (#456) + +### Fixed +- 修复用户注册时邮箱大小写不一致的问题 (#789) + +## [1.2.0] - 2024-03-15 + +### Added +- ... + +### Breaking Changes +- 移除 /v1/users/search 接口，请使用 /v1/users?q= 代替 +``` + +### 分类标签 + +| 标签 | 含义 | +| --- | --- | +| Added | 新增功能 | +| Changed | 现有功能的变更 | +| Deprecated | 即将移除的功能 | +| Removed | 已移除的功能 | +| Fixed | Bug 修复 | +| Security | 安全漏洞修复 | +| Breaking Changes | 不兼容变更（必须醒目标注） | + +### 编写规则 + +- 每条记录关联 PR 或 Issue 编号 +- 面向**使用者**写（描述影响，而非实现细节） +- Breaking Changes 必须单独标注并说明迁移方式 +- `[Unreleased]` 部分在开发过程中持续维护，发布时移入对应版本 + +--- + +## 发布流程 + +### 标准发布流程 + +``` +1. 确认 main 分支上的代码即待发布内容 +2. 执行发布前检查清单（全部勾选） +3. 将 CHANGELOG 中 [Unreleased] 内容移入新版本号 +4. 提交 CHANGELOG 变更 +5. 打 Tag（git tag -a vX.Y.Z） +6. Push Tag 触发 CI/CD 发布流水线 +7. 验证 staging 环境部署结果 +8. 执行生产部署 +9. 验证生产环境（Smoke Test） +10. 通知相关方发布完成 +``` + +### 发布窗口 + +> [团队填写] 发布时间约定： +> +> - 允许发布时间段：[填写]（如工作日 10:00-16:00） +> - 禁止发布时间段：[填写]（如周五下午、节假日前一天） +> - 紧急发布（Hotfix）不受窗口限制，但需要审批 + +### 发布通知 + +发布完成后通知以下渠道： + +> [团队填写] 通知渠道和模板： +> +> - Slack/飞书频道：[填写] +> - 通知内容：版本号 + 主要变更 + CHANGELOG 链接 + +--- + +## 回滚方案 + +### 回滚触发条件 + +- 核心业务错误率超过 [团队填写]% +- P99 延迟超过基线 [团队填写] 倍 +- 出现数据不一致 +- 用户大量反馈异常 + +### 回滚步骤 + +``` +1. 确认需要回滚（参照触发条件） +2. 通知团队正在执行回滚 +3. 回滚应用到上一个稳定版本 +4. 如有 Migration，执行 DOWN 回滚 +5. 验证回滚后服务恢复正常 +6. 发送回滚通知 +7. 事后分析根因，修复后重新发布 +``` + +### 回滚的数据库考虑 + +- 如果新 Migration 已执行且有数据写入：需评估 DOWN Migration 对数据的影响 +- 涉及不可逆数据变更的 Migration：必须在发布前准备独立的数据恢复脚本 +- **原则：先回滚应用，再评估是否回滚数据库** + +--- + +## Feature Flag + +### 何时使用 Feature Flag + +- 大功能需要多次 PR 合入但未完成 +- 需要按比例灰度的功能 +- 需要快速关闭的风险功能 + +### Feature Flag 规范 + +- 命名：`FF_<DOMAIN>_<FEATURE>`（如 `FF_ORDER_NEW_PAYMENT`） +- 每个 Feature Flag 必须有**过期日期** +- 功能全量上线稳定后，必须在 [团队填写] 个迭代内清理 Flag 代码 +- 不允许 Feature Flag 嵌套超过 2 层 + +--- + +## Claude 行为约束 + +Claude 在协助发布相关工作时必须遵守： + +1. **生成 CHANGELOG 时**遵循 Keep a Changelog 格式，关联 PR 编号 +2. **打 Tag 前**提醒用户确认已完成发布检查清单 +3. **不直接执行生产部署命令**——展示命令并等待用户确认 +4. **生成回滚方案**时必须考虑数据库变更的回滚 +5. **提醒清理过期 Feature Flag**