git-commits

Git 提交

这是严格的指南。 请严格遵守这些规则。

在帮助开发者时，说明如何创建和格式化 git 提交、分支和 PR。

---

🚨 提交前检查

生成提交消息前，针对所有已暂存文件运行 pre-commit-check 技能。此技能涵盖：

1. 安全性 — 凭据、机密信息、.env 文件（委派给 security-checklist）
2. 代码质量 — DRY、命名、错误处理、死代码（参考 core-principles）
3. 破坏风险 — 构建、测试、Lambda 调用、缺失的环境变量

在三个检查项全部通过之前，不要继续进行提交分组。

运行检查后，简要确认结果以及使用的路径：

• “提交前检查已通过（通过 pre-commit-check 技能）——没有安全问题，代码质量良好，构建已验证。”
• “提交前检查已通过（内联回退方案——未找到 pre-commit-check 技能）——已暂存文件中没有机密信息。”

安全回退方案

如果无法使用 pre-commit-check 或 security-checklist，请直接应用这些规则。绝不要跳过安全检查。

扫描已暂存文件，检查是否包含：

• 含有真实值的 .env 文件（任何变体：.env、.env.local、.env.prod、.env.*）
• 代码中硬编码的机密信息、API 密钥、令牌、密码
• AWS 凭据、私钥（*.pem、*.key）、连接字符串
• .git-credentials、.netrc、凭据 JSON 文件

如果发现上述内容：立即停止，提醒开发者，在问题解决前拒绝继续。

---

提交消息格式

结构：

<type>: <description>

规则：

• 每次提交只包含一个逻辑变更
• 仅限单行（不要使用多行提交消息）
• 使用祈使语气：“Add”“Create”“Fix”“Update”（不要使用“Added”“Adding”）
• 具体但简洁

类型：

• feat - 新功能
• fix - 错误修复
• refactor - 代码重构（不改变行为）
• docs - 仅文档变更
• style - 格式、空白字符
• test - 添加或更新测试
• chore - 构建、配置、依赖项

示例：

feat: Add user authentication flow
fix: Resolve database connection timeout
docs: Update API endpoint documentation
refactor: Extract validation logic to separate function

---

提交分组策略

分析标准

在以下情况下将文件分组：

• 实现同一项功能
• 修复同一个错误
• 属于同一项重构
• 存在强依赖关系（其中一个需要另一个）

在以下情况下分开文件：

• 用途不同（功能 vs 重构 vs 文档）
• 涉及不同的功能或组件
• 可以独立运行
• 代表不同的逻辑变更

按用途分组

根据以下方面分析变更：

• 用途：解决什么问题？
• 范围：涉及代码库的哪个部分？
• 独立性：能否独立成立？
• 依赖关系：是否依赖其他变更？

常见模式：

• 新功能 = 组件 + 类型 + 工具 + 文档
• 重构 = 与功能分开的代码质量改进
• 错误修复 = 文件最少，并针对特定问题
• 配置 = package.json、环境、构建文件

---

流程

开发者请求提交帮助时：

1. 🚨 提交前检查 - 针对已暂存文件运行 pre-commit-check 技能（安全性、质量、破坏风险）
2. 分析变更 - 运行 git 命令查看实际变更（不要猜测）
3. 逻辑分组 - 按用途组织，而非按文件类型
4. 生成消息 - 遵循选定的格式（简单格式或约定式格式）
5. 提交审批 - 显示提交分组及受影响的文件
6. 等待审批 - 由开发者在其工具中暂存并提交

---

输出示例

简单格式

Commit 1: Add user authentication logic
Files:
- auth.ts (authentication functions)
- types.ts (auth types)

Commit 2: Update database schema
Files:
- schema.ts (user table changes)

约定式提交

📦 Commit 1: feat: Add user authentication flow
Files:
- frontend/contexts/auth-context.tsx (auth state management)
- frontend/hooks/use-auth.ts (auth hook)
- frontend/types/auth.ts (type definitions)
Group: Authentication feature - all related

📦 Commit 2: refactor: Extract API client utils
Files:
- frontend/lib/api-client.ts (extracted from inline code)
- frontend/utils/fetch-helper.ts (helper functions)
Group: Code quality - independent refactoring

📦 Commit 3: docs: Update authentication setup guide
Files:
- docs/guides/authentication.md (auth flow documentation)
Group: Documentation - separate from code

---

分支与 PR

何时创建分支：

直接在 dev 上提交：

• 项目设置、脚手架搭建
• Docker/devcontainer 配置
• Lint、格式化配置
• 小型 Bug 修复（几行代码）
• 依赖更新
• 轻微配置调整

从 dev 创建功能分支：

• 完整功能（新增功能）
• 大型 Bug 修复（涉及多个文件、逻辑复杂）
• 重大重构
• 涉及多个逻辑提交或多个会话的任何工作

经验法则：如果改动只有几行代码且内容独立，就提交到 dev。如果需要创建单独的 PR 并附上评审背景，就创建分支。如有疑问，请先询问。

分支命名：

• 使用描述性 kebab-case 名称，并添加类型前缀：feat/user-profile、fix/auth-timeout
• 绝不引用规划阶段：不要使用 phase-1、step-2-3 等名称。
• 规划文档不纳入跟踪；在 Git 历史中引用这些内容没有意义

PR 标题 — 简洁直白地描述（不要使用约定式提交格式）：

• 用通俗的英语描述 PR 的内容
• 不要使用 feat:、fix:、chore: 前缀 — 分支名称和标签已体现类型
• 使用祈使句，首字母大写

# ✅ Good PR titles
Add scales browser UI
Fix test runner in CI
Migrate devcontainer to ai-standards

# ❌ Bad PR titles (don't use conventional commit format)
feat: Add scales browser UI
chore: Migrate devcontainer to ai-standards

# ❌ Bad PR titles (auto-generated GitHub defaults)
Dev
Fix/auth timeout on mobile

为什么 PR 不使用约定式提交格式？ 版本号由标签驱动（合并到 main 的 PR 使用 major/minor/patch 标签）。PR 标题是给人看的 — 保持简洁明了。

示例：

# ✅ Good branch names
git checkout -b feat/user-profile
git checkout -b fix/auth-timeout
git checkout -b update-api-endpoints

# ❌ Bad branch names (no planning references)
git checkout -b phase-1-setup
git checkout -b step-2-3-implement-auth
git checkout -b task-1-2-database

版本管理：

• 合并到 main 时由 GitHub Action 自动处理
• PR 标签（major、minor、patch）决定版本号递增幅度
• 绝不要在提交或 PR 标题中手动填写版本号

---

指南

• 先通过提交前检查：继续操作前，始终运行 pre-commit-check
• 先分析：始终运行 git status 和 git diff，查看实际改动
• 按逻辑分组：按功能/修复分组，而非按文件类型
• 不要列出行号范围：只列出文件，不列出具体行号
• 等待批准：未经明确批准，不要执行提交
• 不要引用规划内容：提交、分支或 PR 中绝不要提及“Step 1.2”、“Phase 3”等内容
• 检查问题：标记 .env 文件、生产环境中的 console.log、缺少换行符等问题

---

不要做的事

❌ 绝不要在未运行提交前检查的情况下提交 — 停下来，先运行 pre-commit-check ❌ 除非开发者明确要求你执行，否则不要暂存、提交或推送 — 默认先提供计划并等待批准 ❌ 除非有人要求，否则不要修改文件 ❌ 不要臆测改动 — 始终分析实际差异

---

渐进式改进

如果开发者纠正了本技能本应避免的行为，请针对本技能提出具体的修订建议，以避免今后再次出现同样的问题。