golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: add Chinese (zh-CN) documentation

Browse Source 
- 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>
This commit is contained in:
lone
2026-03-16 10:13:55 +08:00
parent 0f38e3467e
commit 1155c7564e
16 changed files with 3814 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -6,6 +6,8 @@
**Solves context rot — the quality degradation that happens as Claude fills its context window.**
[**English**](README.md) | [**简体中文**](docs/zh-CN/README.md)
[![npm version](https://img.shields.io/npm/v/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
[![npm downloads](https://img.shields.io/npm/dm/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
[![Tests](https://img.shields.io/github/actions/workflow/status/glittercowboy/get-shit-done/test.yml?branch=main&style=for-the-badge&logo=github&label=Tests)](https://github.com/glittercowboy/get-shit-done/actions/workflows/test.yml)

707
docs/zh-CN/README.md Normal file
View File

@@ -0,0 +1,707 @@
<div align="center">
# GET SHIT DONE
**一个轻量级且强大的元提示、上下文工程和规格驱动开发系统，支持 Claude Code、OpenCode、Gemini CLI 和 Codex。**
**解决上下文衰减 —— 即 Claude 填充上下文窗口时发生的质量退化问题。**
[![npm version](https://img.shields.io/npm/v/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
[![npm downloads](https://img.shields.io/npm/dm/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
[![Tests](https://img.shields.io/github/actions/workflow/status/glittercowboy/get-shit-done/test.yml?branch=main&style=for-the-badge&logo=github&label=Tests)](https://github.com/glittercowboy/get-shit-done/actions/workflows/test.yml)
[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/gsd)
[![X (Twitter)](https://img.shields.io/badge/X-@gsd__foundation-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/gsd_foundation)
[![$GSD Token](https://img.shields.io/badge/$GSD-Dexscreener-1C1C1C?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0iIzAwRkYwMCIvPjwvc3ZnPg==&logoColor=00FF00)](https://dexscreener.com/solana/dwudwjvan7bzkw9zwlbyv6kspdlvhwzrqy6ebk8xzxkv)
[![GitHub stars](https://img.shields.io/github/stars/glittercowboy/get-shit-done?style=for-the-badge&logo=github&color=181717)](https://github.com/glittercowboy/get-shit-done)
[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
<br>
```bash
npx get-shit-done-cc@latest
```
**支持 Mac、Windows 和 Linux。**
<br>
![GSD Install](../assets/terminal.svg)
<br>
*"如果你清楚自己想要什么，它真的会帮你构建出来。不忽悠。"*
*"我试过 SpecKit、OpenSpec 和 Taskmaster —— 这是我用过的效果最好的。"*
*"这是我用过的 Claude Code 最强大的扩展。没有过度设计。真的就是把事情做完。"*
<br>
**被 Amazon、Google、Shopify 和 Webflow 的工程师信赖使用。**
[我为什么开发这个](#我为什么开发这个) · [工作原理](#工作原理) · [命令](#命令) · [为什么有效](#为什么有效) · [用户指南](USER-GUIDE.md)
</div>
---
## 我为什么开发这个
我是一名独立开发者。我不写代码 —— Claude Code 写。
其他规格驱动开发工具确实存在，比如 BMAD、Speckit... 但它们似乎都把事情搞得比实际需要的复杂得多（冲刺会议、故事点、干系人同步、回顾、Jira 工作流），或者缺乏对你正在构建的东西的真正大局理解。我不是一个 50 人的软件公司。我不想搞企业级表演。我只是个想构建出好用的东西的创意人。
所以我开发了 GSD。复杂性在系统内部，不在你的工作流里。幕后是：上下文工程、XML 提示格式、子代理编排、状态管理。你看到的是：几个命令，用就完了。
系统给 Claude 提供了它完成工作**以及**验证工作所需的一切。我信任这个工作流。它就是做得好。
这就是它的本质。没有企业级角色扮演的废话。只是一个让 Claude Code 稳定可靠地构建酷东西的极其有效的系统。
— **TÂCHES**
---
Vibecoding 名声不好。你描述想要什么，AI 生成代码，结果得到不一致的垃圾，规模一大就崩。
GSD 解决了这个问题。它是让 Claude Code 变得可靠的上下文工程层。描述你的想法，让系统提取它需要知道的一切，然后让 Claude Code 开始工作。
---
## 这个工具适合谁
想要描述需求然后正确构建出来的人 —— 不用假装自己在运营一个 50 人的工程组织。
---
## 快速开始
```bash
npx get-shit-done-cc@latest
```
安装程序会提示你选择：
1. **运行时** —— Claude Code、OpenCode、Gemini、Codex 或全部
2. **位置** —— 全局（所有项目）或本地（仅当前项目）
验证安装：
- Claude Code / Gemini: `/gsd:help`
- OpenCode: `/gsd-help`
- Codex: `$gsd-help`
> [!NOTE]
> Codex 安装使用技能（`skills/gsd-*/SKILL.md`）而非自定义提示。
### 保持更新
GSD 快速迭代。定期更新：
```bash
npx get-shit-done-cc@latest
```
<details>
<summary><strong>非交互式安装（Docker、CI、脚本）</strong></summary>
```bash
# Claude Code
npx get-shit-done-cc --claude --global # 安装到 ~/.claude/
npx get-shit-done-cc --claude --local # 安装到 ./.claude/
# OpenCode（开源，免费模型）
npx get-shit-done-cc --opencode --global # 安装到 ~/.config/opencode/
# Gemini CLI
npx get-shit-done-cc --gemini --global # 安装到 ~/.gemini/
# Codex（技能优先）
npx get-shit-done-cc --codex --global # 安装到 ~/.codex/
npx get-shit-done-cc --codex --local # 安装到 ./.codex/
# 所有运行时
npx get-shit-done-cc --all --global # 安装到所有目录
```
使用 `--global`（`-g`）或 `--local`（`-l`）跳过位置提示。
使用 `--claude`、`--opencode`、`--gemini`、`--codex` 或 `--all` 跳过运行时提示。
</details>
<details>
<summary><strong>开发安装</strong></summary>
克隆仓库并本地运行安装程序：
```bash
git clone https://github.com/glittercowboy/get-shit-done.git
cd get-shit-done
node bin/install.js --claude --local
```
安装到 `./.claude/` 用于在贡献前测试修改。
</details>
### 推荐：跳过权限模式
GSD 设计为无摩擦自动化。运行 Claude Code 时使用：
```bash
claude --dangerously-skip-permissions
```
> [!TIP]
> 这是 GSD 的预期使用方式 —— 停下来 50 次批准 `date` 和 `git commit` 会失去意义。
<details>
<summary><strong>替代方案：细粒度权限</strong></summary>
如果你不想使用那个标志，在项目的 `.claude/settings.json` 中添加：
```json
{
"permissions": {
"allow": [
"Bash(date:*)",
"Bash(echo:*)",
"Bash(cat:*)",
"Bash(ls:*)",
"Bash(mkdir:*)",
"Bash(wc:*)",
"Bash(head:*)",
"Bash(tail:*)",
"Bash(sort:*)",
"Bash(grep:*)",
"Bash(tr:*)",
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git status:*)",
"Bash(git log:*)",
"Bash(git diff:*)",
"Bash(git tag:*)"
]
}
}
```
</details>
---
## 工作原理
> **已有代码？** 先运行 `/gsd:map-codebase`。它会生成并行代理分析你的技术栈、架构、约定和关注点。然后 `/gsd:new-project` 就了解你的代码库了 —— 问题聚焦在你正在**添加**什么，规划会自动加载你的模式。
### 1. 初始化项目
```
/gsd:new-project
```
一条命令，一个流程。系统：
1. **提问** —— 问到完全理解你的想法为止（目标、约束、技术偏好、边缘情况）
2. **研究** —— 生成并行代理调查领域（可选但推荐）
3. **需求** —— 提取哪些是 v1、v2 和范围外
4. **路线图** —— 创建映射到需求的阶段
你批准路线图。现在准备好构建了。
**创建：** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`.planning/research/`
---
### 2. 讨论阶段
```
/gsd:discuss-phase 1
```
**这是你塑造实现方式的地方。**
你的路线图每个阶段有一两句话。这不足以按照**你**想象的方式构建东西。这一步在研究或规划之前捕获你的偏好。
系统分析阶段并根据正在构建的内容识别灰色区域：
- **视觉功能** → 布局、密度、交互、空状态
- **API/CLI** → 响应格式、标志、错误处理、详细程度
- **内容系统** → 结构、语气、深度、流程
- **组织任务** → 分组标准、命名、重复项、例外
对于你选择的每个领域，它会问到让你满意为止。输出 —— `CONTEXT.md` —— 直接输入接下来的两个步骤：
1. **研究员读取它** —— 知道要调查什么模式（"用户想要卡片布局" → 研究卡片组件库）
2. **规划者读取它** —— 知道哪些决策已锁定（"无限滚动已决定" → 规划包含滚动处理）
你在这里走得越深，系统构建的就越是你真正想要的。跳过它你会得到合理的默认值。使用它你会得到**你的**愿景。
**创建：** `{阶段号}-CONTEXT.md`
---
### 3. 规划阶段
```
/gsd:plan-phase 1
```
系统：
1. **研究** —— 调查如何实现这个阶段，由你的 CONTEXT.md 决策指导
2. **规划** —— 创建 2-3 个带有 XML 结构的原子任务计划
3. **验证** —— 根据需求检查计划，循环直到通过
每个计划足够小，可以在全新的上下文窗口中执行。没有退化，没有"我现在会更简洁"。
**创建：** `{阶段号}-RESEARCH.md`、`{阶段号}-{N}-PLAN.md`
---
### 4. 执行阶段
```
/gsd:execute-phase 1
```
系统：
1. **按波次运行计划** —— 可能的话并行，有依赖时顺序
2. **每个计划全新上下文** —— 200k token 纯粹用于实现，零累积垃圾
3. **每个任务提交** —— 每个任务都有自己的原子提交
4. **根据目标验证** —— 检查代码库是否交付了阶段承诺的内容
离开，回来看到完成的工作和干净的 git 历史。
**波次执行工作原理：**
计划根据依赖关系分组到"波次"。在每个波次内，计划并行运行。波次顺序执行。
```
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段执行 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 波次 1 (并行) 波次 2 (并行) 波次 3 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 计划 01 │ │ 计划 02 │ → │ 计划 03 │ │ 计划 04 │ → │ 计划 05 │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ 用户 │ │ 产品 │ │ 订单 │ │ 购物车 │ │ 结账 │ │
│ │ 模型 │ │ 模型 │ │ API │ │ API │ │ UI │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ ↑ ↑ ↑ │
│ └───────────┴──────────────┴───────────┘ │ │
│ 依赖关系: 计划 03 需要计划 01 │ │
│ 计划 04 需要计划 02 │ │
│ 计划 05 需要计划 03 + 04 │ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
**为什么波次重要：**
- 独立计划 → 同一波次 → 并行运行
- 依赖计划 → 后续波次 → 等待依赖
- 文件冲突 → 顺序计划或同一计划
这就是为什么"垂直切片"（计划 01: 用户功能端到端）比"水平分层"（计划 01: 所有模型，计划 02: 所有 API）并行化更好。
**创建：** `{阶段号}-{N}-SUMMARY.md`、`{阶段号}-VERIFICATION.md`
---
### 5. 验证工作
```
/gsd:verify-work 1
```
**这是你确认它真的有效的地方。**
自动化验证检查代码存在和测试通过。但功能是否按你预期的方式**工作**？这是你使用它的机会。
系统：
1. **提取可测试交付物** —— 你现在应该能做什么
2. **逐个引导你** —— "你能用邮箱登录吗？" 是/否，或描述有什么问题
3. **自动诊断失败** —— 生成调试代理找根本原因
4. **创建已验证的修复计划** —— 准备立即重新执行
如果一切通过，继续。如果有东西坏了，不用手动调试 —— 只需再次运行 `/gsd:execute-phase`，使用它创建的修复计划。
**创建：** `{阶段号}-UAT.md`，如果发现问题则创建修复计划
---
### 6. 循环 → 完成 → 下一个里程碑
```
/gsd:discuss-phase 2
/gsd:plan-phase 2
/gsd:execute-phase 2
/gsd:verify-work 2
...
/gsd:complete-milestone
/gsd:new-milestone
```
循环 **讨论 → 规划 → 执行 → 验证** 直到里程碑完成。
如果你想在讨论期间更快速地输入，使用 `/gsd:discuss-phase <n> --batch` 一次回答一组小问题，而不是一个一个来。
每个阶段都会获得你的输入（讨论）、适当的研究（规划）、干净的执行（执行）和人工验证（验证）。上下文保持新鲜。质量保持高水平。
当所有阶段完成后，`/gsd:complete-milestone` 归档里程碑并标记发布。
然后 `/gsd:new-milestone` 开始下一个版本 —— 与 `new-project` 相同的流程，但针对你现有的代码库。你描述接下来想构建什么，系统研究领域，你界定需求范围，它创建新的路线图。每个里程碑是一个干净的周期：定义 → 构建 → 发布。
---
### 快速模式
```
/gsd:quick
```
**用于不需要完整规划的临时任务。**
快速模式给你 GSD 保证（原子提交、状态跟踪）和更快的路径：
- **相同代理** —— 规划者 + 执行者，相同质量
- **跳过可选步骤** —— 无研究、无计划检查器、无验证器
- **独立跟踪** —— 存放在 `.planning/quick/`，不是阶段
用于：bug 修复、小功能、配置更改、一次性任务。
```
/gsd:quick
> 你想做什么？"在设置中添加深色模式切换"
```
**创建：** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`、`SUMMARY.md`
---
## 为什么有效
### 上下文工程
Claude Code 非常强大，**如果你**给它需要的上下文。大多数人没有。
GSD 为你处理：
| 文件 | 作用 |
|------|------|
| `PROJECT.md` | 项目愿景，始终加载 |
| `research/` | 生态知识（技术栈、功能、架构、陷阱） |
| `REQUIREMENTS.md` | 界定 v1/v2 需求及阶段可追溯性 |
| `ROADMAP.md` | 你要去哪里，完成了什么 |
| `STATE.md` | 决策、阻塞项、位置 —— 跨会话记忆 |
| `PLAN.md` | 带有 XML 结构和验证步骤的原子任务 |
| `SUMMARY.md` | 发生了什么，改了什么，提交到历史 |
| `todos/` | 为后续工作捕获的想法和任务 |
基于 Claude 质量退化的位置设置大小限制。保持在限制内，获得一致的卓越。
### XML 提示格式
每个计划都是为 Claude 优化的结构化 XML：
```xml
<task type="auto">
<name>创建登录端点</name>
<files>src/app/api/auth/login/route.ts</files>
<action>
使用 jose 处理 JWT（不用 jsonwebtoken - CommonJS 问题）。
根据 users 表验证凭据。
成功时返回 httpOnly cookie。
</action>
<verify>curl -X POST localhost:3000/api/auth/login 返回 200 + Set-Cookie</verify>
<done>有效凭据返回 cookie，无效返回 401</done>
</task>
```
精确的指令。不猜测。内置验证。
### 多代理编排
每个阶段使用相同模式：轻量编排器生成专门代理，收集结果，路由到下一步。
| 阶段 | 编排器做 | 代理做 |
|-------|------------------|-----------|
| 研究 | 协调，呈现发现 | 4 个并行研究员调查技术栈、功能、架构、陷阱 |
| 规划 | 验证，管理迭代 | 规划者创建计划，检查器验证，循环直到通过 |
| 执行 | 分组为波次，跟踪进度 | 执行者并行实现，每个有全新 200k 上下文 |
| 验证 | 呈现结果，路由下一步 | 验证器根据目标检查代码库，调试器诊断失败 |
编排器从不做重活。它生成代理，等待，整合结果。
**结果：** 你可以运行整个阶段 —— 深度研究、多个计划创建和验证、跨并行执行者编写数千行代码、根据目标自动化验证 —— 你的主上下文窗口保持在 30-40%。工作在全新的子代理上下文中完成。你的会话保持快速和响应。
### 原子 Git 提交
每个任务在完成后立即获得自己的提交：
```bash
abc123f docs(08-02): 完成用户注册计划
def456g feat(08-02): 添加邮箱确认流程
hij789k feat(08-02): 实现密码哈希
lmn012o feat(08-02): 创建注册端点
```
> [!NOTE]
> **好处：** Git bisect 找到确切的失败任务。每个任务独立可回滚。未来会话中 Claude 的清晰历史。AI 自动化工作流中更好的可观察性。
每个提交都是精确的、可追溯的、有意义的。
### 模块化设计
- 向当前里程碑添加阶段
- 在阶段之间插入紧急工作
- 完成里程碑并重新开始
- 调整计划而不重建一切
你永远不会被锁定。系统会适应。
---
## 命令
### 核心工作流
| 命令 | 作用 |
|---------|--------------|
| `/gsd:new-project [--auto]` | 完整初始化：提问 → 研究 → 需求 → 路线图 |
| `/gsd:discuss-phase [N] [--auto]` | 在规划前捕获实现决策 |
| `/gsd:plan-phase [N] [--auto]` | 阶段的研究 + 规划 + 验证 |
| `/gsd:execute-phase <N>` | 在并行波次中执行所有计划，完成后验证 |
| `/gsd:verify-work [N]` | 手动用户验收测试 ¹ |
| `/gsd:audit-milestone` | 验证里程碑达到了其完成定义 |
| `/gsd:complete-milestone` | 归档里程碑，标记发布 |
| `/gsd:new-milestone [name]` | 开始下一个版本：提问 → 研究 → 需求 → 路线图 |
### 导航
| 命令 | 作用 |
|---------|--------------|
| `/gsd:progress` | 我在哪？接下来做什么？ |
| `/gsd:help` | 显示所有命令和使用指南 |
| `/gsd:update` | 更新 GSD 并预览变更日志 |
| `/gsd:join-discord` | 加入 GSD Discord 社区 |
### 现有代码库
| 命令 | 作用 |
|---------|--------------|
| `/gsd:map-codebase` | 在 new-project 之前分析现有代码库 |
### 阶段管理
| 命令 | 作用 |
|---------|--------------|
| `/gsd:add-phase` | 向路线图追加阶段 |
| `/gsd:insert-phase [N]` | 在阶段之间插入紧急工作 |
| `/gsd:remove-phase [N]` | 删除未来阶段，重新编号 |
| `/gsd:list-phase-assumptions [N]` | 规划前查看 Claude 的预期方法 |
| `/gsd:plan-milestone-gaps` | 创建阶段以填补审计发现的差距 |
### 会话
| 命令 | 作用 |
|---------|--------------|
| `/gsd:pause-work` | 阶段中途停止时创建交接 |
| `/gsd:resume-work` | 从上次会话恢复 |
### 工具
| 命令 | 作用 |
|---------|--------------|
| `/gsd:settings` | 配置模型配置文件和工作流代理 |
| `/gsd:set-profile <profile>` | 切换模型配置文件（quality/balanced/budget） |
| `/gsd:add-todo [desc]` | 捕获想法留待后用 |
| `/gsd:check-todos` | 列出待处理事项 |
| `/gsd:debug [desc]` | 带持久状态的系统化调试 |
| `/gsd:quick [--full] [--discuss]` | 用 GSD 保证执行临时任务（`--full` 添加计划检查和验证，`--discuss` 先收集上下文） |
| `/gsd:health [--repair]` | 验证 `.planning/` 目录完整性，用 `--repair` 自动修复 |
<sup>¹ 由 Reddit 用户 OracleGreyBeard 贡献</sup>
---
## 配置
GSD 在 `.planning/config.json` 中存储项目设置。在 `/gsd:new-project` 期间配置或稍后用 `/gsd:settings` 更新。完整配置模式、工作流开关、git 分支选项和每个代理的模型分解，请参阅[用户指南](USER-GUIDE.md#配置参考)。
### 核心设置
| 设置 | 选项 | 默认值 | 控制内容 |
|---------|---------|---------|------------------|
| `mode` | `yolo`, `interactive` | `interactive` | 自动批准 vs 每步确认 |
| `granularity` | `coarse`, `standard`, `fine` | `standard` | 阶段粒度 —— 范围切分多细（阶段 × 计划） |
### 模型配置
控制每个代理使用哪个 Claude 模型。平衡质量和 token 消耗。
| 配置 | 规划 | 执行 | 验证 |
|---------|----------|-----------|--------------|
| `quality` | Opus | Opus | Sonnet |
| `balanced`（默认） | Opus | Sonnet | Sonnet |
| `budget` | Sonnet | Sonnet | Haiku |
切换配置：
```
/gsd:set-profile budget
```
或通过 `/gsd:settings` 配置。
### 工作流代理
这些在规划/执行期间生成额外代理。它们提高质量但增加 token 和时间。
| 设置 | 默认值 | 作用 |
|---------|---------|--------------|
| `workflow.research` | `true` | 每个阶段规划前研究领域 |
| `workflow.plan_check` | `true` | 执行前验证计划是否达到阶段目标 |
| `workflow.verifier` | `true` | 执行后确认必须项已交付 |
| `workflow.auto_advance` | `false` | 自动链式执行 讨论 → 规划 → 执行 |
使用 `/gsd:settings` 切换这些，或每次调用时覆盖：
- `/gsd:plan-phase --skip-research`
- `/gsd:plan-phase --skip-verify`
### 执行
| 设置 | 默认值 | 控制内容 |
|---------|---------|------------------|
| `parallelization.enabled` | `true` | 同时运行独立计划 |
| `planning.commit_docs` | `true` | 在 git 中跟踪 `.planning/` |
### Git 分支
控制 GSD 在执行期间如何处理分支。
| 设置 | 选项 | 默认值 | 作用 |
|---------|---------|---------|--------------|
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 分支创建策略 |
| `git.phase_branch_template` | 字符串 | `gsd/phase-{phase}-{slug}` | 阶段分支模板 |
| `git.milestone_branch_template` | 字符串 | `gsd/{milestone}-{slug}` | 里程碑分支模板 |
**策略：**
- **`none`** —— 提交到当前分支（默认 GSD 行为）
- **`phase`** —— 每个阶段创建一个分支，阶段完成时合并
- **`milestone`** —— 为整个里程碑创建一个分支，完成时合并
在里程碑完成时，GSD 提供 squash 合并（推荐）或带历史合并。
---
## 安全
### 保护敏感文件
GSD 的代码库映射和分析命令读取文件以了解你的项目。**保护包含密钥的文件**，将它们添加到 Claude Code 的拒绝列表：
1. 打开 Claude Code 设置（`.claude/settings.json` 或全局）
2. 将敏感文件模式添加到拒绝列表：
```json
{
"permissions": {
"deny": [
"Read(.env)",
"Read(.env.*)",
"Read(**/secrets/*)",
"Read(**/*credential*)",
"Read(**/*.pem)",
"Read(**/*.key)"
]
}
}
```
这完全阻止 Claude 读取这些文件，无论你运行什么命令。
> [!IMPORTANT]
> GSD 包含内置保护以防止提交密钥，但纵深防御是最佳实践。拒绝读取敏感文件作为第一道防线。
---
## 故障排除
**安装后找不到命令？**
- 重启运行时以重新加载命令/技能
- 验证文件是否存在于 `~/.claude/commands/gsd/`（全局）或 `./.claude/commands/gsd/`（本地）
- 对于 Codex，验证技能是否存在于 `~/.codex/skills/gsd-*/SKILL.md`（全局）或 `./.codex/skills/gsd-*/SKILL.md`（本地）
**命令没有按预期工作？**
- 运行 `/gsd:help` 验证安装
- 重新运行 `npx get-shit-done-cc` 重新安装
**更新到最新版本？**
```bash
npx get-shit-done-cc@latest
```
**使用 Docker 或容器化环境？**
如果用波浪号路径（`~/.claude/...`）读取文件失败，在安装前设置 `CLAUDE_CONFIG_DIR`：
```bash
CLAUDE_CONFIG_DIR=/home/youruser/.claude npx get-shit-done-cc --global
```
这确保使用绝对路径而不是 `~`，后者在容器中可能无法正确展开。
### 卸载
完全删除 GSD：
```bash
# 全局安装
npx get-shit-done-cc --claude --global --uninstall
npx get-shit-done-cc --opencode --global --uninstall
npx get-shit-done-cc --codex --global --uninstall
# 本地安装（当前项目）
npx get-shit-done-cc --claude --local --uninstall
npx get-shit-done-cc --opencode --local --uninstall
npx get-shit-done-cc --codex --local --uninstall
```
这删除所有 GSD 命令、代理、钩子和设置，同时保留你的其他配置。
---
## 社区移植
OpenCode、Gemini CLI 和 Codex 现在通过 `npx get-shit-done-cc` 原生支持。
这些社区移植开创了多运行时支持：
| 项目 | 平台 | 描述 |
|---------|----------|-------------|
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | 原始 OpenCode 适配 |
| gsd-gemini (已归档) | Gemini CLI | 由 uberfuzzy 开发的原始 Gemini 适配 |
---
## Star 历史
<a href="https://star-history.com/#glittercowboy/get-shit-done&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date" />
</picture>
</a>
---
## 许可证
MIT 许可证。详见 [LICENSE](../LICENSE)。
---
<div align="center">
**Claude Code 很强大。GSD 让它可靠。**
</div>

492
docs/zh-CN/USER-GUIDE.md Normal file
View File

@@ -0,0 +1,492 @@
# GSD 用户指南
工作流、故障排除和配置的详细参考。快速入门设置请参阅 [README](README.md)。
---
## 目录
- [工作流图解](#工作流图解)
- [命令参考](#命令参考)
- [配置参考](#配置参考)
- [使用示例](#使用示例)
- [故障排除](#故障排除)
- [恢复快速参考](#恢复快速参考)
---
## 工作流图解
### 完整项目生命周期
```
┌──────────────────────────────────────────────────┐
│ 新建项目 │
│ /gsd:new-project │
│ 提问 -> 研究 -> 需求 -> 路线图 │
└─────────────────────────┬────────────────────────┘
│
┌──────────────▼─────────────┐
│ 每个阶段: │
│ │
│ ┌────────────────────┐ │
│ │ /gsd:discuss-phase │ │ <- 锁定偏好
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd:plan-phase │ │ <- 研究 + 规划 + 验证
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd:execute-phase │ │ <- 并行执行
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd:verify-work │ │ <- 手动 UAT
│ └──────────┬─────────┘ │
│ │ │
│ 下一阶段?────────────┘
│ │ 否
└─────────────┼──────────────┘
│
┌───────────────▼──────────────┐
│ /gsd:audit-milestone │
│ /gsd:complete-milestone │
└───────────────┬──────────────┘
│
另一个里程碑?
│ │
是 否 -> 完成!
│
┌───────▼──────────────┐
│ /gsd:new-milestone │
└──────────────────────┘
```
### 规划代理协调
```
/gsd:plan-phase N
│
├── 阶段研究员 (x4 并行)
│ ├── 技术栈研究员
│ ├── 功能研究员
│ ├── 架构研究员
│ └── 陷阱研究员
│ │
│ ┌──────▼──────┐
│ │ RESEARCH.md │
│ └──────┬──────┘
│ │
│ ┌──────▼──────┐
│ │ 规划者 │ <- 读取 PROJECT.md, REQUIREMENTS.md,
│ │ │ CONTEXT.md, RESEARCH.md
│ └──────┬──────┘
│ │
│ ┌──────▼───────────┐ ┌────────┐
│ │ 计划检查器 │────>│ 通过? │
│ └──────────────────┘ └───┬────┘
│ │
│ 是 │ 否
│ │ │ │
│ │ └───┘ (循环，最多 3 次)
│ │
│ ┌─────▼──────┐
│ │ PLAN 文件 │
│ └────────────┘
└── 完成
```
### 验证架构 (Nyquist 层)
在 plan-phase 研究期间，GSD 现在在任何代码编写之前将自动化测试覆盖率映射到每个阶段需求。这确保当 Claude 的执行者提交任务时，反馈机制已经存在可以在几秒钟内验证它。
研究员检测你现有的测试基础设施，将每个需求映射到特定的测试命令，并识别在实现开始之前必须创建的任何测试脚手架（波次 0 任务）。
计划检查器将其强制作为第 8 个验证维度：缺少自动化验证命令的计划将不会被批准。
**输出：** `{阶段}-VALIDATION.md` —— 阶段的反馈契约。
**禁用：** 在 `/gsd:settings` 中设置 `workflow.nyquist_validation: false`，用于测试基础设施不是重点的快速原型阶段。
### 追溯验证 (`/gsd:validate-phase`)
对于在 Nyquist 验证存在之前执行的阶段，或只有传统测试套件的现有代码库，追溯审计并填补覆盖缺口：
```
/gsd:validate-phase N
|
+-- 检测状态 (VALIDATION.md 存在? SUMMARY.md 存在?)
|
+-- 发现: 扫描实现，将需求映射到测试
|
+-- 分析缺口: 哪些需求缺少自动化验证?
|
+-- 呈现缺口计划供审批
|
+-- 生成审计器: 生成测试，运行，调试（最多 3 次尝试）
|
+-- 更新 VALIDATION.md
|
+-- COMPLIANT -> 所有需求都有自动化检查
+-- PARTIAL -> 部分缺口升级为仅手动
```
审计器从不修改实现代码 —— 只修改测试文件和 VALIDATION.md。如果测试发现实现 bug，它会标记为升级让你处理。
**何时使用：** 在启用了 Nyquist 之前规划的阶段执行后，或在 `/gsd:audit-milestone` 发现 Nyquist 合规缺口后。
### 执行波次协调
```
/gsd:execute-phase N
│
├── 分析计划依赖
│
├── 波次 1 (独立计划):
│ ├── 执行者 A (全新 200K 上下文) -> 提交
│ └── 执行者 B (全新 200K 上下文) -> 提交
│
├── 波次 2 (依赖波次 1):
│ └── 执行者 C (全新 200K 上下文) -> 提交
│
└── 验证器
└── 根据阶段目标检查代码库
│
├── 通过 -> VERIFICATION.md (成功)
└── 失败 -> 问题记录到 /gsd:verify-work
```
### 现有代码库工作流
```
/gsd:map-codebase
│
├── 技术栈映射器 -> codebase/STACK.md
├── 架构映射器 -> codebase/ARCHITECTURE.md
├── 约定映射器 -> codebase/CONVENTIONS.md
└── 关注点映射器 -> codebase/CONCERNS.md
│
┌───────▼──────────┐
│ /gsd:new-project │ <- 问题聚焦于你正在添加的内容
└──────────────────┘
```
---
## 命令参考
### 核心工作流
| 命令 | 用途 | 何时使用 |
|---------|---------|-------------|
| `/gsd:new-project` | 完整项目初始化：提问、研究、需求、路线图 | 新项目开始时 |
| `/gsd:new-project --auto @idea.md` | 从文档自动初始化 | 有现成的 PRD 或想法文档 |
| `/gsd:discuss-phase [N]` | 捕获实现决策 | 规划前，塑造构建方式 |
| `/gsd:plan-phase [N]` | 研究 + 规划 + 验证 | 执行阶段前 |
| `/gsd:execute-phase <N>` | 在并行波次中执行所有计划 | 规划完成后 |
| `/gsd:verify-work [N]` | 带自动诊断的手动 UAT | 执行完成后 |
| `/gsd:audit-milestone` | 验证里程碑达到其完成定义 | 完成里程碑前 |
| `/gsd:complete-milestone` | 归档里程碑，标记发布 | 所有阶段已验证 |
| `/gsd:new-milestone [name]` | 开始下一个版本周期 | 完成里程碑后 |
### 导航
| 命令 | 用途 | 何时使用 |
|---------|---------|-------------|
| `/gsd:progress` | 显示状态和下一步 | 任何时候 -- "我在哪?" |
| `/gsd:resume-work` | 从上次会话恢复完整上下文 | 开始新会话 |
| `/gsd:pause-work` | 保存上下文交接 | 阶段中途停止 |
| `/gsd:help` | 显示所有命令 | 快速参考 |
| `/gsd:update` | 更新 GSD 并预览变更日志 | 检查新版本 |
| `/gsd:join-discord` | 打开 Discord 社区邀请 | 问题或社区 |
### 阶段管理
| 命令 | 用途 | 何时使用 |
|---------|---------|-------------|
| `/gsd:add-phase` | 向路线图追加新阶段 | 初始规划后范围增长 |
| `/gsd:insert-phase [N]` | 插入紧急工作（小数编号） | 里程碑中途紧急修复 |
| `/gsd:remove-phase [N]` | 删除未来阶段并重新编号 | 移除某个功能 |
| `/gsd:list-phase-assumptions [N]` | 预览 Claude 的预期方法 | 规划前，验证方向 |
| `/gsd:plan-milestone-gaps` | 为审计缺口创建阶段 | 审计发现缺失项后 |
| `/gsd:research-phase [N]` | 仅深度生态研究 | 复杂或不熟悉的领域 |
### 现有代码库和工具
| 命令 | 用途 | 何时使用 |
|---------|---------|-------------|
| `/gsd:map-codebase` | 分析现有代码库 | 在现有代码上运行 `/gsd:new-project` 之前 |
| `/gsd:quick` | 带 GSD 保证的临时任务 | Bug 修复、小功能、配置更改 |
| `/gsd:debug [desc]` | 带持久状态的系统化调试 | 出问题时 |
| `/gsd:add-todo [desc]` | 捕获想法留待后用 | 会话期间想到什么 |
| `/gsd:check-todos` | 列出待处理事项 | 查看捕获的想法 |
| `/gsd:settings` | 配置工作流开关和模型配置 | 更改模型、切换代理 |
| `/gsd:set-profile <profile>` | 快速切换配置 | 更改成本/质量权衡 |
| `/gsd:reapply-patches` | 更新后恢复本地修改 | 如果你有本地编辑，在 `/gsd:update` 后 |
---
## 配置参考
GSD 在 `.planning/config.json` 中存储项目设置。在 `/gsd:new-project` 期间配置或稍后用 `/gsd:settings` 更新。
### 完整 config.json 模式
```json
{
"mode": "interactive",
"granularity": "standard",
"model_profile": "balanced",
"planning": {
"commit_docs": true,
"search_gitignored": false
},
"workflow": {
"research": true,
"plan_check": true,
"verifier": true,
"nyquist_validation": true
},
"git": {
"branching_strategy": "none",
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}"
}
}
```
### 核心设置
| 设置 | 选项 | 默认值 | 控制内容 |
|---------|---------|---------|------------------|
| `mode` | `interactive`, `yolo` | `interactive` | `yolo` 自动批准决策；`interactive` 每步确认 |
| `granularity` | `coarse`, `standard`, `fine` | `standard` | 阶段粒度：范围切分多细（3-5、5-8 或 8-12 个阶段） |
| `model_profile` | `quality`, `balanced`, `budget` | `balanced` | 每个代理的模型层级（见下表） |
### 规划设置
| 设置 | 选项 | 默认值 | 控制内容 |
|---------|---------|---------|------------------|
| `planning.commit_docs` | `true`, `false` | `true` | `.planning/` 文件是否提交到 git |
| `planning.search_gitignored` | `true`, `false` | `false` | 在广泛搜索中添加 `--no-ignore` 以包含 `.planning/` |
> **注意：** 如果 `.planning/` 在 `.gitignore` 中，无论配置值如何，`commit_docs` 自动为 `false`。
### 工作流开关
| 设置 | 选项 | 默认值 | 控制内容 |
|---------|---------|---------|------------------|
| `workflow.research` | `true`, `false` | `true` | 规划前的领域调查 |
| `workflow.plan_check` | `true`, `false` | `true` | 计划验证循环（最多 3 次迭代） |
| `workflow.verifier` | `true`, `false` | `true` | 根据阶段目标的执行后验证 |
| `workflow.nyquist_validation` | `true`, `false` | `true` | plan-phase 期间的验证架构研究；第 8 个计划检查维度 |
在熟悉的领域或需要节省 token 时禁用这些以加速阶段。
### Git 分支
| 设置 | 选项 | 默认值 | 控制内容 |
|---------|---------|---------|------------------|
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 何时以及如何创建分支 |
| `git.phase_branch_template` | 模板字符串 | `gsd/phase-{phase}-{slug}` | 阶段策略的分支名 |
| `git.milestone_branch_template` | 模板字符串 | `gsd/{milestone}-{slug}` | 里程碑策略的分支名 |
**分支策略说明：**
| 策略 | 创建分支 | 范围 | 适用于 |
|----------|---------------|-------|----------|
| `none` | 从不 | N/A | 独立开发、简单项目 |
| `phase` | 每次 `execute-phase` | 每个阶段一个分支 | 每阶段代码审查、细粒度回滚 |
| `milestone` | 第一次 `execute-phase` | 所有阶段共享一个分支 | 发布分支、每个版本一个 PR |
**模板变量：** `{phase}` = 零填充数字（如 "03"），`{slug}` = 小写连字符名称，`{milestone}` = 版本（如 "v1.0"）。
### 模型配置（每个代理分解）
| 代理 | `quality` | `balanced` | `budget` |
|-------|-----------|------------|----------|
| gsd-planner | Opus | Opus | Sonnet |
| gsd-roadmapper | Opus | Sonnet | Sonnet |
| gsd-executor | Opus | Sonnet | Sonnet |
| gsd-phase-researcher | Opus | Sonnet | Haiku |
| gsd-project-researcher | Opus | Sonnet | Haiku |
| gsd-research-synthesizer | Sonnet | Sonnet | Haiku |
| gsd-debugger | Opus | Sonnet | Sonnet |
| gsd-codebase-mapper | Sonnet | Haiku | Haiku |
| gsd-verifier | Sonnet | Sonnet | Haiku |
| gsd-plan-checker | Sonnet | Sonnet | Haiku |
| gsd-integration-checker | Sonnet | Sonnet | Haiku |
**配置理念：**
- **quality** —— 所有决策代理使用 Opus，只读验证使用 Sonnet。有配额可用且工作关键时使用。
- **balanced** —— 仅规划（架构决策发生的地方）使用 Opus，其他全部使用 Sonnet。这是默认，有充分理由。
- **budget** —— 编写代码的使用 Sonnet，研究和验证使用 Haiku。大量工作或不太关键的阶段使用。
---
## 使用示例
### 新项目（完整周期）
```bash
claude --dangerously-skip-permissions
/gsd:new-project # 回答问题，配置，批准路线图
/clear
/gsd:discuss-phase 1 # 锁定你的偏好
/gsd:plan-phase 1 # 研究 + 规划 + 验证
/gsd:execute-phase 1 # 并行执行
/gsd:verify-work 1 # 手动 UAT
/clear
/gsd:discuss-phase 2 # 对每个阶段重复
...
/gsd:audit-milestone # 检查所有内容已发布
/gsd:complete-milestone # 归档，标记，完成
```
### 从现有文档创建新项目
```bash
/gsd:new-project --auto @prd.md # 从你的文档自动运行研究/需求/路线图
/clear
/gsd:discuss-phase 1 # 从这里开始正常流程
```
### 现有代码库
```bash
/gsd:map-codebase # 分析现有内容（并行代理）
/gsd:new-project # 问题聚焦于你正在添加的内容
# （从这里开始正常阶段工作流）
```
### 快速 Bug 修复
```bash
/gsd:quick
> "修复移动端 Safari 上登录按钮无响应的问题"
```
### 中断后恢复
```bash
/gsd:progress # 查看你停在哪和接下来做什么
# 或
/gsd:resume-work # 从上次会话完整恢复上下文
```
### 准备发布
```bash
/gsd:audit-milestone # 检查需求覆盖率，检测存根
/gsd:plan-milestone-gaps # 如果审计发现缺口，创建阶段来填补
/gsd:complete-milestone # 归档，标记，完成
```
### 速度与质量预设
| 场景 | 模式 | 粒度 | 配置 | 研究 | 计划检查 | 验证器 |
|----------|------|-------|---------|----------|------------|----------|
| 原型开发 | `yolo` | `coarse` | `budget` | 关 | 关 | 关 |
| 正常开发 | `interactive` | `standard` | `balanced` | 开 | 开 | 开 |
| 生产环境 | `interactive` | `fine` | `quality` | 开 | 开 | 开 |
### 里程碑中途范围变更
```bash
/gsd:add-phase # 向路线图追加新阶段
# 或
/gsd:insert-phase 3 # 在阶段 3 和 4 之间插入紧急工作
# 或
/gsd:remove-phase 7 # 移除阶段 7 并重新编号
```
---
## 故障排除
### "项目已初始化"
你运行了 `/gsd:new-project` 但 `.planning/PROJECT.md` 已存在。这是安全检查。如果你想重新开始，先删除 `.planning/` 目录。
### 长会话期间上下文退化
在主要命令之间清除上下文窗口：Claude Code 中的 `/clear`。GSD 设计围绕全新上下文 —— 每个子代理获得干净的 200K 窗口。如果主会话质量下降，清除并使用 `/gsd:resume-work` 或 `/gsd:progress` 恢复状态。
### 计划看起来错误或不一致
在规划前运行 `/gsd:discuss-phase [N]`。大多数计划质量问题来自 Claude 做出了 `CONTEXT.md` 本可以防止的假设。你也可以运行 `/gsd:list-phase-assumptions [N]` 在提交计划前查看 Claude 打算做什么。
### 执行失败或产生存根
检查计划是否太雄心勃勃。计划最多应有 2-3 个任务。如果任务太大，它们超出了单个上下文窗口可以可靠产生的内容。用更小的范围重新规划。
### 忘记你在哪里
运行 `/gsd:progress`。它读取所有状态文件，准确告诉你位置和下一步。
### 执行后需要更改某些内容
不要重新运行 `/gsd:execute-phase`。使用 `/gsd:quick` 进行针对性修复，或用 `/gsd:verify-work` 通过 UAT 系统识别和修复问题。
### 模型成本太高
切换到 budget 配置：`/gsd:set-profile budget`。如果领域对你（或 Claude）熟悉，通过 `/gsd:settings` 禁用研究和计划检查代理。
### 处理敏感/私有项目
在 `/gsd:new-project` 期间或通过 `/gsd:settings` 设置 `commit_docs: false`。将 `.planning/` 添加到 `.gitignore`。规划工件保留在本地，从不接触 git。
### GSD 更新覆盖了我的本地更改
从 v1.17 开始，安装程序将本地修改的文件备份到 `gsd-local-patches/`。运行 `/gsd:reapply-patches` 将你的更改合并回来。
### 子代理似乎失败但工作已完成
存在 Claude Code 分类 bug 的已知解决方法。GSD 的编排器（execute-phase、quick）在报告失败前抽查实际输出。如果你看到失败消息但提交已创建，检查 `git log` —— 工作可能已成功。
---
## 恢复快速参考
| 问题 | 解决方案 |
|---------|----------|
| 丢失上下文 / 新会话 | `/gsd:resume-work` 或 `/gsd:progress` |
| 阶段出错 | `git revert` 阶段提交，然后重新规划 |
| 需要更改范围 | `/gsd:add-phase`、`/gsd:insert-phase` 或 `/gsd:remove-phase` |
| 里程碑审计发现缺口 | `/gsd:plan-milestone-gaps` |
| 出问题了 | `/gsd:debug "描述"` |
| 快速针对性修复 | `/gsd:quick` |
| 计划与你的愿景不符 | `/gsd:discuss-phase [N]` 然后重新规划 |
| 成本过高 | `/gsd:set-profile budget` 和 `/gsd:settings` 关闭代理 |
| 更新破坏了本地更改 | `/gsd:reapply-patches` |
---
## 项目文件结构
供参考，这是 GSD 在你的项目中创建的内容：
```
.planning/
PROJECT.md # 项目愿景和上下文（始终加载）
REQUIREMENTS.md # 界定 v1/v2 需求及 ID
ROADMAP.md # 带状态跟踪的阶段分解
STATE.md # 决策、阻塞项、会话记忆
config.json # 工作流配置
MILESTONES.md # 已完成里程碑归档
research/ # 来自 /gsd:new-project 的领域研究
todos/
pending/ # 等待处理的捕获想法
done/ # 已完成的待办事项
debug/ # 活跃调试会话
resolved/ # 已归档的调试会话
codebase/ # 现有代码库映射（来自 /gsd:map-codebase）
phases/
XX-phase-name/
XX-YY-PLAN.md # 原子执行计划
XX-YY-SUMMARY.md # 执行结果和决策
CONTEXT.md # 你的实现偏好
RESEARCH.md # 生态研究发现
VERIFICATION.md # 执行后验证结果
```

450
docs/zh-CN/references/checkpoints.md Normal file
View File

@@ -0,0 +1,450 @@
# 检查点
计划自主执行。检查点用于规范化需要人工验证或决策的交互点。
**核心原则：** Claude 用 CLI/API 自动化一切。检查点用于验证和决策，而非手动工作。
**黄金法则：**
1. **如果 Claude 能运行，Claude 就运行** - 绝不让用户执行 CLI 命令、启动服务器或运行构建
2. **Claude 设置验证环境** - 启动开发服务器、填充数据库、配置环境变量
3. **用户只做需要人工判断的事** - 视觉检查、UX 评估、"这个感觉对吗？"
4. **密钥来自用户，自动化来自 Claude** - 询问 API 密钥，然后 Claude 通过 CLI 使用它们
5. **自动模式绕过验证/决策检查点** — 当 config 中 `workflow._auto_chain_active` 或 `workflow.auto_advance` 为 true 时：human-verify 自动批准，decision 自动选择第一个选项，human-action 仍会停止（认证门控无法自动化）
## 检查点类型
### checkpoint:human-verify（最常见 - 90%）
**何时使用：** Claude 完成自动化工作，人工确认其正常工作。
**用于：**
- 视觉 UI 检查（布局、样式、响应式）
- 交互流程（点击向导、测试用户流程）
- 功能验证（功能按预期工作）
- 音频/视频播放质量
- 动画流畅度
- 无障碍测试
**结构：**
```xml
<task type="checkpoint:human-verify" gate="blocking">
<what-built>[Claude 自动化并部署/构建的内容]</what-built>
<how-to-verify>
[测试的确切步骤 - URL、命令、预期行为]
</how-to-verify>
<resume-signal>[如何继续 - "approved"、"yes" 或描述问题]</resume-signal>
</task>
```
**示例：UI 组件（展示关键模式：Claude 在检查点之前启动服务器）**
```xml
<task type="auto">
<name>构建响应式仪表板布局</name>
<files>src/components/Dashboard.tsx, src/app/dashboard/page.tsx</files>
<action>创建带侧边栏、标题和内容区域的仪表板。使用 Tailwind 响应式类处理移动端。</action>
<verify>npm run build 成功，无 TypeScript 错误</verify>
<done>仪表板组件构建无错误</done>
</task>
<task type="auto">
<name>启动开发服务器用于验证</name>
<action>在后台运行 `npm run dev`，等待 "ready" 消息，捕获端口</action>
<verify>curl http://localhost:3000 返回 200</verify>
<done>开发服务器运行于 http://localhost:3000</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>响应式仪表板布局 - 开发服务器运行于 http://localhost:3000</what-built>
<how-to-verify>
访问 http://localhost:3000/dashboard 并验证：
1. 桌面端 (>1024px): 左侧边栏，右侧内容，顶部标题
2. 平板端 (768px): 侧边栏折叠为汉堡菜单
3. 移动端 (375px): 单列布局，出现底部导航
4. 任何尺寸无布局偏移或水平滚动
</how-to-verify>
<resume-signal>输入 "approved" 或描述布局问题</resume-signal>
</task>
```
### checkpoint:decision（9%）
**何时使用：** 人工必须做出影响实现方向的选择。
**用于：**
- 技术选型（哪个认证提供商、哪个数据库）
- 架构决策（monorepo 还是独立仓库）
- 设计选择（配色方案、布局方式）
- 功能优先级（构建哪个变体）
- 数据模型决策（模式结构）
**结构：**
```xml
<task type="checkpoint:decision" gate="blocking">
<decision>[正在决策的内容]</decision>
<context>[为什么这个决策重要]</context>
<options>
<option id="option-a">
<name>[选项名称]</name>
<pros>[好处]</pros>
<cons>[权衡]</cons>
</option>
<option id="option-b">
<name>[选项名称]</name>
<pros>[好处]</pros>
<cons>[权衡]</cons>
</option>
</options>
<resume-signal>[如何表明选择]</resume-signal>
</task>
```
**示例：认证提供商选择**
```xml
<task type="checkpoint:decision" gate="blocking">
<decision>选择认证提供商</decision>
<context>
应用需要用户认证。三个可靠选项各有权衡。
</context>
<options>
<option id="supabase">
<name>Supabase Auth</name>
<pros>与我们使用的 Supabase DB 内置集成，慷慨的免费额度，行级安全集成</pros>
<cons>UI 定制性较差，绑定 Supabase 生态</cons>
</option>
<option id="clerk">
<name>Clerk</name>
<pros>精美的预构建 UI，最佳开发体验，优秀文档</pros>
<cons>10k MAU 后付费，供应商锁定</cons>
</option>
<option id="nextauth">
<name>NextAuth.js</name>
<pros>免费，自托管，最大控制权，广泛采用</pros>
<cons>更多设置工作，需自行管理安全更新，UI 需自己构建</cons>
</option>
</options>
<resume-signal>选择：supabase、clerk 或 nextauth</resume-signal>
</task>
```
### checkpoint:human-action（1% - 罕见）
**何时使用：** 操作没有 CLI/API 且需要仅人工交互，或者 Claude 在自动化过程中遇到认证门控。
**仅用于：**
- **认证门控** - Claude 尝试了 CLI/API 但需要凭证（这不是失败）
- 邮箱验证链接（点击邮件）
- 短信两步验证码（手机验证）
- 人工账户审批（平台需要人工审核）
- 信用卡 3D Secure 流程（基于 Web 的支付授权）
- OAuth 应用审批（基于 Web 的审批）
**不要用于预定的手动工作：**
- 部署（使用 CLI - 如需要则认证门控）
- 创建 webhooks/数据库（使用 API/CLI - 如需要则认证门控）
- 运行构建/测试（使用 Bash 工具）
- 创建文件（使用 Write 工具）
**结构：**
```xml
<task type="checkpoint:human-action" gate="blocking">
<action>[人工必须做什么 - Claude 已完成所有可自动化的]</action>
<instructions>
[Claude 已自动化的内容]
[需要人工操作的一件事]
</instructions>
<verification>[Claude 之后可以检查的内容]</verification>
<resume-signal>[如何继续]</resume-signal>
</task>
```
**示例：认证门控（动态检查点）**
```xml
<task type="auto">
<name>部署到 Vercel</name>
<files>.vercel/, vercel.json</files>
<action>运行 `vercel --yes` 进行部署</action>
<verify>vercel ls 显示部署，curl 返回 200</verify>
</task>
<!-- 如果 vercel 返回 "Error: Not authenticated"，Claude 即时创建检查点 -->
<task type="checkpoint:human-action" gate="blocking">
<action>认证 Vercel CLI 以便我继续部署</action>
<instructions>
我尝试部署但收到认证错误。
运行：vercel login
这将打开你的浏览器 - 完成认证流程。
</instructions>
<verification>vercel whoami 返回你的账户邮箱</verification>
<resume-signal>认证完成后输入 "done"</resume-signal>
</task>
<!-- 认证后，Claude 重试部署 -->
<task type="auto">
<name>重试 Vercel 部署</name>
<action>运行 `vercel --yes`（已认证）</action>
<verify>vercel ls 显示部署，curl 返回 200</verify>
</task>
```
**关键区别：** 认证门控是 Claude 遇到认证错误时动态创建的。不是预定的 — Claude 先自动化，只有在被阻止时才请求凭证。
## 执行协议
当 Claude 遇到 `type="checkpoint:*"` 时：
1. **立即停止** - 不继续下一个任务
2. **清晰显示检查点** 使用下面的格式
3. **等待用户响应** - 不幻想完成
4. **如可能则验证** - 检查文件、运行测试、任何指定的内容
5. **恢复执行** - 仅在确认后继续下一个任务
**对于 checkpoint:human-verify:**
```
╔═══════════════════════════════════════════════════════╗
║ CHECKPOINT: 需要验证 ║
╚═══════════════════════════════════════════════════════╝
进度: 5/8 任务完成
任务: 响应式仪表板布局
已构建: /dashboard 的响应式仪表板
如何验证:
1. 访问: http://localhost:3000/dashboard
2. 桌面端 (>1024px): 侧边栏可见，内容填充剩余空间
3. 平板端 (768px): 侧边栏折叠为图标
4. 移动端 (375px): 侧边栏隐藏，出现汉堡菜单
────────────────────────────────────────────────────────
→ 你的操作: 输入 "approved" 或描述问题
────────────────────────────────────────────────────────
```
**对于 checkpoint:decision:**
```
╔═══════════════════════════════════════════════════════╗
║ CHECKPOINT: 需要决策 ║
╚═══════════════════════════════════════════════════════╝
进度: 2/6 任务完成
任务: 选择认证提供商
决策: 我们应该使用哪个认证提供商？
上下文: 需要用户认证。三个选项各有权衡。
选项:
1. supabase - 与我们的数据库内置集成，免费额度
优点: 行级安全集成，慷慨的免费额度
缺点: UI 定制性较差，生态锁定
2. clerk - 最佳 DX，10k 用户后付费
优点: 精美的预构建 UI，优秀文档
缺点: 供应商锁定，规模化时价格问题
3. nextauth - 自托管，最大控制权
优点: 免费，无供应商锁定，广泛采用
缺点: 更多设置工作，自行 DIY 安全更新
────────────────────────────────────────────────────────
→ 你的操作: 选择 supabase、clerk 或 nextauth
────────────────────────────────────────────────────────
```
## 认证门控
**认证门控 = Claude 尝试了 CLI/API，收到认证错误。** 不是失败 — 是需要人工输入来解除阻止的门控。
**模式：** Claude 尝试自动化 → 认证错误 → 创建 checkpoint:human-action → 用户认证 → Claude 重试 → 继续
**门控协议：**
1. 认识到这不是失败 - 缺少认证是正常的
2. 停止当前任务 - 不要反复重试
3. 动态创建 checkpoint:human-action
4. 提供确切的认证步骤
5. 验证认证有效
6. 重试原始任务
7. 正常继续
**关键区别：**
- 预定的检查点："我需要你做 X"（错误 - Claude 应该自动化）
- 认证门控："我尝试自动化 X 但需要凭证"（正确 - 解除自动化阻止）
## 自动化参考
**规则：** 如果有 CLI/API，Claude 就做。绝不让人工执行可自动化的工作。
### 服务 CLI 参考
| 服务 | CLI/API | 关键命令 | 认证门控 |
|------|---------|----------|----------|
| Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` |
| Railway | `railway` | `init`, `up`, `variables set` | `railway login` |
| Fly | `fly` | `launch`, `deploy`, `secrets set` | `fly auth login` |
| Stripe | `stripe` + API | `listen`, `trigger`, API 调用 | .env 中的 API key |
| Supabase | `supabase` | `init`, `link`, `db push`, `gen types` | `supabase login` |
| Upstash | `upstash` | `redis create`, `redis get` | `upstash auth login` |
| PlanetScale | `pscale` | `database create`, `branch create` | `pscale auth login` |
| GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` |
| Node | `npm`/`pnpm` | `install`, `run build`, `test`, `run dev` | N/A |
| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |
| Convex | `npx convex` | `dev`, `deploy`, `env set`, `env get` | `npx convex login` |
### 环境变量自动化
**Env 文件：** 使用 Write/Edit 工具。绝不让用户手动创建 .env。
**通过 CLI 的仪表板环境变量：**
| 平台 | CLI 命令 | 示例 |
|------|----------|------|
| Convex | `npx convex env set` | `npx convex env set OPENAI_API_KEY sk-...` |
| Vercel | `vercel env add` | `vercel env add STRIPE_KEY production` |
| Railway | `railway variables set` | `railway variables set API_KEY=value` |
| Fly | `fly secrets set` | `fly secrets set DATABASE_URL=...` |
| Supabase | `supabase secrets set` | `supabase secrets set MY_SECRET=value` |
### 开发服务器自动化
| 框架 | 启动命令 | 就绪信号 | 默认 URL |
|------|----------|----------|----------|
| Next.js | `npm run dev` | "Ready in" 或 "started server" | http://localhost:3000 |
| Vite | `npm run dev` | "ready in" | http://localhost:5173 |
| Convex | `npx convex dev` | "Convex functions ready" | N/A（仅后端）|
| Express | `npm start` | "listening on port" | http://localhost:3000 |
| Django | `python manage.py runserver` | "Starting development server" | http://localhost:8000 |
**服务器生命周期：**
```bash
# 后台运行，捕获 PID
npm run dev &
DEV_SERVER_PID=$!
# 等待就绪（最多 30s）
timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done'
```
**端口冲突：** 终止陈旧进程（`lsof -ti:3000 | xargs kill`）或使用备用端口（`--port 3001`）。
**服务器保持运行** 直到检查点结束。仅在计划完成、切换到生产环境或端口需要用于不同服务时终止。
### CLI 安装处理
| CLI | 自动安装？ | 命令 |
|-----|------------|------|
| npm/pnpm/yarn | 否 - 询问用户 | 用户选择包管理器 |
| vercel | 是 | `npm i -g vercel` |
| gh (GitHub) | 是 | `brew install gh` (macOS) 或 `apt install gh` (Linux) |
| stripe | 是 | `npm i -g stripe` |
| supabase | 是 | `npm i -g supabase` |
| convex | 否 - 使用 npx | `npx convex`（无需安装）|
| fly | 是 | `brew install flyctl` 或 curl 安装器 |
| railway | 是 | `npm i -g @railway/cli` |
**协议：** 尝试命令 → "command not found" → 可自动安装？→ 是：静默安装，重试 → 否：检查点请求用户安装。
## 检查点前自动化失败处理
| 失败 | 响应 |
|------|------|
| 服务器无法启动 | 检查错误，修复问题，重试（不进入检查点）|
| 端口被占用 | 终止陈旧进程或使用备用端口 |
| 缺少依赖 | 运行 `npm install`，重试 |
| 构建错误 | 先修复错误（是 bug，不是检查点问题）|
| 认证错误 | 创建认证门控检查点 |
| 网络超时 | 带退避重试，如果持续则检查点 |
**绝不呈现验证环境损坏的检查点。** 如果 `curl localhost:3000` 失败，不要让用户"访问 localhost:3000"。
## 可自动化快速参考
| 操作 | 可自动化？| Claude 做？|
|------|------------|------------|
| 部署到 Vercel | 是 (`vercel`) | 是 |
| 创建 Stripe webhook | 是 (API) | 是 |
| 写入 .env 文件 | 是 (Write 工具) | 是 |
| 创建 Upstash DB | 是 (`upstash`) | 是 |
| 运行测试 | 是 (`npm test`) | 是 |
| 启动开发服务器 | 是 (`npm run dev`) | 是 |
| 添加环境变量到 Convex | 是 (`npx convex env set`) | 是 |
| 添加环境变量到 Vercel | 是 (`vercel env add`) | 是 |
| 填充数据库 | 是 (CLI/API) | 是 |
| 点击邮件验证链接 | 否 | 否 |
| 输入带 3DS 的信用卡 | 否 | 否 |
| 在浏览器中完成 OAuth | 否 | 否 |
| 视觉验证 UI 是否正确 | 否 | 否 |
| 测试交互式用户流程 | 否 | 否 |
## 反模式
### ❌ 错误：让用户启动开发服务器
```xml
<task type="checkpoint:human-verify" gate="blocking">
<what-built>仪表板组件</what-built>
<how-to-verify>
1. 运行: npm run dev
2. 访问: http://localhost:3000/dashboard
3. 检查布局是否正确
</how-to-verify>
</task>
```
**为什么错误：** Claude 可以运行 `npm run dev`。用户应该只访问 URL，不执行命令。
### ✅ 正确：Claude 启动服务器，用户访问
```xml
<task type="auto">
<name>启动开发服务器</name>
<action>在后台运行 `npm run dev`</action>
<verify>curl localhost:3000 返回 200</verify>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>http://localhost:3000/dashboard 的仪表板（服务器运行中）</what-built>
<how-to-verify>
访问 http://localhost:3000/dashboard 并验证：
1. 布局匹配设计
2. 无控制台错误
</how-to-verify>
</task>
```
### ❌ 错误：让用户部署 / ✅ 正确：Claude 自动化
```xml
<!-- 错误：让用户通过仪表板部署 -->
<task type="checkpoint:human-action" gate="blocking">
<action>部署到 Vercel</action>
<instructions>访问 vercel.com/new → 导入仓库 → 点击部署 → 复制 URL</instructions>
</task>
<!-- 正确：Claude 部署，用户验证 -->
<task type="auto">
<name>部署到 Vercel</name>
<action>运行 `vercel --yes`。捕获 URL。</action>
<verify>vercel ls 显示部署，curl 返回 200</verify>
</task>
<task type="checkpoint:human-verify">
<what-built>已部署到 {url}</what-built>
<how-to-verify>访问 {url}，检查首页加载</how-to-verify>
<resume-signal>输入 "approved"</resume-signal>
</task>
```
## 摘要
检查点规范化人工介入点用于验证和决策，而非手动工作。
**黄金法则：** 如果 Claude 能自动化它，Claude 就必须自动化它。
**检查点优先级：**
1. **checkpoint:human-verify**（90%）- Claude 自动化一切，人工确认视觉/功能正确性
2. **checkpoint:decision**（9%）- 人工做出架构/技术选择
3. **checkpoint:human-action**（1%）- 真正无法避免的、没有 API/CLI 的手动步骤
**何时不用检查点：**
- Claude 可以编程验证的事情（测试、构建）
- 文件操作（Claude 可以读取文件）
- 代码正确性（测试和静态分析）
- 任何可通过 CLI/API 自动化的内容

249
docs/zh-CN/references/continuation-format.md Normal file
View File

@@ -0,0 +1,249 @@
# 续接格式
完成命令或工作流后展示下一步的标准格式。
## 核心结构
```
---
## ▶ 下一步
**{标识符}: {名称}** — {单行描述}
`{可复制粘贴的命令}`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
---
**也可选：**
- `{备选项 1}` — 描述
- `{备选项 2}` — 描述
---
```
## 格式规则
1. **始终展示它是什么** — 名称 + 描述，绝不仅仅是一个命令路径
2. **从源文件拉取上下文** — ROADMAP.md 用于阶段，PLAN.md `<objective>` 用于计划
3. **命令用内联代码** — 反引号，易于复制粘贴，渲染为可点击链接
4. **`/clear` 说明** — 始终包含，保持简洁但解释原因
5. **用"也可选"而非"其他选项"** — 听起来更像应用
6. **视觉分隔符** — 上下用 `---` 使其突出
## 变体
### 执行下一个计划
```
---
## ▶ 下一步
**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh
`/gsd:execute-phase 2`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
---
**也可选：**
- 执行前审查计划
- `/gsd:list-phase-assumptions 2` — 检查假设
---
```
### 执行阶段中最后一个计划
添加注释说明这是最后一个计划以及接下来是什么：
```
---
## ▶ 下一步
**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh
<sub>阶段 2 的最后一个计划</sub>
`/gsd:execute-phase 2`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
---
**完成后：**
- 阶段 2 → 阶段 3 过渡
- 下一步：**阶段 3: 核心功能** — 用户仪表板和设置
---
```
### 规划阶段
```
---
## ▶ 下一步
**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程
`/gsd:plan-phase 2`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
---
**也可选：**
- `/gsd:discuss-phase 2` — 先收集上下文
- `/gsd:research-phase 2` — 调查未知项
- 审查路线图
---
```
### 阶段完成，准备下一步
在下一步操作前显示完成状态：
```
---
## ✓ 阶段 2 完成
3/3 计划已执行
## ▶ 下一步
**阶段 3: 核心功能** — 用户仪表板、设置和数据导出
`/gsd:plan-phase 3`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
---
**也可选：**
- `/gsd:discuss-phase 3` — 先收集上下文
- `/gsd:research-phase 3` — 调查未知项
- 回顾阶段 2 构建的内容
---
```
### 多个同等选项
当没有明确的主要操作时：
```
---
## ▶ 下一步
**阶段 3: 核心功能** — 用户仪表板、设置和数据导出
**直接规划：** `/gsd:plan-phase 3`
**先讨论上下文：** `/gsd:discuss-phase 3`
**研究未知项：** `/gsd:research-phase 3`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
---
```
### 里程碑完成
```
---
## 🎉 里程碑 v1.0 完成
全部 4 个阶段已发布
## ▶ 下一步
**开始 v1.1** — 提问 → 研究 → 需求 → 路线图
`/gsd:new-milestone`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
---
```
## 拉取上下文
### 用于阶段（从 ROADMAP.md）：
```markdown
### 阶段 2: 认证
**目标**: 带刷新令牌的 JWT 登录流程
```
提取：`**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程`
### 用于计划（从 ROADMAP.md）：
```markdown
计划:
- [ ] 02-03: 添加刷新令牌轮换
```
或从 PLAN.md `<objective>`：
```xml
<objective>
添加带滑动过期窗口的刷新令牌轮换。
目的: 在不影响安全性的前提下延长会话生命周期。
</objective>
```
提取：`**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh`
## 反模式
### 不要：仅命令（无上下文）
```
## 继续
运行 `/clear`，然后粘贴：
/gsd:execute-phase 2
```
用户不知道 02-03 是关于什么的。
### 不要：缺少 /clear 说明
```
`/gsd:plan-phase 3`
先运行 /clear。
```
没有解释原因。用户可能跳过。
### 不要："其他选项" 措辞
```
其他选项：
- 审查路线图
```
听起来像是事后补充。用"也可选："替代。
### 不要：用围栏代码块展示命令
```
```
/gsd:plan-phase 3
```
```
模板内的围栏代码块会造成嵌套歧义。用内联反引号替代。

65
docs/zh-CN/references/decimal-phase-calculation.md Normal file
View File

@@ -0,0 +1,65 @@
# 小数阶段计算
为紧急插入计算下一个小数阶段编号。
## 使用 gsd-tools
```bash
# 获取阶段 6 之后的下一个小数阶段
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 6
```
输出：
```json
{
"found": true,
"base_phase": "06",
"next": "06.1",
"existing": []
}
```
已有小数时：
```json
{
"found": true,
"base_phase": "06",
"next": "06.3",
"existing": ["06.1", "06.2"]
}
```
## 提取值
```bash
DECIMAL_INFO=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}")
DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next')
BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase')
```
或使用 --raw 标志：
```bash
DECIMAL_PHASE=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
# 返回: 06.1
```
## 示例
| 已有阶段 | 下一个阶段 |
|----------|------------|
| 仅 06 | 06.1 |
| 06, 06.1 | 06.2 |
| 06, 06.1, 06.2 | 06.3 |
| 06, 06.1, 06.3（有空缺）| 06.4 |
## 目录命名
小数阶段目录使用完整的小数编号：
```bash
SLUG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" generate-slug "$DESCRIPTION" --raw)
PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
mkdir -p "$PHASE_DIR"
```
示例：`.planning/phases/06.1-fix-critical-auth-bug/`

248
docs/zh-CN/references/git-integration.md Normal file
View File

@@ -0,0 +1,248 @@
<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>

38
docs/zh-CN/references/git-planning-commit.md Normal file
View File

@@ -0,0 +1,38 @@
# Git 规划提交
使用 gsd-tools CLI 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态。
## 通过 CLI 提交
始终使用 `gsd-tools.cjs commit` 处理 `.planning/` 文件 — 它会自动处理 `commit_docs` 和 gitignore 检查：
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
```
如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（带原因）。无需手动条件检查。
## 修改上次提交
将 `.planning/` 文件变更合并到上次提交：
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
```
## 提交消息模式
| 命令 | 范围 | 示例 |
|------|------|------|
| plan-phase | phase | `docs(phase-03): create authentication plans` |
| execute-phase | phase | `docs(phase-03): complete authentication phase` |
| new-milestone | milestone | `docs: start milestone v1.1` |
| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
| add-phase | phase | `docs: add phase 07 (settings page)` |
## 何时跳过
- config 中 `commit_docs: false`
- `.planning/` 被 gitignore
- 无变更可提交（用 `git status --porcelain .planning/` 检查）

34
docs/zh-CN/references/model-profile-resolution.md Normal file
View File

@@ -0,0 +1,34 @@
# 模型配置解析
在编排开始时解析一次模型配置，然后在所有 Task 生成时使用。
## 解析模式
```bash
MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
```
默认值：未设置或缺少 config 时为 `balanced`。
## 查找表
@~/.claude/get-shit-done/references/model-profiles.md
在表中查找已解析配置对应的代理。将 model 参数传递给 Task 调用：
```
Task(
prompt="...",
subagent_type="gsd-planner",
model="{resolved_model}" # "inherit"、"sonnet" 或 "haiku"
)
```
**注意：** Opus 级代理解析为 `"inherit"`（而非 `"opus"`）。这会使代理使用父会话的模型，避免与可能阻止特定 opus 版本的组织策略冲突。
## 使用方法
1. 在编排开始时解析一次
2. 存储 profile 值
3. 生成时在表中查找每个代理的模型
4. 将 model 参数传递给每个 Task 调用（值：`"inherit"`、`"sonnet"`、`"haiku"`）

93
docs/zh-CN/references/model-profiles.md Normal file
View File

@@ -0,0 +1,93 @@
# 模型配置
模型配置控制每个 GSD 代理使用哪个 Claude 模型。这允许平衡质量和 token 消耗。
## 配置定义
| 代理 | `quality` | `balanced` | `budget` |
|-------|-----------|------------|----------|
| gsd-planner | opus | opus | sonnet |
| gsd-roadmapper | opus | sonnet | sonnet |
| gsd-executor | opus | sonnet | sonnet |
| gsd-phase-researcher | opus | sonnet | haiku |
| gsd-project-researcher | opus | sonnet | haiku |
| gsd-research-synthesizer | sonnet | sonnet | haiku |
| gsd-debugger | opus | sonnet | sonnet |
| gsd-codebase-mapper | sonnet | haiku | haiku |
| gsd-verifier | sonnet | sonnet | haiku |
| gsd-plan-checker | sonnet | sonnet | haiku |
| gsd-integration-checker | sonnet | sonnet | haiku |
| gsd-nyquist-auditor | sonnet | sonnet | haiku |
## 配置理念
**quality** - 最大推理能力
- 所有决策代理使用 Opus
- 只读验证使用 Sonnet
- 适用场景：有配额可用、关键架构工作
**balanced**（默认）- 智能分配
- 仅规划（架构决策发生的地方）使用 Opus
- 执行和研究使用 Sonnet（遵循明确指令）
- 验证使用 Sonnet（需要推理，不仅仅是模式匹配）
- 适用场景：正常开发、质量与成本的良好平衡
**budget** - 最小化 Opus 使用
- 编写代码的使用 Sonnet
- 研究和验证使用 Haiku
- 适用场景：节省配额、大量工作、不太关键的阶段
## 解析逻辑
编排器在生成代理前解析模型：
```
1. 读取 .planning/config.json
2. 检查 model_overrides 是否有代理特定覆盖
3. 如果没有覆盖，在配置表中查找代理
4. 将 model 参数传递给 Task 调用
```
## 单代理覆盖
覆盖特定代理而不更改整个配置：
```json
{
"model_profile": "balanced",
"model_overrides": {
"gsd-executor": "opus",
"gsd-planner": "haiku"
}
}
```
覆盖优先于配置。有效值：`opus`、`sonnet`、`haiku`。
## 切换配置
运行时：`/gsd:set-profile <profile>`
项目默认值：在 `.planning/config.json` 中设置：
```json
{
"model_profile": "balanced"
}
```
## 设计理由
**为什么 gsd-planner 使用 Opus？**
规划涉及架构决策、目标分解和任务设计。这是模型质量影响最大的地方。
**为什么 gsd-executor 使用 Sonnet？**
执行者遵循明确的 PLAN.md 指令。计划已包含推理；执行只是实现。
**为什么 balanced 中验证器使用 Sonnet（而非 Haiku）？**
验证需要目标回溯推理 —— 检查代码是否**交付**了阶段承诺的内容，而不仅仅是模式匹配。Sonnet 处理得很好；Haiku 可能会遗漏细微的差距。
**为什么 gsd-codebase-mapper 使用 Haiku？**
只读探索和模式提取。不需要推理，只需从文件内容输出结构化结果。
**为什么用 `inherit` 而不是直接传递 `opus`？**
Claude Code 的 `"opus"` 别名映射到特定模型版本。组织可能阻止旧版 opus 而允许新版。GSD 为 opus 级代理返回 `"inherit"`，使其使用用户在会话中配置的任何 opus 版本。这避免了版本冲突和静默回退到 Sonnet。

61
docs/zh-CN/references/phase-argument-parsing.md Normal file
View File

@@ -0,0 +1,61 @@
# 阶段参数解析
为操作阶段的命令解析和规范化阶段参数。
## 提取
从 `$ARGUMENTS` 中：
- 提取阶段编号（第一个数字参数）
- 提取标志（以 `--` 为前缀）
- 剩余文本为描述（用于 insert/add 命令）
## 使用 gsd-tools
`find-phase` 命令一步完成规范化和验证：
```bash
PHASE_INFO=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" find-phase "${PHASE}")
```
返回 JSON 包含：
- `found`: true/false
- `directory`: 阶段目录的完整路径
- `phase_number`: 规范化的编号（如 "06"、"06.1"）
- `phase_name`: 名称部分（如 "foundation"）
- `plans`: PLAN.md 文件数组
- `summaries`: SUMMARY.md 文件数组
## 手动规范化（遗留）
将整数阶段补零到 2 位。保留小数后缀。
```bash
# 规范化阶段编号
if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
# 整数: 8 → 08
PHASE=$(printf "%02d" "$PHASE")
elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
# 小数: 2.1 → 02.1
PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
fi
```
## 验证
使用 `roadmap get-phase` 验证阶段存在：
```bash
PHASE_CHECK=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}")
if [ "$(printf '%s\n' "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
echo "ERROR: Phase ${PHASE} not found in roadmap"
exit 1
fi
```
## 目录查找
使用 `find-phase` 进行目录查找：
```bash
PHASE_DIR=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" find-phase "${PHASE}" --raw)
```

200
docs/zh-CN/references/planning-config.md Normal file
View File

@@ -0,0 +1,200 @@
<planning_config>
`.planning/` 目录行为的配置选项。
<config_schema>
```json
"planning": {
"commit_docs": true,
"search_gitignored": false
},
"git": {
"branching_strategy": "none",
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}"
}
```
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `commit_docs` | `true` | 是否将规划工件提交到 git |
| `search_gitignored` | `false` | 在广泛 rg 搜索中添加 `--no-ignore` |
| `git.branching_strategy` | `"none"` | Git 分支策略：`"none"`、`"phase"` 或 `"milestone"` |
| `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | 阶段策略的分支模板 |
| `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | 里程碑策略的分支模板 |
</config_schema>
<commit_docs_behavior>
**当 `commit_docs: true`（默认）：**
- 规划文件正常提交
- SUMMARY.md、STATE.md、ROADMAP.md 在 git 中跟踪
- 规划决策的完整历史保留
**当 `commit_docs: false`：**
- 跳过 `.planning/` 文件的所有 `git add`/`git commit`
- 用户必须将 `.planning/` 添加到 `.gitignore`
- 适用于：OSS 贡献、客户项目、保持规划私有
**使用 gsd-tools.cjs（推荐）：**
```bash
# 提交时自动检查 commit_docs + gitignore：
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
# 通过 state load 加载配置（返回 JSON）：
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# commit_docs 在 JSON 输出中可用
# 或使用包含 commit_docs 的 init 命令：
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# commit_docs 包含在所有 init 命令输出中
```
**自动检测：** 如果 `.planning/` 被 gitignore，无论 config.json 如何，`commit_docs` 自动为 `false`。这防止用户在 `.gitignore` 中有 `.planning/` 时出现 git 错误。
**通过 CLI 提交（自动处理检查）：**
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
```
CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。
</commit_docs_behavior>
<search_behavior>
**当 `search_gitignored: false`（默认）：**
- 标准 rg 行为（尊重 .gitignore）
- 直接路径搜索有效：`rg "pattern" .planning/` 找到文件
- 广泛搜索跳过 gitignored：`rg "pattern"` 跳过 `.planning/`
**当 `search_gitignored: true`:**
- 在应该包含 `.planning/` 的广泛 rg 搜索中添加 `--no-ignore`
- 仅在搜索整个仓库并期望 `.planning/` 匹配时需要
**注意：** 大多数 GSD 操作使用直接文件读取或显式路径，无论 gitignore 状态如何都有效。
</search_behavior>
<setup_uncommitted_mode>
使用未提交模式：
1. **设置配置：**
```json
"planning": {
"commit_docs": false,
"search_gitignored": true
}
```
2. **添加到 .gitignore：**
```
.planning/
```
3. **已存在的跟踪文件：** 如果 `.planning/` 之前被跟踪：
```bash
git rm -r --cached .planning/
git commit -m "chore: stop tracking planning docs"
```
4. **分支合并：** 当使用 `branching_strategy: phase` 或 `milestone` 时，`complete-milestone` 工作流在 `commit_docs: false` 时自动从暂存区移除 `.planning/` 文件，然后才进行合并提交。
</setup_uncommitted_mode>
<branching_strategy_behavior>
**分支策略：**
| 策略 | 创建分支时机 | 分支范围 | 合并点 |
|----------|---------------------|--------------|-------------|
| `none` | 从不 | N/A | N/A |
| `phase` | `execute-phase` 开始时 | 单个阶段 | 阶段后用户手动合并 |
| `milestone` | 里程碑第一个 `execute-phase` | 整个里程碑 | `complete-milestone` 时 |
**当 `git.branching_strategy: "none"`（默认）：**
- 所有工作提交到当前分支
- 标准 GSD 行为
**当 `git.branching_strategy: "phase"`：**
- `execute-phase` 在执行前创建/切换到分支
- 分支名来自 `phase_branch_template`（如 `gsd/phase-03-authentication`）
- 所有计划提交到该分支
- 阶段完成后用户手动合并分支
- `complete-milestone` 提供合并所有阶段分支的选项
**当 `git.branching_strategy: "milestone"`：**
- 里程碑的第一个 `execute-phase` 创建里程碑分支
- 分支名来自 `milestone_branch_template`（如 `gsd/v1.0-mvp`）
- 里程碑中所有阶段提交到同一分支
- `complete-milestone` 提供将里程碑分支合并到 main 的选项
**模板变量：**
| 变量 | 可用于 | 描述 |
|----------|--------------|-------------|
| `{phase}` | phase_branch_template | 零填充阶段号（如 "03"） |
| `{slug}` | 两者 | 小写、连字符名称 |
| `{milestone}` | milestone_branch_template | 里程碑版本（如 "v1.0"） |
**检查配置：**
使用 `init execute-phase` 返回所有配置为 JSON：
```bash
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# JSON 输出包含：branching_strategy, phase_branch_template, milestone_branch_template
```
或使用 `state load` 获取配置值：
```bash
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template
```
**分支创建：**
```bash
# 阶段策略
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
fi
# 里程碑策略
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
fi
```
**complete-milestone 时的合并选项：**
| 选项 | Git 命令 | 结果 |
|--------|-------------|--------|
| Squash 合并（推荐） | `git merge --squash` | 每个分支单个干净提交 |
| 带历史合并 | `git merge --no-ff` | 保留所有单独提交 |
| 不合并直接删除 | `git branch -D` | 丢弃分支工作 |
| 保留分支 | （无） | 后续手动处理 |
推荐 Squash 合并 —— 保持 main 分支历史干净，同时在分支中保留完整开发历史（直到删除）。
**使用场景：**
| 策略 | 最适合 |
|----------|----------|
| `none` | 独立开发、简单项目 |
| `phase` | 每阶段代码审查、细粒度回滚、团队协作 |
| `milestone` | 发布分支、预发布环境、每个版本一个 PR |
</branching_strategy_behavior>
</planning_config>

142
docs/zh-CN/references/questioning.md Normal file
View File

@@ -0,0 +1,142 @@
# 提问指南
项目初始化是梦想提取，而非需求收集。你在帮助用户发现和表达他们想构建的内容。这不是合同谈判 —— 是协作思考。
## 理念
**你是思考伙伴，不是面试官。**
用户通常有一个模糊的想法。你的工作是帮助他们将其锐化。问一些让他们思考"哦，我没想到那个"或"是的，这正是我的意思"的问题。
不要审问。协作。不要照本宣科。顺藤摸瓜。
## 目标
到提问结束时，你需要足够的清晰度来编写下游阶段可执行的 PROJECT.md：
- **研究** 需要：研究什么领域、用户已知什么、存在哪些未知
- **需求** 需要：足够清晰的愿景来界定 v1 功能
- **路线图** 需要：足够清晰的愿景来分解为阶段、"完成"是什么样子
- **plan-phase** 需要：可分解为任务的具体需求、实现选择的上下文
- **execute-phase** 需要：可验证的成功标准、需求背后的"为什么"
模糊的 PROJECT.md 会让每个下游阶段都在猜测。成本会叠加。
## 如何提问
**开放开始。** 让他们倾倒心理模型。不要用结构打断。
**跟随能量。** 无论他们强调什么，深入那个。什么让他们兴奋？什么问题引发了这一切？
**挑战模糊。** 绝不接受模糊回答。"好"意味着什么？"用户"指谁？"简单"是怎么简单？
**让抽象具体。**"带我走一遍使用这个。""那实际看起来是什么样？"
**澄清歧义。**"你说 Z 时，是指 A 还是 B？""你提到了 X —— 跟我多说说。"
**知道何时停止。** 当你理解他们想要什么、为什么想要、给谁用、完成是什么样 —— 提议继续。
## 问题类型
以此作为灵感，不是清单。选择与话题相关的。
**动机 —— 为什么存在：**
- "什么引发了这一切？"
- "你今天在做什么会被这个替代？"
- "如果这个存在，你会做什么？"
**具体性 —— 它实际是什么：**
- "带我走一遍使用这个"
- "你说 X —— 那实际看起来是什么样？"
- "给我一个例子"
**澄清 —— 他们什么意思：**
- "你说 Z 时，是指 A 还是 B？"
- "你提到了 X —— 跟我多说说那个"
**成功 —— 你怎么知道它在工作：**
- "你怎么知道这个在工作？"
- "完成是什么样子？"
## 使用 AskUserQuestion
用 AskUserQuestion 帮助用户思考，通过呈现具体的选项供他们反应。
**好选项：**
- 他们可能意思的解读
- 确认或否认的具体例子
- 揭示优先级的具体选择
**坏选项：**
- 泛泛的类别（"技术"、"业务"、"其他"）
- 预设答案的引导性选项
- 选项太多（2-4 个理想）
- 超过 12 个字符的标题（硬限制 —— 验证会拒绝）
**示例 —— 模糊回答：**
用户说"它应该快"
- header: "快"
- question: "快是指？"
- options: ["亚秒响应", "处理大数据集", "快速构建", "让我解释"]
**示例 —— 跟随话题：**
用户提到"对当前工具感到沮丧"
- header: "沮丧"
- question: "具体什么让你沮丧？"
- options: ["点击太多", "缺少功能", "不可靠", "让我解释"]
**给用户的提示 —— 修改选项：**
想要稍微修改某个选项版本的用户可以选择"Other"并通过编号引用选项：`#1 但仅用于指关节` 或 `#2 禁用分页`。这避免重新输入完整选项文本。
## 自由格式规则
**当用户想自由解释时，停止使用 AskUserQuestion。**
如果用户选择"Other"且他们的回应表明他们想用自己的话描述（如"让我描述一下"、"我来解释"、"别的"、或任何非选择/修改现有选项的开放式回复），你必须：
1. **用纯文本问你的追问** — 不通过 AskUserQuestion
2. **等待他们在正常提示符下输入**
3. **仅在处理他们的自由格式回应后恢复 AskUserQuestion**
同样适用于如果你包含一个表明自由格式的选项（如"让我解释"或"详细描述"）且用户选择了它。
**错误：** 用户说"让我描述一下" → AskUserQuestion("什么功能？", ["功能 A", "功能 B", "详细描述"])
**正确：** 用户说"让我描述一下" → "请讲 —— 你在想什么？"
## 上下文清单
以此作为**背景清单**，而非对话结构。进行时在脑中检查这些。如果还有缺口，自然地穿插问题。
- [ ] 他们在构建什么（足够具体可以向陌生人解释）
- [ ] 为什么它需要存在（驱动它的问题或渴望）
- [ ] 给谁用的（即使只是他们自己）
- [ ] "完成"是什么样子（可观察的结果）
四件事。如果他们主动提供更多，捕获它。
## 决策门控
当你能写出清晰的 PROJECT.md 时，提议继续：
- header: "准备好了？"
- question: "我想我理解你想要什么了。准备创建 PROJECT.md 吗？"
- options:
- "创建 PROJECT.md" — 让我们继续
- "继续探索" — 我想分享更多 / 再问我
如果"继续探索" —— 问他们想添加什么或识别缺口并自然探查。
循环直到选择"创建 PROJECT.md"。
## 反模式
- **走清单** — 不管他们说什么都按领域走
- **套话问题** — "你的核心价值是什么？""什么超出范围？"不管上下文
- **企业腔** — "你的成功标准是什么？""你的利益相关者是谁？"
- **审问** — 不基于回答构建就连续发问
- **急于求成** — 最小化问题以开始"实际工作"
- **浅层接受** — 不探查就接受模糊回答
- **过早约束** — 还不理解想法就问技术栈
- **用户技能** — 绝不问用户的技术经验。Claude 来构建。

263
docs/zh-CN/references/tdd.md Normal file
View File

@@ -0,0 +1,263 @@
<overview>
TDD 关乎设计质量，而非覆盖率指标。红-绿-重构循环迫使你在实现前思考行为，从而产生更清晰的接口和更可测试的代码。
**原则：** 如果在编写 `fn` 之前能用 `expect(fn(input)).toBe(output)` 描述行为，TDD 会改善结果。
**关键洞察：** TDD 工作本质上比标准任务更重 —— 它需要 2-3 个执行周期（RED → GREEN → REFACTOR），每个周期都涉及文件读取、测试运行和可能的调试。TDD 功能获得专门的计划，以确保整个周期内有完整的上下文可用。
</overview>
<when_to_use_tdd>
## 何时 TDD 提高质量
**TDD 候选（创建 TDD 计划）：**
- 有明确输入/输出的业务逻辑
- 有请求/响应契约的 API 端点
- 数据转换、解析、格式化
- 验证规则和约束
- 有可测试行为的算法
- 状态机和工作流
- 有清晰规格的工具函数
**跳过 TDD（使用带 `type="auto"` 任务的标准计划）：**
- UI 布局、样式、视觉组件
- 配置更改
- 连接现有组件的胶水代码
- 一次性脚本和迁移
- 无业务逻辑的简单 CRUD
- 探索性原型
**启发式：** 能在编写 `fn` 之前写 `expect(fn(input)).toBe(output)` 吗？
→ 能：创建 TDD 计划
→ 不能：使用标准计划，事后添加测试（如需要）
</when_to_use_tdd>
<tdd_plan_structure>
## TDD 计划结构
每个 TDD 计划通过完整的 RED-GREEN-REFACTOR 循环实现**一个功能**。
```markdown
---
phase: XX-name
plan: NN
type: tdd
---
<objective>
[什么功能以及为什么]
Purpose: [该功能 TDD 的设计收益]
Output: [可工作的、已测试的功能]
</objective>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@relevant/source/files.ts
</context>
<feature>
<name>[功能名称]</name>
<files>[源文件, 测试文件]</files>
<behavior>
[可测试术语描述的预期行为]
Cases: 输入 → 预期输出
</behavior>
<implementation>[测试通过后如何实现]</implementation>
</feature>
<verification>
[证明功能有效的测试命令]
</verification>
<success_criteria>
- 失败测试已编写并提交
- 实现通过测试
- 重构完成（如需要）
- 所有 2-3 个提交都存在
</success_criteria>
<output>
完成后，创建包含以下内容的 SUMMARY.md：
- RED: 编写了什么测试，为什么失败
- GREEN: 什么实现让它通过
- REFACTOR: 做了什么清理（如有）
- Commits: 生成的提交列表
</output>
```
**每个 TDD 计划一个功能。** 如果功能足够简单可以批量处理，那就足够简单可以跳过 TDD —— 使用标准计划，事后添加测试。
</tdd_plan_structure>
<execution_flow>
## 红-绿-重构循环
**RED - 编写失败测试：**
1. 按项目约定创建测试文件
2. 编写描述预期行为的测试（来自 `<behavior>` 元素）
3. 运行测试 - 必须**失败**
4. 如果测试通过：功能已存在或测试有误。调查。
5. 提交：`test({phase}-{plan}): add failing test for [feature]`
**GREEN - 实现使其通过：**
1. 编写使测试通过的最小代码
2. 不耍小聪明，不优化 - 只让它工作
3. 运行测试 - 必须**通过**
4. 提交：`feat({phase}-{plan}): implement [feature]`
**REFACTOR（如需要）：**
1. 如果存在明显的改进，清理实现
2. 运行测试 - 必须**仍然通过**
3. 仅在做出更改时提交：`refactor({phase}-{plan}): clean up [feature]`
**结果：** 每个 TDD 计划产生 2-3 个原子提交。
</execution_flow>
<test_quality>
## 好测试 vs 坏测试
**测试行为，而非实现：**
- 好："返回格式化的日期字符串"
- 坏："用正确参数调用 formatDate 辅助函数"
- 测试应该能经受重构
**每个测试一个概念：**
- 好：分别为有效输入、空输入、畸形输入编写测试
- 坏：用多个断言检查所有边缘情况的单个测试
**描述性名称：**
- 好："should reject empty email"、"returns null for invalid ID"
- 坏："test1"、"handles error"、"works correctly"
**不包含实现细节：**
- 好：测试公共 API、可观察行为
- 坏：Mock 内部实现、测试私有方法、断言内部状态
</test_quality>
<framework_setup>
## 测试框架设置（如不存在）
当执行 TDD 计划但没有配置测试框架时，作为 RED 阶段的一部分进行设置：
**1. 检测项目类型：**
```bash
# JavaScript/TypeScript
if [ -f package.json ]; then echo "node"; fi
# Python
if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
# Go
if [ -f go.mod ]; then echo "go"; fi
# Rust
if [ -f Cargo.toml ]; then echo "rust"; fi
```
**2. 安装最小框架：**
| 项目 | 框架 | 安装 |
|---------|-----------|---------|
| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
| Node.js (Vite) | Vitest | `npm install -D vitest` |
| Python | pytest | `pip install pytest` |
| Go | testing | 内置 |
| Rust | cargo test | 内置 |
**3. 按需创建配置：**
- Jest: 带 ts-jest preset 的 `jest.config.js`
- Vitest: 带测试全局变量的 `vitest.config.ts`
- pytest: `pytest.ini` 或 `pyproject.toml` 部分
**4. 验证设置：**
```bash
# 运行空测试套件 - 应该以 0 个测试通过
npm test # Node
pytest # Python
go test ./... # Go
cargo test # Rust
```
**5. 创建第一个测试文件：**
遵循项目约定的测试位置：
- 源文件旁边的 `*.test.ts` / `*.spec.ts`
- `__tests__/` 目录
- 根目录的 `tests/` 目录
框架设置是第一个 TDD 计划 RED 阶段的一次性成本。
</framework_setup>
<error_handling>
## 错误处理
**测试在 RED 阶段没有失败：**
- 功能可能已存在 - 调查
- 测试可能有误（没测试你以为的东西）
- 前进前修复
**测试在 GREEN 阶段没有通过：**
- 调试实现
- 不要跳到重构
- 持续迭代直到绿色
**测试在 REFACTOR 阶段失败：**
- 撤销重构
- 提交过早
- 用更小的步骤重构
**不相关的测试失败：**
- 停下来调查
- 可能表明耦合问题
- 前进前修复
</error_handling>
<commit_pattern>
## TDD 计划的提交模式
TDD 计划产生 2-3 个原子提交（每个阶段一个）：
```
test(08-02): add failing test for email validation
- Tests valid email formats accepted
- Tests invalid formats rejected
- Tests empty input handling
feat(08-02): implement email validation
- Regex pattern matches RFC 5322
- Returns boolean for validity
- Handles edge cases (empty, null)
refactor(08-02): extract regex to constant (optional)
- Moved pattern to EMAIL_REGEX constant
- No behavior changes
- Tests still pass
```
**与标准计划对比：**
- 标准计划：每个任务 1 个提交，每个计划 2-4 个提交
- TDD 计划：单个功能 2-3 个提交
两者遵循相同格式：`{type}({phase}-{plan}): {description}`
**好处：**
- 每个提交独立可回滚
- Git bisect 在提交级别工作
- 显示 TDD 纪律的清晰历史
- 与整体提交策略一致
</commit_pattern>
<context_budget>
## 上下文预算
TDD 计划目标 **~40% 上下文使用率**（低于标准计划的 ~50%）。
为什么更低：
- RED 阶段：编写测试、运行测试、可能调试为什么没有失败
- GREEN 阶段：实现、运行测试、可能对失败进行迭代
- REFACTOR 阶段：修改代码、运行测试、验证无回归
每个阶段涉及读取文件、运行命令、分析输出。来回往复本质上比线性任务执行更重。
单一功能聚焦确保整个周期保持完整质量。
</context_budget>

158
docs/zh-CN/references/ui-brand.md Normal file
View File

@@ -0,0 +1,158 @@
# UI 品牌规范
面向用户的 GSD 输出的视觉模式。编排器通过 @ 引用此文件。
## 阶段横幅
用于主要工作流过渡。
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► {阶段名称}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**阶段名称（大写）：**
- `QUESTIONING`（提问）
- `RESEARCHING`（研究）
- `DEFINING REQUIREMENTS`（定义需求）
- `CREATING ROADMAP`（创建路线图）
- `PLANNING PHASE {N}`（规划阶段 {N}）
- `EXECUTING WAVE {N}`（执行波次 {N}）
- `VERIFYING`（验证）
- `PHASE {N} COMPLETE ✓`（阶段 {N} 完成）
- `MILESTONE COMPLETE 🎉`（里程碑完成）
---
## 检查点框
需要用户操作。62 字符宽度。
```
╔══════════════════════════════════════════════════════════════╗
║ CHECKPOINT: {类型} ║
╚══════════════════════════════════════════════════════════════╝
{内容}
──────────────────────────────────────────────────────────────
→ {操作提示}
──────────────────────────────────────────────────────────────
```
**类型：**
- `CHECKPOINT: 需要验证` → `→ 输入 "approved" 或描述问题`
- `CHECKPOINT: 需要决策` → `→ 选择: option-a / option-b`
- `CHECKPOINT: 需要操作` → `→ 完成后输入 "done"`
---
## 状态符号
```
✓ 完成 / 通过 / 已验证
✗ 失败 / 缺失 / 阻塞
◆ 进行中
○ 待处理
⚡ 自动批准
⚠ 警告
🎉 里程碑完成（仅在横幅中）
```
---
## 进度显示
**阶段/里程碑级别：**
```
进度: ████████░░ 80%
```
**任务级别：**
```
任务: 2/4 完成
```
**计划级别：**
```
计划: 3/5 完成
```
---
## 生成指示器
```
◆ 正在生成研究员...
◆ 并行生成 4 个研究员...
→ 技术栈研究
→ 功能研究
→ 架构研究
→ 陷阱研究
✓ 研究员完成: STACK.md 已写入
```
---
## 下一步区块
始终在主要完成后。
```
───────────────────────────────────────────────────────────────
## ▶ 下一步
**{标识符}: {名称}** — {单行描述}
`{可复制粘贴的命令}`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
───────────────────────────────────────────────────────────────
**也可选：**
- `/gsd:alternative-1` — 描述
- `/gsd:alternative-2` — 描述
───────────────────────────────────────────────────────────────
```
---
## 错误框
```
╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
{错误描述}
**修复方法:** {解决步骤}
```
---
## 表格
```
| 阶段 | 状态 | 计划 | 进度 |
|------|------|------|------|
| 1 | ✓ | 3/3 | 100% |
| 2 | ◆ | 1/4 | 25% |
| 3 | ○ | 0/2 | 0% |
```
---
## 反模式
- 变化的框/横幅宽度
- 混合横幅样式（`===`、`---`、`***`）
- 横幅中缺少 `GSD ►` 前缀
- 随机 emoji（`🚀`、`✨`、`💫`）
- 完成后缺少下一步区块

612
docs/zh-CN/references/verification-patterns.md Normal file
View File

@@ -0,0 +1,612 @@
# 验证模式
如何验证不同类型的工件是真实实现，而非存根或占位符。
<core_principle>
**存在 ≠ 实现**
文件存在并不意味着功能有效。验证必须检查：
1. **存在** - 文件在预期路径
2. **实质性** - 内容是真实实现，非占位符
3. **已连接** - 已连接到系统的其他部分
4. **功能性** - 调用时实际工作
级别 1-3 可以编程检查。级别 4 通常需要人工验证。
</core_principle>
<stub_detection>
## 通用存根模式
这些模式表明占位符代码，无论文件类型：
**基于注释的存根：**
```bash
# 存根注释的 Grep 模式
grep -E "(TODO|FIXME|XXX|HACK|PLACEHOLDER)" "$file"
grep -E "implement|add later|coming soon|will be" "$file" -i
grep -E "// \.\.\.|/\* \.\.\. \*/|# \.\.\." "$file"
```
**输出中的占位符文本：**
```bash
# UI 占位符模式
grep -E "placeholder|lorem ipsum|coming soon|under construction" "$file" -i
grep -E "sample|example|test data|dummy" "$file" -i
grep -E "\[.*\]|<.*>|\{.*\}" "$file" # 模板括号未移除
```
**空或琐碎实现：**
```bash
# 什么都不做的函数
grep -E "return null|return undefined|return \{\}|return \[\]" "$file"
grep -E "pass$|\.\.\.|\bnothing\b" "$file"
grep -E "console\.(log|warn|error).*only" "$file" # 仅日志函数
```
**预期动态但硬编码的值：**
```bash
# 硬编码 ID、计数或内容
grep -E "id.*=.*['\"].*['\"]" "$file" # 硬编码字符串 ID
grep -E "count.*=.*\d+|length.*=.*\d+" "$file" # 硬编码计数
grep -E "\\\$\d+\.\d{2}|\d+ items" "$file" # 硬编码显示值
```
</stub_detection>
<react_components>
## React/Next.js 组件
**存在检查：**
```bash
# 文件存在且导出组件
[ -f "$component_path" ] && grep -E "export (default |)function|export const.*=.*\(" "$component_path"
```
**实质性检查：**
```bash
# 返回实际 JSX，非占位符
grep -E "return.*<" "$component_path" | grep -v "return.*null" | grep -v "placeholder" -i
# 有有意义的内容（不仅仅是包装 div）
grep -E "<[A-Z][a-zA-Z]+|className=|onClick=|onChange=" "$component_path"
# 使用 props 或 state（非静态）
grep -E "props\.|useState|useEffect|useContext|\{.*\}" "$component_path"
```
**React 特有的存根模式：**
```javascript
// 危险信号 - 这些是存根：
return <div>Component</div>
return <div>Placeholder</div>
return <div>{/* TODO */}</div>
return <p>Coming soon</p>
return null
return <></>
// 也是存根 - 空处理器：
onClick={() => {}}
onChange={() => console.log('clicked')}
onSubmit={(e) => e.preventDefault()} // 仅阻止默认，什么都不做
```
**连接检查：**
```bash
# 组件导入它需要的东西
grep -E "^import.*from" "$component_path"
# Props 实际被使用（不仅仅是接收）
# 查找解构或 props.X 用法
grep -E "\{ .* \}.*props|\bprops\.[a-zA-Z]+" "$component_path"
# API 调用存在（对于数据获取组件）
grep -E "fetch\(|axios\.|useSWR|useQuery|getServerSideProps|getStaticProps" "$component_path"
```
**功能验证（需要人工）：**
- 组件是否渲染可见内容？
- 交互元素是否响应点击？
- 数据是否加载并显示？
- 错误状态是否适当显示？
</react_components>
<api_routes>
## API 路由（Next.js App Router / Express 等）
**存在检查：**
```bash
# 路由文件存在
[ -f "$route_path" ]
# 导出 HTTP 方法处理器（Next.js App Router）
grep -E "export (async )?(function|const) (GET|POST|PUT|PATCH|DELETE)" "$route_path"
# 或 Express 风格处理器
grep -E "\.(get|post|put|patch|delete)\(" "$route_path"
```
**实质性检查：**
```bash
# 有实际逻辑，不仅仅是 return 语句
wc -l "$route_path" # 超过 10-15 行表明真实实现
# 与数据源交互
grep -E "prisma\.|db\.|mongoose\.|sql|query|find|create|update|delete" "$route_path" -i
# 有错误处理
grep -E "try|catch|throw|error|Error" "$route_path"
# 返回有意义的响应
grep -E "Response\.json|res\.json|res\.send|return.*\{" "$route_path" | grep -v "message.*not implemented" -i
```
**API 路由特有的存根模式：**
```typescript
// 危险信号 - 这些是存根：
export async function POST() {
return Response.json({ message: "Not implemented" })
}
export async function GET() {
return Response.json([]) // 空 array 无数据库查询
}
export async function PUT() {
return new Response() // 空响应
}
// 仅控制台日志：
export async function POST(req) {
console.log(await req.json())
return Response.json({ ok: true })
}
```
**连接检查：**
```bash
# 导入数据库/服务客户端
grep -E "^import.*prisma|^import.*db|^import.*client" "$route_path"
# 实际使用请求体（对于 POST/PUT）
grep -E "req\.json\(\)|req\.body|request\.json\(\)" "$route_path"
# 验证输入（不仅仅信任请求）
grep -E "schema\.parse|validate|zod|yup|joi" "$route_path"
```
**功能验证（人工或自动化）：**
- GET 是否从数据库返回真实数据？
- POST 是否实际创建记录？
- 错误响应是否有正确的状态码？
- 认证检查是否实际执行？
</api_routes>
<database_schema>
## 数据库模式（Prisma / Drizzle / SQL）
**存在检查：**
```bash
# 模式文件存在
[ -f "prisma/schema.prisma" ] || [ -f "drizzle/schema.ts" ] || [ -f "src/db/schema.sql" ]
# 模型/表已定义
grep -E "^model $model_name|CREATE TABLE $table_name|export const $table_name" "$schema_path"
```
**实质性检查：**
```bash
# 有预期字段（不仅仅是 id）
grep -A 20 "model $model_name" "$schema_path" | grep -E "^\s+\w+\s+\w+"
# 有预期关系
grep -E "@relation|REFERENCES|FOREIGN KEY" "$schema_path"
# 有适当的字段类型（不全是 String）
grep -A 20 "model $model_name" "$schema_path" | grep -E "Int|DateTime|Boolean|Float|Decimal|Json"
```
**模式特有的存根模式：**
```prisma
// 危险信号 - 这些是存根：
model User {
id String @id
// TODO: add fields
}
model Message {
id String @id
content String // 只有一个真实字段
}
// 缺少关键字段：
model Order {
id String @id
// 缺少: userId, items, total, status, createdAt
}
```
**连接检查：**
```bash
# 迁移存在且已应用
ls prisma/migrations/ 2>/dev/null | wc -l # 应该 > 0
npx prisma migrate status 2>/dev/null | grep -v "pending"
# 客户端已生成
[ -d "node_modules/.prisma/client" ]
```
**功能验证：**
```bash
# 可以查询表（自动化）
npx prisma db execute --stdin <<< "SELECT COUNT(*) FROM $table_name"
```
</database_schema>
<hooks_utilities>
## 自定义 Hooks 和工具
**存在检查：**
```bash
# 文件存在且导出函数
[ -f "$hook_path" ] && grep -E "export (default )?(function|const)" "$hook_path"
```
**实质性检查：**
```bash
# Hook 使用 React hooks（对于自定义 hooks）
grep -E "useState|useEffect|useCallback|useMemo|useRef|useContext" "$hook_path"
# 有有意义的返回值
grep -E "return \{|return \[" "$hook_path"
# 超过琐碎长度
[ $(wc -l < "$hook_path") -gt 10 ]
```
**Hooks 特有的存根模式：**
```typescript
// 危险信号 - 这些是存根：
export function useAuth() {
return { user: null, login: () => {}, logout: () => {} }
}
export function useCart() {
const [items, setItems] = useState([])
return { items, addItem: () => console.log('add'), removeItem: () => {} }
}
// 硬编码返回：
export function useUser() {
return { name: "Test User", email: "test@example.com" }
}
```
**连接检查：**
```bash
# Hook 实际在某处被导入
grep -r "import.*$hook_name" src/ --include="*.tsx" --include="*.ts" | grep -v "$hook_path"
# Hook 实际被调用
grep -r "$hook_name()" src/ --include="*.tsx" --include="*.ts" | grep -v "$hook_path"
```
</hooks_utilities>
<environment_config>
## 环境变量和配置
**存在检查：**
```bash
# .env 文件存在
[ -f ".env" ] || [ -f ".env.local" ]
# 必需变量已定义
grep -E "^$VAR_NAME=" .env .env.local 2>/dev/null
```
**实质性检查：**
```bash
# 变量有实际值（非占位符）
grep -E "^$VAR_NAME=.+" .env .env.local 2>/dev/null | grep -v "your-.*-here|xxx|placeholder|TODO" -i
# 值对类型看起来有效：
# - URL 应以 http 开头
# - 密钥应足够长
# - 布尔值应为 true/false
```
**环境变量特有的存根模式：**
```bash
# 危险信号 - 这些是存根：
DATABASE_URL=your-database-url-here
STRIPE_SECRET_KEY=sk_test_xxx
API_KEY=placeholder
NEXT_PUBLIC_API_URL=http://localhost:3000 # 生产环境仍指向 localhost
```
**连接检查：**
```bash
# 变量实际在代码中使用
grep -r "process\.env\.$VAR_NAME|env\.$VAR_NAME" src/ --include="*.ts" --include="*.tsx"
# 变量在验证模式中（如果使用 zod 等验证 env）
grep -E "$VAR_NAME" src/env.ts src/env.mjs 2>/dev/null
```
</environment_config>
<wiring_verification>
## 连接验证模式
连接验证检查组件是否实际通信。这是大多数存根隐藏的地方。
### 模式：组件 → API
**检查：** 组件是否实际调用 API？
```bash
# 查找 fetch/axios 调用
grep -E "fetch\(['\"].*$api_path|axios\.(get|post).*$api_path" "$component_path"
# 验证未被注释掉
grep -E "fetch\(|axios\." "$component_path" | grep -v "^.*//.*fetch"
# 检查响应被使用
grep -E "await.*fetch|\.then\(|setData|setState" "$component_path"
```
**危险信号：**
```typescript
// Fetch 存在但响应被忽略：
fetch('/api/messages') // 无 await，无 .then，无赋值
// Fetch 在注释中：
// fetch('/api/messages').then(r => r.json()).then(setMessages)
// Fetch 到错误的端点：
fetch('/api/message') // 拼写错误 - 应该是 /api/messages
```
### 模式：API → 数据库
**检查：** API 路由是否实际查询数据库？
```bash
# 查找数据库调用
grep -E "prisma\.$model|db\.query|Model\.find" "$route_path"
# 验证被 await
grep -E "await.*prisma|await.*db\." "$route_path"
# 检查结果被返回
grep -E "return.*json.*data|res\.json.*result" "$route_path"
```
**危险信号：**
```typescript
// 查询存在但结果未返回：
await prisma.message.findMany()
return Response.json({ ok: true }) // 返回静态值，非查询结果
// 查询未被 await：
const messages = prisma.message.findMany() // 缺少 await
return Response.json(messages) // 返回 Promise，非数据
```
### 模式：表单 → 处理器
**检查：** 表单提交是否实际做些什么？
```bash
# 查找 onSubmit 处理器
grep -E "onSubmit=\{|handleSubmit" "$component_path"
# 检查处理器有内容
grep -A 10 "onSubmit.*=" "$component_path" | grep -E "fetch|axios|mutate|dispatch"
# 验证不仅仅是 preventDefault
grep -A 5 "onSubmit" "$component_path" | grep -v "only.*preventDefault" -i
```
**危险信号：**
```typescript
// 处理器仅阻止默认：
onSubmit={(e) => e.preventDefault()}
// 处理器仅日志：
const handleSubmit = (data) => {
console.log(data)
}
// 处理器为空：
onSubmit={() => {}}
```
### 模式：状态 → 渲染
**检查：** 组件是否渲染状态，而非硬编码内容？
```bash
# 查找 JSX 中的状态使用
grep -E "\{.*messages.*\}|\{.*data.*\}|\{.*items.*\}" "$component_path"
# 检查状态的 map/render
grep -E "\.map\(|\.filter\(|\.reduce\(" "$component_path"
# 验证动态内容
grep -E "\{[a-zA-Z_]+\." "$component_path" # 变量插值
```
**危险信号：**
```tsx
// 硬编码而非状态：
return <div>
<p>Message 1</p>
<p>Message 2</p>
</div>
// 状态存在但未渲染：
const [messages, setMessages] = useState([])
return <div>No messages</div> // 总是显示 "no messages"
// 渲染错误的状态：
const [messages, setMessages] = useState([])
return <div>{otherData.map(...)}</div> // 使用不同数据
```
</wiring_verification>
<verification_checklist>
## 快速验证清单
对于每种工件类型，运行此清单：
### 组件清单
- [ ] 文件存在于预期路径
- [ ] 导出函数/const 组件
- [ ] 返回 JSX（非 null/空）
- [ ] 渲染中无占位符文本
- [ ] 使用 props 或 state（非静态）
- [ ] 事件处理器有真实实现
- [ ] 导入正确解析
- [ ] 在应用某处被使用
### API 路由清单
- [ ] 文件存在于预期路径
- [ ] 导出 HTTP 方法处理器
- [ ] 处理器超过 5 行
- [ ] 查询数据库或服务
- [ ] 返回有意义的响应（非空/占位符）
- [ ] 有错误处理
- [ ] 验证输入
- [ ] 从前端调用
### 模式清单
- [ ] 模型/表已定义
- [ ] 有所有预期字段
- [ ] 字段有适当类型
- [ ] 如需要关系已定义
- [ ] 迁移存在且已应用
- [ ] 客户端已生成
### Hook/工具清单
- [ ] 文件存在于预期路径
- [ ] 导出函数
- [ ] 有有意义的实现（非空返回）
- [ ] 在应用某处被使用
- [ ] 返回值被消费
### 连接清单
- [ ] 组件 → API: fetch/axios 调用存在且使用响应
- [ ] API → 数据库: 查询存在且结果返回
- [ ] 表单 → 处理器: onSubmit 调用 API/mutation
- [ ] 状态 → 渲染: 状态变量出现在 JSX 中
</verification_checklist>
<automated_verification_script>
## 自动化验证方法
对于验证子代理，使用此模式：
```bash
# 1. 检查存在
check_exists() {
[ -f "$1" ] && echo "EXISTS: $1" || echo "MISSING: $1"
}
# 2. 检查存根模式
check_stubs() {
local file="$1"
local stubs=$(grep -c -E "TODO|FIXME|placeholder|not implemented" "$file" 2>/dev/null || echo 0)
[ "$stubs" -gt 0 ] && echo "STUB_PATTERNS: $stubs in $file"
}
# 3. 检查连接（组件调用 API）
check_wiring() {
local component="$1"
local api_path="$2"
grep -q "$api_path" "$component" && echo "WIRED: $component → $api_path" || echo "NOT_WIRED: $component → $api_path"
}
# 4. 检查实质性（超过 N 行，有预期模式）
check_substantive() {
local file="$1"
local min_lines="$2"
local pattern="$3"
local lines=$(wc -l < "$file" 2>/dev/null || echo 0)
local has_pattern=$(grep -c -E "$pattern" "$file" 2>/dev/null || echo 0)
[ "$lines" -ge "$min_lines" ] && [ "$has_pattern" -gt 0 ] && echo "SUBSTANTIVE: $file" || echo "THIN: $file ($lines lines, $has_pattern matches)"
}
```
对每个必须有工件运行这些检查。汇总结果到 VERIFICATION.md。
</automated_verification_script>
<human_verification_triggers>
## 何时需要人工验证
有些事情无法编程验证。标记这些需要人工测试：
**始终人工：**
- 视觉外观（看起来对吗？）
- 用户流程完成（能实际做那件事吗？）
- 实时行为（WebSocket、SSE）
- 外部服务集成（Stripe、邮件发送）
- 错误消息清晰度（消息有帮助吗？）
- 性能感觉（感觉快吗？）
**如不确定则人工：**
- grep 无法追踪的复杂连接
- 依赖状态的动态行为
- 边缘情况和错误状态
- 移动端响应式
- 无障碍性
**人工验证请求格式：**
```markdown
## 需要人工验证
### 1. 聊天消息发送
**测试：** 输入消息并点击发送
**预期：** 消息出现在列表中，输入框清空
**检查：** 刷新后消息是否持久？
### 2. 错误处理
**测试：** 断开网络，尝试发送
**预期：** 错误消息出现，消息未丢失
**检查：** 重连后能重试吗？
```
</human_verification_triggers>
<checkpoint_automation_reference>
## 检查点前自动化
关于自动化优先的检查点模式、服务器生命周期管理、CLI 安装处理和错误恢复协议，请参阅：
**@~/.claude/get-shit-done/references/checkpoints.md** → `<automation_reference>` 部分
关键原则：
- Claude 在呈现检查点**之前**设置验证环境
- 用户从不运行 CLI 命令（仅访问 URL）
- 服务器生命周期：检查点前启动、处理端口冲突、持续运行
- CLI 安装：安全处自动安装，否则检查点让用户选择
- 错误处理：检查点前修复损坏环境，绝不呈现有失败设置的检查点
</checkpoint_automation_reference>