1155c7564e
- Add language switch link to root README - Translate README.md to docs/zh-CN/README.md - Translate USER-GUIDE.md to docs/zh-CN/USER-GUIDE.md - Translate all 13 reference documents to docs/zh-CN/references/ Key terminology mappings: - context engineering → 上下文工程 - spec-driven development → 规格驱动开发 - context rot → 上下文衰减 - phase → 阶段 - milestone → 里程碑 - roadmap → 路线图 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
248 lines
6.4 KiB
Markdown
248 lines
6.4 KiB
Markdown
<overview>
|
||
GSD 框架的 Git 集成。
|
||
</overview>
|
||
|
||
<core_principle>
|
||
|
||
**提交结果，而非过程。**
|
||
|
||
git 日志应该读起来像是发布内容的变更日志，而不是规划活动的日记。
|
||
</core_principle>
|
||
|
||
<commit_points>
|
||
|
||
| 事件 | 提交? | 原因 |
|
||
| ----------------------- | ------- | ------------------------------------------------ |
|
||
| BRIEF + ROADMAP 创建 | 是 | 项目初始化 |
|
||
| PLAN.md 创建 | 否 | 中间产物 - 与计划完成一起提交 |
|
||
| RESEARCH.md 创建 | 否 | 中间产物 |
|
||
| DISCOVERY.md 创建 | 否 | 中间产物 |
|
||
| **任务完成** | 是 | 原子工作单元（每个任务 1 个提交） |
|
||
| **计划完成** | 是 | 元数据提交（SUMMARY + STATE + ROADMAP） |
|
||
| 交接创建 | 是 | WIP 状态保留 |
|
||
|
||
</commit_points>
|
||
|
||
<git_check>
|
||
|
||
```bash
|
||
[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
|
||
```
|
||
|
||
如果 NO_GIT：静默运行 `git init`。GSD 项目总是有自己的仓库。
|
||
</git_check>
|
||
|
||
<commit_formats>
|
||
|
||
<format name="initialization">
|
||
## 项目初始化（brief + roadmap 一起）
|
||
|
||
```
|
||
docs: initialize [project-name] ([N] phases)
|
||
|
||
[PROJECT.md 中的一句话描述]
|
||
|
||
Phases:
|
||
1. [phase-name]: [goal]
|
||
2. [phase-name]: [goal]
|
||
3. [phase-name]: [goal]
|
||
```
|
||
|
||
提交内容：
|
||
|
||
```bash
|
||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/
|
||
```
|
||
|
||
</format>
|
||
|
||
<format name="task-completion">
|
||
## 任务完成（计划执行期间）
|
||
|
||
每个任务在完成后立即获得自己的提交。
|
||
|
||
```
|
||
{type}({phase}-{plan}): {task-name}
|
||
|
||
- [关键变更 1]
|
||
- [关键变更 2]
|
||
- [关键变更 3]
|
||
```
|
||
|
||
**提交类型：**
|
||
- `feat` - 新功能/功能
|
||
- `fix` - Bug 修复
|
||
- `test` - 仅测试（TDD RED 阶段）
|
||
- `refactor` - 代码清理（TDD REFACTOR 阶段）
|
||
- `perf` - 性能改进
|
||
- `chore` - 依赖、配置、工具
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 标准任务
|
||
git add src/api/auth.ts src/types/user.ts
|
||
git commit -m "feat(08-02): create user registration endpoint
|
||
|
||
- POST /auth/register validates email and password
|
||
- Checks for duplicate users
|
||
- Returns JWT token on success
|
||
"
|
||
|
||
# TDD 任务 - RED 阶段
|
||
git add src/__tests__/jwt.test.ts
|
||
git commit -m "test(07-02): add failing test for JWT generation
|
||
|
||
- Tests token contains user ID claim
|
||
- Tests token expires in 1 hour
|
||
- Tests signature verification
|
||
"
|
||
|
||
# TDD 任务 - GREEN 阶段
|
||
git add src/utils/jwt.ts
|
||
git commit -m "feat(07-02): implement JWT generation
|
||
|
||
- Uses jose library for signing
|
||
- Includes user ID and expiry claims
|
||
- Signs with HS256 algorithm
|
||
"
|
||
```
|
||
|
||
</format>
|
||
|
||
<format name="plan-completion">
|
||
## 计划完成（所有任务完成后）
|
||
|
||
所有任务提交后，最后一个元数据提交捕获计划完成。
|
||
|
||
```
|
||
docs({phase}-{plan}): complete [plan-name] plan
|
||
|
||
Tasks completed: [N]/[N]
|
||
- [Task 1 name]
|
||
- [Task 2 name]
|
||
- [Task 3 name]
|
||
|
||
SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
|
||
```
|
||
|
||
提交内容：
|
||
|
||
```bash
|
||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
|
||
```
|
||
|
||
**注意：** 代码文件不包含 - 已按任务提交。
|
||
|
||
</format>
|
||
|
||
<format name="handoff">
|
||
## 交接（WIP）
|
||
|
||
```
|
||
wip: [phase-name] paused at task [X]/[Y]
|
||
|
||
Current: [task name]
|
||
[如果阻塞:] Blocked: [reason]
|
||
```
|
||
|
||
提交内容：
|
||
|
||
```bash
|
||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
|
||
```
|
||
|
||
</format>
|
||
</commit_formats>
|
||
|
||
<example_log>
|
||
|
||
**旧方法（每个计划提交）：**
|
||
```
|
||
a7f2d1 feat(checkout): Stripe payments with webhook verification
|
||
3e9c4b feat(products): catalog with search, filters, and pagination
|
||
8a1b2c feat(auth): JWT with refresh rotation using jose
|
||
5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
|
||
2f4a8d docs: initialize ecommerce-app (5 phases)
|
||
```
|
||
|
||
**新方法（每个任务提交）：**
|
||
```
|
||
# Phase 04 - Checkout
|
||
1a2b3c docs(04-01): complete checkout flow plan
|
||
4d5e6f feat(04-01): add webhook signature verification
|
||
7g8h9i feat(04-01): implement payment session creation
|
||
0j1k2l feat(04-01): create checkout page component
|
||
|
||
# Phase 03 - Products
|
||
3m4n5o docs(03-02): complete product listing plan
|
||
6p7q8r feat(03-02): add pagination controls
|
||
9s0t1u feat(03-02): implement search and filters
|
||
2v3w4x feat(03-01): create product catalog schema
|
||
|
||
# Phase 02 - Auth
|
||
5y6z7a docs(02-02): complete token refresh plan
|
||
8b9c0d feat(02-02): implement refresh token rotation
|
||
1e2f3g test(02-02): add failing test for token refresh
|
||
4h5i6j docs(02-01): complete JWT setup plan
|
||
7k8l9m feat(02-01): add JWT generation and validation
|
||
0n1o2p chore(02-01): install jose library
|
||
|
||
# Phase 01 - Foundation
|
||
3q4r5s docs(01-01): complete scaffold plan
|
||
6t7u8v feat(01-01): configure Tailwind and globals
|
||
9w0x1y feat(01-01): set up Prisma with database
|
||
2z3a4b feat(01-01): create Next.js 15 project
|
||
|
||
# Initialization
|
||
5c6d7e docs: initialize ecommerce-app (5 phases)
|
||
```
|
||
|
||
每个计划产生 2-4 个提交（任务 + 元数据）。清晰、细粒度、可 bisect。
|
||
|
||
</example_log>
|
||
|
||
<anti_patterns>
|
||
|
||
**仍不要提交（中间产物）：**
|
||
- PLAN.md 创建（与计划完成一起提交）
|
||
- RESEARCH.md（中间产物）
|
||
- DISCOVERY.md（中间产物）
|
||
- 小的规划调整
|
||
- "Fixed typo in roadmap"
|
||
|
||
**要提交（结果）：**
|
||
- 每个任务完成（feat/fix/test/refactor）
|
||
- 计划完成元数据（docs）
|
||
- 项目初始化（docs）
|
||
|
||
**关键原则：** 提交可工作的代码和已发布的结果，而非规划过程。
|
||
|
||
</anti_patterns>
|
||
|
||
<commit_strategy_rationale>
|
||
|
||
## 为什么使用每任务提交？
|
||
|
||
**AI 上下文工程：**
|
||
- Git 历史成为未来 Claude 会话的主要上下文源
|
||
- `git log --grep="{phase}-{plan}"` 显示计划的所有工作
|
||
- `git diff <hash>^..<hash>` 显示每个任务的确切变更
|
||
- 减少对解析 SUMMARY.md 的依赖 = 更多上下文用于实际工作
|
||
|
||
**失败恢复：**
|
||
- 任务 1 已提交 ✅，任务 2 失败 ❌
|
||
- 下次会话中的 Claude：看到任务 1 完成，可以重试任务 2
|
||
- 可以 `git reset --hard` 到最后一个成功的任务
|
||
|
||
**调试：**
|
||
- `git bisect` 找到确切的失败任务，而不仅仅是失败计划
|
||
- `git blame` 将行追溯到特定任务上下文
|
||
- 每个提交独立可回滚
|
||
|
||
**可观察性：**
|
||
- 独立开发者 + Claude 工作流受益于细粒度归因
|
||
- 原子提交是 git 最佳实践
|
||
- 当消费者是 Claude 而非人类时，"提交噪音"无关紧要
|
||
|
||
</commit_strategy_rationale> |