git-commits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Commits

Git提交

This is a strict guideline. Follow these rules exactly.

How to format and create git commits, branches, and PRs when helping developers.

这是一项严格的指导规范，请严格遵守以下规则。

本规范说明了协助开发者时如何格式化、创建Git提交、分支以及PR。

🚨 CRITICAL: Security Check FIRST

🚨 重中之重：优先进行安全检查

Before analyzing ANY commits, check for sensitive files:

NEVER commit these files:

Environment & Configuration:

.env

(any variant:

.env

.env.local

.env.prod

.env.dev

.env.test

.env.*

)

```
.envrc
```
,
```
.env.example
```
(if contains real values)
```
config.json
```
,
```
secrets.json
```
,
```
credentials.json
```
```
.npmrc
```
,
```
.pypirc
```
(if contains auth tokens)

AWS & Cloud Credentials:

```
credentials
```
,
```
config
```
(in
```
.aws/
```
directory)

serviceAccount.json

gcloud-credentials.json

```
terraform.tfvars
```
(if contains secrets)
```
pulumi.*.yaml
```
(if contains secrets)

Private Keys & Certificates:

```
*.pem
```
,
```
*.key
```
,
```
*.p12
```
,
```
*.pfx
```
```
id_rsa
```
,
```
id_ed25519
```
,
```
*.pub
```
(private keys only)
```
*.crt
```
(if paired with private key)
```
keystore.jks
```
,
```
truststore.jks
```

Database & API:

Files with connection strings containing passwords
API keys, access tokens, OAuth secrets
Database dumps with real data
```
*.sql
```
files with production data

Other Sensitive:

```
.git-credentials
```
```
.netrc
```
```
*.log
```
files with sensitive data
Backup files with credentials (
```
*.bak
```
,
```
*.backup
```
)

If detected:

STOP immediately
Alert developer with 🚨 WARNING
List the sensitive files found
Refuse to proceed until removed from staging
Remind developer to add to
.gitignore

Example alert:

🚨 SECURITY WARNING: Sensitive files detected!

The following files should NEVER be committed:
- infrastructure/.env.prod (environment file with credentials)
- .aws/credentials (AWS access keys)
- config/database.json (database password)

ACTION REQUIRED:
1. Remove from staging: git reset HEAD <file>
2. Add to .gitignore if not already present
3. Verify no secrets were previously committed
4. Consider rotating any exposed credentials

I cannot proceed with commit suggestions until these are resolved.

分析任何提交前，请先检查是否存在敏感文件：

绝对不要提交以下文件：

环境与配置类：

.env

（所有变体：

.env

、

.env.local

、

.env.prod

、

.env.dev

、

.env.test

、

.env.*

）

```
.envrc
```
、
```
.env.example
```
（如果包含真实值）
```
config.json
```
、
```
secrets.json
```
、
```
credentials.json
```
```
.npmrc
```
、
```
.pypirc
```
（如果包含认证令牌）

AWS与云凭证类：

```
credentials
```
、
```
config
```
（在
```
.aws/
```
目录下）

serviceAccount.json

、

gcloud-credentials.json

```
terraform.tfvars
```
（如果包含密钥）
```
pulumi.*.yaml
```
（如果包含密钥）

私钥与证书类：

```
*.pem
```
、
```
*.key
```
、
```
*.p12
```
、
```
*.pfx
```
```
id_rsa
```
、
```
id_ed25519
```
、
```
*.pub
```
（仅私钥）
```
*.crt
```
（如果和私钥配对）
```
keystore.jks
```
、
```
truststore.jks
```

数据库与API类：

包含密码的连接字符串相关文件
API密钥、访问令牌、OAuth密钥
包含真实数据的数据库转储文件
包含生产数据的
```
*.sql
```
文件

其他敏感类：

```
.git-credentials
```
```
.netrc
```
包含敏感数据的
```
*.log
```
文件
带有凭证的备份文件（
```
*.bak
```
、
```
*.backup
```
）

如果检测到上述文件：

立即停止操作
用🚨警告提醒开发者
列出所有检测到的敏感文件
在这些文件从暂存区移除前拒绝继续操作
提醒开发者将这些文件添加到
.gitignore
中

警告示例：

🚨 SECURITY WARNING: Sensitive files detected!

The following files should NEVER be committed:
- infrastructure/.env.prod (environment file with credentials)
- .aws/credentials (AWS access keys)
- config/database.json (database password)

ACTION REQUIRED:
1. Remove from staging: git reset HEAD <file>
2. Add to .gitignore if not already present
3. Verify no secrets were previously committed
4. Consider rotating any exposed credentials

I cannot proceed with commit suggestions until these are resolved.

Commit Message Format

提交信息格式

Structure:

<type>: <description>

Rules:

One logical change per commit
Single line only (no multi-line commits)
Imperative form: "Add", "Create", "Fix", "Update" (not "Added", "Adding")
Be specific but concise

Types:

```
feat
```
- New feature
```
fix
```
- Bug fix
```
refactor
```
- Code restructuring (no behavior change)
```
docs
```
- Documentation only
```
style
```
- Formatting, whitespace
```
test
```
- Adding/updating tests
```
chore
```
- Build, config, dependencies

Examples:

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

结构：

<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

Commit Grouping Strategy

提交分组策略

Analysis Criteria

分析标准

Group files together when they:

Implement the same feature
Fix the same bug
Are part of the same refactoring
Have strong dependencies (one requires the other)

Separate files when they:

Serve different purposes (feature vs refactor vs docs)
Touch different features/components
Can work independently
Represent different logical changes

符合以下条件的文件可以分到同一组：

实现同一个功能
修复同一个漏洞
属于同一次重构的一部分
存在强依赖关系（一个变更依赖另一个）

符合以下条件的文件需要拆分：

用途不同（功能 vs 重构 vs 文档）
修改的是不同的功能/组件
可以独立运行
代表不同的逻辑变更

Grouping by Purpose

按用途分组

Analyze changes by:

Purpose: What problem does this solve?
Scope: What area of the codebase?
Independence: Can this stand alone?
Dependencies: Does it depend on other changes?

Common patterns:

New feature = components + types + utilities + docs
Refactoring = code quality improvements separate from features
Bug fix = minimal files, specific to issue
Config = package.json, environment, build files

通过以下维度分析变更：

用途：解决什么问题？
范围：属于代码库的哪个模块？
独立性：是否可以独立存在？
依赖关系：是否依赖其他变更？

常见模式：

新功能 = 组件 + 类型定义 + 工具函数 + 文档
重构 = 与功能无关的代码质量优化
漏洞修复 = 最少的、仅和问题相关的文件
配置 = package.json、环境变量、构建文件

Process

处理流程

When developer asks for commit help:

🚨 Security Check - Verify no
```
.env
```
files or credentials in changes (STOP if found)
Analyze changes - Run git commands to see actual changes (don't guess)
Group logically - Organize by purpose, not file type
Generate messages - Follow chosen format (simple or conventional)
Present for approval - Show commit groups with affected files
Wait for approval - Developer stages and commits in their tool

当开发者寻求提交相关帮助时：

🚨 安全检查 - 确认变更中没有
```
.env
```
文件或凭证（如果发现立即停止）
分析变更 - 运行git命令查看实际变更（不要猜测）
逻辑分组 - 按用途分组，而非按文件类型
生成提交信息 - 遵循选定的格式（简易格式或约定式提交）
提交审核 - 展示提交分组以及对应影响的文件
等待确认 - 开发者在自己的工具中暂存并提交代码

Example Output

输出示例

Simple Format

简易格式

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: Add user authentication logic
Files:
- auth.ts (authentication functions)
- types.ts (auth types)

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

Conventional Commits

约定式提交

📦 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

📦 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

Branches and PRs

分支与PR

Branch naming:

Use descriptive, kebab-case names with type prefix:
```
feat/user-profile
```
,
```
fix/auth-timeout
```
NEVER reference planning phases: No
```
phase-1
```
,
```
step-2-3
```
, etc.
Planning docs are not tracked — references are meaningless in git history

PR titles — plain descriptive (NOT conventional commits):

Describe what the PR does in plain English
No
```
feat:
```
,
```
fix:
```
,
```
chore:
```
prefixes — the branch name and labels carry the type
Imperative form, capital letter

undefined

分支命名：

使用描述性的kebab-case名称，加上类型前缀：
```
feat/user-profile
```
、
```
fix/auth-timeout
```
绝对不要引用规划阶段：不要用
```
phase-1
```
、
```
step-2-3
```
等命名
规划文档不会被跟踪，这类引用在git历史中没有意义

PR标题 - 纯描述性（不要用约定式提交格式）：

用通俗的英文描述PR的作用
不要加
```
feat:
```
、
```
fix:
```
、
```
chore:
```
前缀，分支名和标签已经承载了类型信息
使用祈使语气，首字母大写

undefined

✅ Good PR titles

✅ 好的PR标题示例

Add scales browser UI Fix test runner in CI Migrate devcontainer to ai-standards

❌ Bad PR titles (don't use conventional commit format)

❌ 不好的PR标题（不要使用约定式提交格式）

feat: Add scales browser UI chore: Migrate devcontainer to ai-standards

❌ Bad PR titles (auto-generated GitHub defaults)

❌ 不好的PR标题（GitHub自动生成的默认标题）

Dev Fix/auth timeout on mobile


**Why no conventional commits on PRs?** Versioning is label-driven (major/minor/patch labels on PRs to main). The PR title is for humans — keep it clean.

**Examples:**
```bash

Dev Fix/auth timeout on mobile


**为什么PR不能用约定式提交格式？** 版本发布是标签驱动的（合并到主干的PR上的major/minor/patch标签决定版本号），PR标题是给人看的，保持简洁即可。

**示例：**
```bash

✅ 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


**Versioning:**
- Handled automatically by GitHub Action on merge to main
- PR labels (`major`, `minor`, `patch`) determine version bump
- Never manually write version numbers in commits or PR titles

---

git checkout -b phase-1-setup git checkout -b step-2-3-implement-auth git checkout -b task-1-2-database


**版本管理：**
- 合并到主干时由GitHub Action自动处理
- PR标签（`major`、`minor`、`patch`）决定版本号升级幅度
- 绝对不要在提交或PR标题中手动写版本号

---

Guidelines

指导原则

Security first: Always check for
```
.env
```
files and credentials before proceeding
Analyze first: Always run
```
git status
```
and
```
git diff
```
to see actual changes
Logical grouping: Group by feature/fix, not by file type
No line ranges: Just list files, not specific line numbers
Wait for approval: Don't execute commits without explicit approval
No planning references: Never mention "Step 1.2", "Phase 3", etc. in commits, branches, or PRs
Check for issues: Flag
```
.env
```
files,
```
console.log
```
in production, missing newlines

安全第一：操作前始终检查是否存在
```
.env
```
文件和凭证
先分析：始终运行
```
git status
```
和
```
git diff
```
查看实际变更
逻辑分组：按功能/修复分组，而非按文件类型
不要标注行范围：仅列出文件，不要标注具体行号
等待确认：没有明确批准的情况下不要执行提交
不要引用规划阶段：绝对不要在提交、分支或PR中提到"Step 1.2"、"Phase 3"等内容
检查问题：标记
```
.env
```
文件、生产环境的
```
console.log
```
、缺失的换行符等问题

What NOT to Do

禁止行为

❌ NEVER commit .env files or credentials - STOP and alert if detected ❌ Don't stage files (developer does this) ❌ Don't commit (developer does this) ❌ Don't push (developer controls when) ❌ Don't modify files unless asked ❌ Don't guess at changes - always analyze actual diffs

❌ 绝对不要提交.env文件或凭证 - 如果检测到立即停止并发出警告 ❌ 不要暂存文件（由开发者操作） ❌ 不要执行提交（由开发者操作） ❌ 不要推送代码（由开发者控制时机） ❌ 不要修改文件除非得到要求 ❌ 不要猜测变更内容 - 始终分析实际的diff

Progressive Improvement

持续优化

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.

如果开发者纠正了本技能本应避免的行为，请提出具体的修订建议，避免未来再次出现同类问题。