diff --git a/README.md b/README.md index 976250856..ca34dfb0a 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md new file mode 100644 index 000000000..150aa346e --- /dev/null +++ b/docs/zh-CN/README.md @@ -0,0 +1,707 @@ +
+ +# 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) + +
+ +```bash +npx get-shit-done-cc@latest +``` + +**支持 Mac、Windows 和 Linux。** + +
+ +![GSD Install](../assets/terminal.svg) + +
+ +*"如果你清楚自己想要什么，它真的会帮你构建出来。不忽悠。"* + +*"我试过 SpecKit、OpenSpec 和 Taskmaster —— 这是我用过的效果最好的。"* + +*"这是我用过的 Claude Code 最强大的扩展。没有过度设计。真的就是把事情做完。"* + +
+ +**被 Amazon、Google、Shopify 和 Webflow 的工程师信赖使用。** + +[我为什么开发这个](#我为什么开发这个) · [工作原理](#工作原理) · [命令](#命令) · [为什么有效](#为什么有效) · [用户指南](USER-GUIDE.md) + +
+ +--- + +## 我为什么开发这个 + +我是一名独立开发者。我不写代码 —— 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 +``` + +
+非交互式安装（Docker、CI、脚本） + +```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` 跳过运行时提示。 + +
+ +
+开发安装 + +克隆仓库并本地运行安装程序： + +```bash +git clone https://github.com/glittercowboy/get-shit-done.git +cd get-shit-done +node bin/install.js --claude --local +``` + +安装到 `./.claude/` 用于在贡献前测试修改。 + +
+ +### 推荐：跳过权限模式 + +GSD 设计为无摩擦自动化。运行 Claude Code 时使用： + +```bash +claude --dangerously-skip-permissions +``` + +> [!TIP] +> 这是 GSD 的预期使用方式 —— 停下来 50 次批准 `date` 和 `git commit` 会失去意义。 + +
+替代方案：细粒度权限 + +如果你不想使用那个标志，在项目的 `.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:*)" + ] + } +} +``` + +
+ +--- + +## 工作原理 + +> **已有代码？** 先运行 `/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 --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 + + 创建登录端点 + src/app/api/auth/login/route.ts + + 使用 jose 处理 JWT（不用 jsonwebtoken - CommonJS 问题）。 + 根据 users 表验证凭据。 + 成功时返回 httpOnly cookie。 + + curl -X POST localhost:3000/api/auth/login 返回 200 + Set-Cookie + 有效凭据返回 cookie，无效返回 401 + +``` + +精确的指令。不猜测。内置验证。 + +### 多代理编排 + +每个阶段使用相同模式：轻量编排器生成专门代理，收集结果，路由到下一步。 + +| 阶段 | 编排器做 | 代理做 | +|-------|------------------|-----------| +| 研究 | 协调，呈现发现 | 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 ` | 在并行波次中执行所有计划，完成后验证 | +| `/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 ` | 切换模型配置文件（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` 自动修复 | + +¹ 由 Reddit 用户 OracleGreyBeard 贡献 + +--- + +## 配置 + +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 历史 + + + + + + Star History Chart + + + +--- + +## 许可证 + +MIT 许可证。详见 [LICENSE](../LICENSE)。 + +--- + +
+ +**Claude Code 很强大。GSD 让它可靠。** + +
\ No newline at end of file diff --git a/docs/zh-CN/USER-GUIDE.md b/docs/zh-CN/USER-GUIDE.md new file mode 100644 index 000000000..66cae6a0a --- /dev/null +++ b/docs/zh-CN/USER-GUIDE.md @@ -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 ` | 在并行波次中执行所有计划 | 规划完成后 | +| `/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 ` | 快速切换配置 | 更改成本/质量权衡 | +| `/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 # 执行后验证结果 +``` \ No newline at end of file diff --git a/docs/zh-CN/references/checkpoints.md b/docs/zh-CN/references/checkpoints.md new file mode 100644 index 000000000..a41a22edb --- /dev/null +++ b/docs/zh-CN/references/checkpoints.md @@ -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 + + [Claude 自动化并部署/构建的内容] + + [测试的确切步骤 - URL、命令、预期行为] + + [如何继续 - "approved"、"yes" 或描述问题] + +``` + +**示例：UI 组件（展示关键模式：Claude 在检查点之前启动服务器）** +```xml + + 构建响应式仪表板布局 + src/components/Dashboard.tsx, src/app/dashboard/page.tsx + 创建带侧边栏、标题和内容区域的仪表板。使用 Tailwind 响应式类处理移动端。 + npm run build 成功，无 TypeScript 错误 + 仪表板组件构建无错误 + + + + 启动开发服务器用于验证 + 在后台运行 `npm run dev`，等待 "ready" 消息，捕获端口 + curl http://localhost:3000 返回 200 + 开发服务器运行于 http://localhost:3000 + + + + 响应式仪表板布局 - 开发服务器运行于 http://localhost:3000 + + 访问 http://localhost:3000/dashboard 并验证： + 1. 桌面端 (>1024px): 左侧边栏，右侧内容，顶部标题 + 2. 平板端 (768px): 侧边栏折叠为汉堡菜单 + 3. 移动端 (375px): 单列布局，出现底部导航 + 4. 任何尺寸无布局偏移或水平滚动 + + 输入 "approved" 或描述布局问题 + +``` + +### checkpoint:decision（9%） + +**何时使用：** 人工必须做出影响实现方向的选择。 + +**用于：** +- 技术选型（哪个认证提供商、哪个数据库） +- 架构决策（monorepo 还是独立仓库） +- 设计选择（配色方案、布局方式） +- 功能优先级（构建哪个变体） +- 数据模型决策（模式结构） + +**结构：** +```xml + + [正在决策的内容] + [为什么这个决策重要] + + + + + [如何表明选择] + +``` + +**示例：认证提供商选择** +```xml + + 选择认证提供商 + + 应用需要用户认证。三个可靠选项各有权衡。 + + + + + + + 选择：supabase、clerk 或 nextauth + +``` + +### checkpoint:human-action（1% - 罕见） + +**何时使用：** 操作没有 CLI/API 且需要仅人工交互，或者 Claude 在自动化过程中遇到认证门控。 + +**仅用于：** +- **认证门控** - Claude 尝试了 CLI/API 但需要凭证（这不是失败） +- 邮箱验证链接（点击邮件） +- 短信两步验证码（手机验证） +- 人工账户审批（平台需要人工审核） +- 信用卡 3D Secure 流程（基于 Web 的支付授权） +- OAuth 应用审批（基于 Web 的审批） + +**不要用于预定的手动工作：** +- 部署（使用 CLI - 如需要则认证门控） +- 创建 webhooks/数据库（使用 API/CLI - 如需要则认证门控） +- 运行构建/测试（使用 Bash 工具） +- 创建文件（使用 Write 工具） + +**结构：** +```xml + + [人工必须做什么 - Claude 已完成所有可自动化的] + + [Claude 已自动化的内容] + [需要人工操作的一件事] + + [Claude 之后可以检查的内容] + [如何继续] + +``` + +**示例：认证门控（动态检查点）** +```xml + + 部署到 Vercel + .vercel/, vercel.json + 运行 `vercel --yes` 进行部署 + vercel ls 显示部署，curl 返回 200 + + + + + + 认证 Vercel CLI 以便我继续部署 + + 我尝试部署但收到认证错误。 + 运行：vercel login + 这将打开你的浏览器 - 完成认证流程。 + + vercel whoami 返回你的账户邮箱 + 认证完成后输入 "done" + + + + + + 重试 Vercel 部署 + 运行 `vercel --yes`（已认证） + vercel ls 显示部署，curl 返回 200 + +``` + +**关键区别：** 认证门控是 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 + + 仪表板组件 + + 1. 运行: npm run dev + 2. 访问: http://localhost:3000/dashboard + 3. 检查布局是否正确 + + +``` +**为什么错误：** Claude 可以运行 `npm run dev`。用户应该只访问 URL，不执行命令。 + +### ✅ 正确：Claude 启动服务器，用户访问 +```xml + + 启动开发服务器 + 在后台运行 `npm run dev` + curl localhost:3000 返回 200 + + + + http://localhost:3000/dashboard 的仪表板（服务器运行中） + + 访问 http://localhost:3000/dashboard 并验证： + 1. 布局匹配设计 + 2. 无控制台错误 + + +``` + +### ❌ 错误：让用户部署 / ✅ 正确：Claude 自动化 +```xml + + + 部署到 Vercel + 访问 vercel.com/new → 导入仓库 → 点击部署 → 复制 URL + + + + + 部署到 Vercel + 运行 `vercel --yes`。捕获 URL。 + vercel ls 显示部署，curl 返回 200 + + + + 已部署到 {url} + 访问 {url}，检查首页加载 + 输入 "approved" + +``` + +## 摘要 + +检查点规范化人工介入点用于验证和决策，而非手动工作。 + +**黄金法则：** 如果 Claude 能自动化它，Claude 就必须自动化它。 + +**检查点优先级：** +1. **checkpoint:human-verify**（90%）- Claude 自动化一切，人工确认视觉/功能正确性 +2. **checkpoint:decision**（9%）- 人工做出架构/技术选择 +3. **checkpoint:human-action**（1%）- 真正无法避免的、没有 API/CLI 的手动步骤 + +**何时不用检查点：** +- Claude 可以编程验证的事情（测试、构建） +- 文件操作（Claude 可以读取文件） +- 代码正确性（测试和静态分析） +- 任何可通过 CLI/API 自动化的内容 \ No newline at end of file diff --git a/docs/zh-CN/references/continuation-format.md b/docs/zh-CN/references/continuation-format.md new file mode 100644 index 000000000..674b3e770 --- /dev/null +++ b/docs/zh-CN/references/continuation-format.md @@ -0,0 +1,249 @@ +# 续接格式 + +完成命令或工作流后展示下一步的标准格式。 + +## 核心结构 + +``` +--- + +## ▶ 下一步 + +**{标识符}: {名称}** — {单行描述} + +`{可复制粘贴的命令}` + +`/clear` 优先 → 全新上下文窗口 + +--- + +**也可选：** +- `{备选项 1}` — 描述 +- `{备选项 2}` — 描述 + +--- +``` + +## 格式规则 + +1. **始终展示它是什么** — 名称 + 描述，绝不仅仅是一个命令路径 +2. **从源文件拉取上下文** — ROADMAP.md 用于阶段，PLAN.md `` 用于计划 +3. **命令用内联代码** — 反引号，易于复制粘贴，渲染为可点击链接 +4. **`/clear` 说明** — 始终包含，保持简洁但解释原因 +5. **用"也可选"而非"其他选项"** — 听起来更像应用 +6. **视觉分隔符** — 上下用 `---` 使其突出 + +## 变体 + +### 执行下一个计划 + +``` +--- + +## ▶ 下一步 + +**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh + +`/gsd:execute-phase 2` + +`/clear` 优先 → 全新上下文窗口 + +--- + +**也可选：** +- 执行前审查计划 +- `/gsd:list-phase-assumptions 2` — 检查假设 + +--- +``` + +### 执行阶段中最后一个计划 + +添加注释说明这是最后一个计划以及接下来是什么： + +``` +--- + +## ▶ 下一步 + +**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh +阶段 2 的最后一个计划 + +`/gsd:execute-phase 2` + +`/clear` 优先 → 全新上下文窗口 + +--- + +**完成后：** +- 阶段 2 → 阶段 3 过渡 +- 下一步：**阶段 3: 核心功能** — 用户仪表板和设置 + +--- +``` + +### 规划阶段 + +``` +--- + +## ▶ 下一步 + +**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程 + +`/gsd:plan-phase 2` + +`/clear` 优先 → 全新上下文窗口 + +--- + +**也可选：** +- `/gsd:discuss-phase 2` — 先收集上下文 +- `/gsd:research-phase 2` — 调查未知项 +- 审查路线图 + +--- +``` + +### 阶段完成，准备下一步 + +在下一步操作前显示完成状态： + +``` +--- + +## ✓ 阶段 2 完成 + +3/3 计划已执行 + +## ▶ 下一步 + +**阶段 3: 核心功能** — 用户仪表板、设置和数据导出 + +`/gsd:plan-phase 3` + +`/clear` 优先 → 全新上下文窗口 + +--- + +**也可选：** +- `/gsd:discuss-phase 3` — 先收集上下文 +- `/gsd:research-phase 3` — 调查未知项 +- 回顾阶段 2 构建的内容 + +--- +``` + +### 多个同等选项 + +当没有明确的主要操作时： + +``` +--- + +## ▶ 下一步 + +**阶段 3: 核心功能** — 用户仪表板、设置和数据导出 + +**直接规划：** `/gsd:plan-phase 3` + +**先讨论上下文：** `/gsd:discuss-phase 3` + +**研究未知项：** `/gsd:research-phase 3` + +`/clear` 优先 → 全新上下文窗口 + +--- +``` + +### 里程碑完成 + +``` +--- + +## 🎉 里程碑 v1.0 完成 + +全部 4 个阶段已发布 + +## ▶ 下一步 + +**开始 v1.1** — 提问 → 研究 → 需求 → 路线图 + +`/gsd:new-milestone` + +`/clear` 优先 → 全新上下文窗口 + +--- +``` + +## 拉取上下文 + +### 用于阶段（从 ROADMAP.md）： + +```markdown +### 阶段 2: 认证 +**目标**: 带刷新令牌的 JWT 登录流程 +``` + +提取：`**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程` + +### 用于计划（从 ROADMAP.md）： + +```markdown +计划: +- [ ] 02-03: 添加刷新令牌轮换 +``` + +或从 PLAN.md ``： + +```xml + +添加带滑动过期窗口的刷新令牌轮换。 + +目的: 在不影响安全性的前提下延长会话生命周期。 + +``` + +提取：`**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh` + +## 反模式 + +### 不要：仅命令（无上下文） + +``` +## 继续 + +运行 `/clear`，然后粘贴： +/gsd:execute-phase 2 +``` + +用户不知道 02-03 是关于什么的。 + +### 不要：缺少 /clear 说明 + +``` +`/gsd:plan-phase 3` + +先运行 /clear。 +``` + +没有解释原因。用户可能跳过。 + +### 不要："其他选项" 措辞 + +``` +其他选项： +- 审查路线图 +``` + +听起来像是事后补充。用"也可选："替代。 + +### 不要：用围栏代码块展示命令 + +``` +``` +/gsd:plan-phase 3 +``` +``` + +模板内的围栏代码块会造成嵌套歧义。用内联反引号替代。 \ No newline at end of file diff --git a/docs/zh-CN/references/decimal-phase-calculation.md b/docs/zh-CN/references/decimal-phase-calculation.md new file mode 100644 index 000000000..d25f46870 --- /dev/null +++ b/docs/zh-CN/references/decimal-phase-calculation.md @@ -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/` \ No newline at end of file diff --git a/docs/zh-CN/references/git-integration.md b/docs/zh-CN/references/git-integration.md new file mode 100644 index 000000000..8fb58d0a6 --- /dev/null +++ b/docs/zh-CN/references/git-integration.md @@ -0,0 +1,248 @@ + +GSD 框架的 Git 集成。 + + + + +**提交结果，而非过程。** + +git 日志应该读起来像是发布内容的变更日志，而不是规划活动的日记。 + + + + +| 事件 | 提交? | 原因 | +| ----------------------- | ------- | ------------------------------------------------ | +| BRIEF + ROADMAP 创建 | 是 | 项目初始化 | +| PLAN.md 创建 | 否 | 中间产物 - 与计划完成一起提交 | +| RESEARCH.md 创建 | 否 | 中间产物 | +| DISCOVERY.md 创建 | 否 | 中间产物 | +| **任务完成** | 是 | 原子工作单元（每个任务 1 个提交） | +| **计划完成** | 是 | 元数据提交（SUMMARY + STATE + ROADMAP） | +| 交接创建 | 是 | WIP 状态保留 | + + + + + +```bash +[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT" +``` + +如果 NO_GIT：静默运行 `git init`。GSD 项目总是有自己的仓库。 + + + + + +## 项目初始化（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/ +``` + + + + +## 任务完成（计划执行期间） + +每个任务在完成后立即获得自己的提交。 + +``` +{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 +" +``` + + + + +## 计划完成（所有任务完成后） + +所有任务提交后，最后一个元数据提交捕获计划完成。 + +``` +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 +``` + +**注意：** 代码文件不包含 - 已按任务提交。 + + + + +## 交接（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/ +``` + + + + + + +**旧方法（每个计划提交）：** +``` +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。 + + + + + +**仍不要提交（中间产物）：** +- PLAN.md 创建（与计划完成一起提交） +- RESEARCH.md（中间产物） +- DISCOVERY.md（中间产物） +- 小的规划调整 +- "Fixed typo in roadmap" + +**要提交（结果）：** +- 每个任务完成（feat/fix/test/refactor） +- 计划完成元数据（docs） +- 项目初始化（docs） + +**关键原则：** 提交可工作的代码和已发布的结果，而非规划过程。 + + + + + +## 为什么使用每任务提交？ + +**AI 上下文工程：** +- Git 历史成为未来 Claude 会话的主要上下文源 +- `git log --grep="{phase}-{plan}"` 显示计划的所有工作 +- `git diff ^..` 显示每个任务的确切变更 +- 减少对解析 SUMMARY.md 的依赖 = 更多上下文用于实际工作 + +**失败恢复：** +- 任务 1 已提交 ✅，任务 2 失败 ❌ +- 下次会话中的 Claude：看到任务 1 完成，可以重试任务 2 +- 可以 `git reset --hard` 到最后一个成功的任务 + +**调试：** +- `git bisect` 找到确切的失败任务，而不仅仅是失败计划 +- `git blame` 将行追溯到特定任务上下文 +- 每个提交独立可回滚 + +**可观察性：** +- 独立开发者 + Claude 工作流受益于细粒度归因 +- 原子提交是 git 最佳实践 +- 当消费者是 Claude 而非人类时，"提交噪音"无关紧要 + + \ No newline at end of file diff --git a/docs/zh-CN/references/git-planning-commit.md b/docs/zh-CN/references/git-planning-commit.md new file mode 100644 index 000000000..fd128ba6c --- /dev/null +++ b/docs/zh-CN/references/git-planning-commit.md @@ -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/` 检查） \ No newline at end of file diff --git a/docs/zh-CN/references/model-profile-resolution.md b/docs/zh-CN/references/model-profile-resolution.md new file mode 100644 index 000000000..777a9a4b0 --- /dev/null +++ b/docs/zh-CN/references/model-profile-resolution.md @@ -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"`） \ No newline at end of file diff --git a/docs/zh-CN/references/model-profiles.md b/docs/zh-CN/references/model-profiles.md new file mode 100644 index 000000000..011fbba57 --- /dev/null +++ b/docs/zh-CN/references/model-profiles.md @@ -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 ` + +项目默认值：在 `.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。 \ No newline at end of file diff --git a/docs/zh-CN/references/phase-argument-parsing.md b/docs/zh-CN/references/phase-argument-parsing.md new file mode 100644 index 000000000..1434143bb --- /dev/null +++ b/docs/zh-CN/references/phase-argument-parsing.md @@ -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) +``` \ No newline at end of file diff --git a/docs/zh-CN/references/planning-config.md b/docs/zh-CN/references/planning-config.md new file mode 100644 index 000000000..075d2f85d --- /dev/null +++ b/docs/zh-CN/references/planning-config.md @@ -0,0 +1,200 @@ + + +`.planning/` 目录行为的配置选项。 + + +```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}"` | 里程碑策略的分支模板 | + + + + +**当 `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 状态 —— 无需手动条件判断。 + + + + + +**当 `search_gitignored: false`（默认）：** +- 标准 rg 行为（尊重 .gitignore） +- 直接路径搜索有效：`rg "pattern" .planning/` 找到文件 +- 广泛搜索跳过 gitignored：`rg "pattern"` 跳过 `.planning/` + +**当 `search_gitignored: true`:** +- 在应该包含 `.planning/` 的广泛 rg 搜索中添加 `--no-ignore` +- 仅在搜索整个仓库并期望 `.planning/` 匹配时需要 + +**注意：** 大多数 GSD 操作使用直接文件读取或显式路径，无论 gitignore 状态如何都有效。 + + + + + +使用未提交模式： + +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/` 文件，然后才进行合并提交。 + + + + + +**分支策略：** + +| 策略 | 创建分支时机 | 分支范围 | 合并点 | +|----------|---------------------|--------------|-------------| +| `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 | + + + + \ No newline at end of file diff --git a/docs/zh-CN/references/questioning.md b/docs/zh-CN/references/questioning.md new file mode 100644 index 000000000..7f23dbe07 --- /dev/null +++ b/docs/zh-CN/references/questioning.md @@ -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 来构建。 \ No newline at end of file diff --git a/docs/zh-CN/references/tdd.md b/docs/zh-CN/references/tdd.md new file mode 100644 index 000000000..247bf77d3 --- /dev/null +++ b/docs/zh-CN/references/tdd.md @@ -0,0 +1,263 @@ + +TDD 关乎设计质量，而非覆盖率指标。红-绿-重构循环迫使你在实现前思考行为，从而产生更清晰的接口和更可测试的代码。 + +**原则：** 如果在编写 `fn` 之前能用 `expect(fn(input)).toBe(output)` 描述行为，TDD 会改善结果。 + +**关键洞察：** TDD 工作本质上比标准任务更重 —— 它需要 2-3 个执行周期（RED → GREEN → REFACTOR），每个周期都涉及文件读取、测试运行和可能的调试。TDD 功能获得专门的计划，以确保整个周期内有完整的上下文可用。 + + + +## 何时 TDD 提高质量 + +**TDD 候选（创建 TDD 计划）：** +- 有明确输入/输出的业务逻辑 +- 有请求/响应契约的 API 端点 +- 数据转换、解析、格式化 +- 验证规则和约束 +- 有可测试行为的算法 +- 状态机和工作流 +- 有清晰规格的工具函数 + +**跳过 TDD（使用带 `type="auto"` 任务的标准计划）：** +- UI 布局、样式、视觉组件 +- 配置更改 +- 连接现有组件的胶水代码 +- 一次性脚本和迁移 +- 无业务逻辑的简单 CRUD +- 探索性原型 + +**启发式：** 能在编写 `fn` 之前写 `expect(fn(input)).toBe(output)` 吗？ +→ 能：创建 TDD 计划 +→ 不能：使用标准计划，事后添加测试（如需要） + + + +## TDD 计划结构 + +每个 TDD 计划通过完整的 RED-GREEN-REFACTOR 循环实现**一个功能**。 + +```markdown +--- +phase: XX-name +plan: NN +type: tdd +--- + + +[什么功能以及为什么] +Purpose: [该功能 TDD 的设计收益] +Output: [可工作的、已测试的功能] + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@relevant/source/files.ts + + + + [功能名称] + [源文件, 测试文件] + + [可测试术语描述的预期行为] + Cases: 输入 → 预期输出 + + [测试通过后如何实现] + + + +[证明功能有效的测试命令] + + + +- 失败测试已编写并提交 +- 实现通过测试 +- 重构完成（如需要） +- 所有 2-3 个提交都存在 + + + +完成后，创建包含以下内容的 SUMMARY.md： +- RED: 编写了什么测试，为什么失败 +- GREEN: 什么实现让它通过 +- REFACTOR: 做了什么清理（如有） +- Commits: 生成的提交列表 + +``` + +**每个 TDD 计划一个功能。** 如果功能足够简单可以批量处理，那就足够简单可以跳过 TDD —— 使用标准计划，事后添加测试。 + + + +## 红-绿-重构循环 + +**RED - 编写失败测试：** +1. 按项目约定创建测试文件 +2. 编写描述预期行为的测试（来自 `` 元素） +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 个原子提交。 + + + +## 好测试 vs 坏测试 + +**测试行为，而非实现：** +- 好："返回格式化的日期字符串" +- 坏："用正确参数调用 formatDate 辅助函数" +- 测试应该能经受重构 + +**每个测试一个概念：** +- 好：分别为有效输入、空输入、畸形输入编写测试 +- 坏：用多个断言检查所有边缘情况的单个测试 + +**描述性名称：** +- 好："should reject empty email"、"returns null for invalid ID" +- 坏："test1"、"handles error"、"works correctly" + +**不包含实现细节：** +- 好：测试公共 API、可观察行为 +- 坏：Mock 内部实现、测试私有方法、断言内部状态 + + + +## 测试框架设置（如不存在） + +当执行 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 阶段的一次性成本。 + + + +## 错误处理 + +**测试在 RED 阶段没有失败：** +- 功能可能已存在 - 调查 +- 测试可能有误（没测试你以为的东西） +- 前进前修复 + +**测试在 GREEN 阶段没有通过：** +- 调试实现 +- 不要跳到重构 +- 持续迭代直到绿色 + +**测试在 REFACTOR 阶段失败：** +- 撤销重构 +- 提交过早 +- 用更小的步骤重构 + +**不相关的测试失败：** +- 停下来调查 +- 可能表明耦合问题 +- 前进前修复 + + + +## 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 纪律的清晰历史 +- 与整体提交策略一致 + + + +## 上下文预算 + +TDD 计划目标 **~40% 上下文使用率**（低于标准计划的 ~50%）。 + +为什么更低： +- RED 阶段：编写测试、运行测试、可能调试为什么没有失败 +- GREEN 阶段：实现、运行测试、可能对失败进行迭代 +- REFACTOR 阶段：修改代码、运行测试、验证无回归 + +每个阶段涉及读取文件、运行命令、分析输出。来回往复本质上比线性任务执行更重。 + +单一功能聚焦确保整个周期保持完整质量。 + \ No newline at end of file diff --git a/docs/zh-CN/references/ui-brand.md b/docs/zh-CN/references/ui-brand.md new file mode 100644 index 000000000..f9828ae1b --- /dev/null +++ b/docs/zh-CN/references/ui-brand.md @@ -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 已写入 +``` + +--- + +## 下一步区块 + +始终在主要完成后。 + +``` +─────────────────────────────────────────────────────────────── + +## ▶ 下一步 + +**{标识符}: {名称}** — {单行描述} + +`{可复制粘贴的命令}` + +`/clear` 优先 → 全新上下文窗口 + +─────────────────────────────────────────────────────────────── + +**也可选：** +- `/gsd:alternative-1` — 描述 +- `/gsd:alternative-2` — 描述 + +─────────────────────────────────────────────────────────────── +``` + +--- + +## 错误框 + +``` +╔══════════════════════════════════════════════════════════════╗ +║ ERROR ║ +╚══════════════════════════════════════════════════════════════╝ + +{错误描述} + +**修复方法:** {解决步骤} +``` + +--- + +## 表格 + +``` +| 阶段 | 状态 | 计划 | 进度 | +|------|------|------|------| +| 1 | ✓ | 3/3 | 100% | +| 2 | ◆ | 1/4 | 25% | +| 3 | ○ | 0/2 | 0% | +``` + +--- + +## 反模式 + +- 变化的框/横幅宽度 +- 混合横幅样式（`===`、`---`、`***`） +- 横幅中缺少 `GSD ►` 前缀 +- 随机 emoji（`🚀`、`✨`、`💫`） +- 完成后缺少下一步区块 \ No newline at end of file diff --git a/docs/zh-CN/references/verification-patterns.md b/docs/zh-CN/references/verification-patterns.md new file mode 100644 index 000000000..cfeeb8dd0 --- /dev/null +++ b/docs/zh-CN/references/verification-patterns.md @@ -0,0 +1,612 @@ +# 验证模式 + +如何验证不同类型的工件是真实实现，而非存根或占位符。 + + +**存在 ≠ 实现** + +文件存在并不意味着功能有效。验证必须检查： +1. **存在** - 文件在预期路径 +2. **实质性** - 内容是真实实现，非占位符 +3. **已连接** - 已连接到系统的其他部分 +4. **功能性** - 调用时实际工作 + +级别 1-3 可以编程检查。级别 4 通常需要人工验证。 + + + + +## 通用存根模式 + +这些模式表明占位符代码，无论文件类型： + +**基于注释的存根：** +```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" # 硬编码显示值 +``` + + + + + +## 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
Component
+return
Placeholder
+return
{/* TODO */}
+return

Coming soon

+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" +``` + +**功能验证（需要人工）：** +- 组件是否渲染可见内容？ +- 交互元素是否响应点击？ +- 数据是否加载并显示？ +- 错误状态是否适当显示？ + + + + + +## 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 是否实际创建记录？ +- 错误响应是否有正确的状态码？ +- 认证检查是否实际执行？ + + + + + +## 数据库模式（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" +``` + + + + + +## 自定义 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" +``` + + + + + +## 环境变量和配置 + +**存在检查：** +```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 +``` + + + + + +## 连接验证模式 + +连接验证检查组件是否实际通信。这是大多数存根隐藏的地方。 + +### 模式：组件 → 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
+

Message 1

+

Message 2

+
+ +// 状态存在但未渲染： +const [messages, setMessages] = useState([]) +return
No messages
// 总是显示 "no messages" + +// 渲染错误的状态： +const [messages, setMessages] = useState([]) +return
{otherData.map(...)}
// 使用不同数据 +``` + + + + + +## 快速验证清单 + +对于每种工件类型，运行此清单： + +### 组件清单 +- [ ] 文件存在于预期路径 +- [ ] 导出函数/const 组件 +- [ ] 返回 JSX（非 null/空） +- [ ] 渲染中无占位符文本 +- [ ] 使用 props 或 state（非静态） +- [ ] 事件处理器有真实实现 +- [ ] 导入正确解析 +- [ ] 在应用某处被使用 + +### API 路由清单 +- [ ] 文件存在于预期路径 +- [ ] 导出 HTTP 方法处理器 +- [ ] 处理器超过 5 行 +- [ ] 查询数据库或服务 +- [ ] 返回有意义的响应（非空/占位符） +- [ ] 有错误处理 +- [ ] 验证输入 +- [ ] 从前端调用 + +### 模式清单 +- [ ] 模型/表已定义 +- [ ] 有所有预期字段 +- [ ] 字段有适当类型 +- [ ] 如需要关系已定义 +- [ ] 迁移存在且已应用 +- [ ] 客户端已生成 + +### Hook/工具清单 +- [ ] 文件存在于预期路径 +- [ ] 导出函数 +- [ ] 有有意义的实现（非空返回） +- [ ] 在应用某处被使用 +- [ ] 返回值被消费 + +### 连接清单 +- [ ] 组件 → API: fetch/axios 调用存在且使用响应 +- [ ] API → 数据库: 查询存在且结果返回 +- [ ] 表单 → 处理器: onSubmit 调用 API/mutation +- [ ] 状态 → 渲染: 状态变量出现在 JSX 中 + + + + + +## 自动化验证方法 + +对于验证子代理，使用此模式： + +```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。 + + + + + +## 何时需要人工验证 + +有些事情无法编程验证。标记这些需要人工测试： + +**始终人工：** +- 视觉外观（看起来对吗？） +- 用户流程完成（能实际做那件事吗？） +- 实时行为（WebSocket、SSE） +- 外部服务集成（Stripe、邮件发送） +- 错误消息清晰度（消息有帮助吗？） +- 性能感觉（感觉快吗？） + +**如不确定则人工：** +- grep 无法追踪的复杂连接 +- 依赖状态的动态行为 +- 边缘情况和错误状态 +- 移动端响应式 +- 无障碍性 + +**人工验证请求格式：** +```markdown +## 需要人工验证 + +### 1. 聊天消息发送 +**测试：** 输入消息并点击发送 +**预期：** 消息出现在列表中，输入框清空 +**检查：** 刷新后消息是否持久？ + +### 2. 错误处理 +**测试：** 断开网络，尝试发送 +**预期：** 错误消息出现，消息未丢失 +**检查：** 重连后能重试吗？ +``` + + + + + +## 检查点前自动化 + +关于自动化优先的检查点模式、服务器生命周期管理、CLI 安装处理和错误恢复协议，请参阅： + +**@~/.claude/get-shit-done/references/checkpoints.md** → `` 部分 + +关键原则： +- Claude 在呈现检查点**之前**设置验证环境 +- 用户从不运行 CLI 命令（仅访问 URL） +- 服务器生命周期：检查点前启动、处理端口冲突、持续运行 +- CLI 安装：安全处自动安装，否则检查点让用户选择 +- 错误处理：检查点前修复损坏环境，绝不呈现有失败设置的检查点 + + \ No newline at end of file