Menu
结构化 Git 工作流实践。在进行任何代码变更时使用。在提交、创建分支、解决冲突，或需要跨多个并行流组织工作时使用。在进行版本发布、选择语义化版本号升级、打 Tag 或编写 Changelog 时使用。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
指导稳定的 RPC、存储协议和接口设计。在设计节点间 RPC、存储协议语义、模块边界或任何公共接口时使用。在定义 gRPC service、对象存储或文件系统语义、节点间的类型契约，或确立组件边界时使用。
自动化 CI/CD 流水线设置。在设置或修改构建和部署流水线时使用。当需要自动化质量门禁、在 CI 中配置测试运行器，或建立部署策略时使用。当需要处理 CI 上不稳定（flaky）的测试时使用。
进行多维度代码审查。在合并任何变更之前使用。在审查由你自己、另一个智能体或人类编写的代码时使用。当需要在代码进入主分支之前评估其跨多个维度的质量时使用。当需要评估变更的正确性、可读性、架构与性能，或审查 PR/diff 时使用。
为清晰性而简化代码。在重构代码以提高可读性而不改变行为时使用。当代码可以正常工作但比应有的更难阅读、维护或扩展时使用。在审查已积累不必要复杂性的代码时使用。当组件过度设计、过于炫技而难以维护时使用。当需要清理越来越难读懂的代码时使用。
验证系统的一致性与持久性承诺。在设计或修改复制协议、写路径、崩溃恢复逻辑时使用。当需要证明已确认的写入不丢失、副本间不发散、崩溃后能恢复到一致状态，或评审 fsync/校验和/事务语义时使用。
优化智能体上下文设置。在开始新会话、智能体输出质量下降、在不同任务之间切换，或需要为项目配置规则文件和上下文时使用。
| name | git-workflow-and-versioning |
| description | 结构化 Git 工作流实践。在进行任何代码变更时使用。在提交、创建分支、解决冲突，或需要跨多个并行流组织工作时使用。在进行版本发布、选择语义化版本号升级、打 Tag 或编写 Changelog 时使用。 |
Git 是你的安全网。将提交视为保存点，将分支视为沙箱，将历史记录视为文档。随着 AI 智能体以高速生成代码，纪律严明的版本控制是保持变更可管理、可审查和可逆的机制。
始终使用。每个代码变更都流经 Git。
保持 main 始终可部署。在 1-3 天内合并回主干的短期功能分支中工作。长期开发分支是隐性成本——它们会分叉、产生合并冲突并延迟集成。DORA 研究一致表明，基于主干的开发与高绩效工程团队相关。
main ──●──●──●──●──●──●──●──●──●── （始终可部署）
╲ ╱ ╲ ╱
●──●─╱ ●──╱ ← 短期功能分支（1-3 天）
这是推荐的默认策略。使用 gitflow 或长期分支的团队可以将这些原则（原子提交、小变更、描述性消息）适应到他们的分支模型中——提交纪律比具体的分支策略更重要。
每个成功的增量都应得到自己的提交。不要累积大量未提交的变更。
工作模式：
实现切片 → 测试 → 验证 → 提交 → 下一个切片
不要这样：
全部实现 → 希望它能工作 → 巨型提交
提交就是保存点。如果下一个变更破坏了什么，你可以立即恢复到上一个已知良好的状态。
每个提交做一件逻辑上自包含的事情：
# 好：每个提交是自包含的
git log --oneline
a1b2c3d 添加带验证的 RPC 创建端点
d4e5f6g 添加副本追赶调度器
h7i8j9k 为副本同步添加集成测试
m1n2o3p 添加请求校验（单元 + 集成）
# 坏：所有内容混在一起
git log --oneline
x1y2z3a 添加任务功能，修复侧边栏，更新依赖，重构工具函数
提交消息解释为什么，而不仅仅是是什么：
# 好：解释意图
feat: 为注册端点添加邮箱验证
防止无效的邮箱格式进入数据库。
在协议处理层使用 protobuf 校验逻辑，
与 auth/handler.go 中现有的验证模式保持一致。
# 坏：描述从 diff 中显而易见的内容
更新 auth/handler.go
格式：
<类型>: <简短描述>
<可选正文，解释为什么，而非是什么>
类型：
feat — 新功能fix — 缺陷修复refactor — 既不修复缺陷也不添加功能的代码变更test — 添加或更新测试docs — 仅文档chore — 工具、依赖项、配置不要将格式变更与行为变更混合。不要将重构与功能混合。每种类型的变更应该是单独的提交——理想情况下是单独的 PR：
# 好：分离关注点
git commit -m "refactor: 将验证逻辑提取为共享工具"
git commit -m "feat: 为注册添加手机号验证"
# 坏：混合关注点
git commit -m "重构验证并添加手机号字段"
将重构与功能工作分开。 重构变更和功能变更是两个不同的变更——分开提交。这使得每个变更更容易审查、回滚和在历史记录中理解。小型清理（重命名一个变量）可以根据审查者的判断包含在功能提交中。
目标每个提交/PR 约 100 行。超过约 1000 行的变更应该拆分。参见 code-review-and-quality 中的拆分策略，了解如何分解大变更。
~100 行 → 易于审查，易于回滚
~300 行 → 单个逻辑变更可接受
~1000 行 → 拆分为更小的变更
main（始终可部署）
│
├── feature/task-creation ← 每个功能一个分支
├── feature/user-settings ← 并行工作
└── fix/duplicate-tasks ← 缺陷修复
main（或团队的默认分支）创建分支feature/<简短描述> → feature/task-creation
fix/<简短描述> → fix/duplicate-tasks
chore/<简短描述> → chore/update-deps
refactor/<简短描述> → refactor/auth-module
对于并行的 AI 智能体工作，使用 git worktree 同时运行多个分支：
# 为功能分支创建工作树
git worktree add ../project-feature-a feature/task-creation
git worktree add ../project-feature-b feature/user-settings
# 每个工作树是具有各自分支的独立目录
# 智能体可以并行工作且互不干扰
ls ../
project/ ← main 分支
project-feature-a/ ← task-creation 分支
project-feature-b/ ← user-settings 分支
# 完成后，合并并清理
git worktree remove ../project-feature-a
优势：
智能体开始工作
│
├── 进行一个变更
│ ├── 测试通过？→ 提交 → 继续
│ └── 测试失败？→ 回滚到上一个提交 → 调查
│
├── 进行另一个变更
│ ├── 测试通过？→ 提交 → 继续
│ └── 测试失败？→ 回滚到上一个提交 → 调查
│
└── 功能完成 → 所有提交形成一个干净的历史记录
这种模式意味着你永远不会丢失超过一个增量的工作。如果智能体偏离了轨道，git reset --hard HEAD 将你带回上一个成功的状态。
在任何修改之后，提供一个结构化的摘要。这使审查更容易，记录范围纪律，并暴露意外的变更：
已进行的变更：
- internal/handler/task.go：为 Create RPC 添加了请求校验
- internal/validation/task.go：使用 protobuf 定义添加了 TaskCreateValidator
我有意不触碰的内容：
- internal/handler/auth.go：有类似的验证缺口，但在范围之外
- internal/middleware/error.go：错误格式可以改进（单独的任务）
潜在担忧：
- 校验逻辑是严格的——拒绝额外字段。确认这是预期的。
- 添加了 validator 作为依赖项——已存在于 go.mod 中
此模式能早期捕获错误假设，并为审查者提供变更的清晰地图。"不触碰的内容"部分特别重要——它表明你遵守了范围纪律，没有进行未经请求的翻新。
每次提交之前：
# 1. 检查你即将提交的内容
git diff --staged
# 2. 确保没有机密
git diff --staged | grep -i "password\|secret\|api_key\|token"
# 3. 运行测试
go test ./... -race
# 或对于 Rust: cargo test
# 4. 运行 Linting
golangci-lint run
# 或对于 Rust: cargo clippy -- -D warnings
# 5. 运行静态分析
go vet ./...
# 或对于 Rust: cargo check
使用 Git Hook 自动化此流程：
# Makefile 目标（或 .githooks/pre-commit）
.PHONY: pre-commit
pre-commit: test lint vet
test:
go test ./... -race
lint:
golangci-lint run
vet:
go vet ./...
go.sum、protobuf 生成的桩代码）target/、dist/）、环境文件（.env）或 IDE 配置（.vscode/settings.json 除非共享）.gitignore，涵盖：target/、build/、.env、*.pem、*.o、*.so# 找到引入缺陷的提交
git bisect start
git bisect bad HEAD
git bisect good <已知良好的提交>
# Git 检出中点；在每个提交运行你的测试来缩小范围
# 查看最近的变化
git log --oneline -20
git diff HEAD~5..HEAD -- src/
# 找到最后修改特定行的人
git blame internal/service/task.go
# 搜索提交消息中的关键词
git log --grep="validation" --oneline
提交是你追踪变更的方式；版本是消费者追踪变更的方式。一旦有任何东西依赖你的代码——另一个团队、一个发布的包、一个部署的客户端——"main 上的最新版"就不再是"我在运行什么，升级安全吗？"的充分回答。版本号和 Changelog 是回答这个问题的契约。
对于任何有消费者的东西，版本 MAJOR.MINOR.PATCH 并让数字传达意义：
MAJOR 破坏性变更——消费者必须修改其代码才能升级
MINOR 新功能，向后兼容——升级安全
PATCH 缺陷修复，向后兼容——升级安全
数字是一份承诺，所以让代码与之匹配。一个改变消费者依赖行为的"补丁"版本是伪装的主版本（Hyrum 定律——参见 api-and-interface-design 技能）。当不确定一个变更是否是破坏性的时，假设它是；一个意外的主版本远比一个损坏的消费者便宜。
发布是历史中不可变的点，而非移动的分支。打 Tag 以便它始终可以被复现：
git tag -a v1.4.0 -m "Release 1.4.0"
git push origin v1.4.0
从 Tag 派生版本号，而非在分散的文件中手动编辑它，这样构建产物、Tag 和 Changelog 永远不会不一致。
Changelog 不是 git log。它是经过策划的、面向消费者的对"什么变了以及我在乎吗？"的回答——按 新增 / 变更 / 修复 / 弃用 / 移除 / 安全 分组，最新的在最上面，每个条目围绕用户影响来表述，而非内部机制。
## [1.4.0] - 2025-06-12
### 新增
- 通过 CSV 批量导入任务
### 修复
- 周期性任务截止日期的时区偏移
### 弃用
- `GET /v1/tasks/all` ——使用分页的 `GET /v1/tasks`（2.0 中移除）
在产生变更的同一个变更中编写条目，趁影响还很新鲜时——而非在发布时从提交考古学中重建。破坏性变更需要迁移说明和弃用窗口期（遵循 deprecation-and-migration 技能）；实际发布是 shipping-and-launch 技能的工作——本节是输入该技能的版本化契约。
| 合理化借口 | 现实 |
|---|---|
| "功能完成时我再提交" | 一个巨型提交无法审查、调试或回滚。每个切片都提交。 |
| "消息不重要" | 消息就是文档。未来的你（和未来的智能体）需要理解什么变了以及为什么。 |
| "我以后压缩一下就行" | 压缩破坏了开发叙事。从一开始就优先使用干净的增量提交。 |
| "分支增加了开销" | 短期分支是免费的，可以防止冲突的工作碰撞。长期分支才是问题——在 1-3 天内合并。 |
| "我稍后再拆分这个变更" | 大变更更难审查、部署风险更高、更难回滚。在提交前拆分，而非之后。 |
| "我不需要 .gitignore" | 直到带有生产机密的 .env 被提交了。立即设置它。 |
| "这只是个小修复，升级补丁版本就行" | 检查消费者能观察到什么。他们依赖的行为变化是主版本，无论 diff 大小如何。 |
| "Changelog 就是提交日志" | 提交是给你的；Changelog 是给消费者的，按影响策划。从原始提交生成会掩盖重要的东西。 |
| "我们在发布时再写 Changelog" | 到那时影响是从记忆中重建的，一半已经遗漏。在变更时编写条目。 |
.gitignoretarget/、vendor/、.env 或构建产物对于每个提交：
.gitignore 覆盖了标准排除项对于每个发布（任何有消费者的东西）：