specops 0.2.4 → 0.3.0

package/.opencode/references/checkpoints.md

@@ -0,0 +1,776 @@
+<overview>
+计划自主执行。检查点将需要人工验证或决策的交互点正式化。
+
+**核心原则：** Claude 用 CLI/API 自动化一切。检查点用于验证和决策，而非手动工作。
+
+**黄金规则：**
+1. **如果 Claude 能运行，Claude 就运行** - 永远不要让用户执行 CLI 命令、启动服务器或运行构建
+2. **Claude 设置验证环境** - 启动开发服务器、填充数据库、配置环境变量
+3. **用户只做需要人类判断的事** - 视觉检查、UX 评估、「这感觉对吗？」
+4. **密钥来自用户，自动化来自 Claude** - 询问 API 密钥，然后 Claude 通过 CLI 使用它们
+5. **自动模式跳过验证/决策检查点** — 当配置中 `workflow.auto_advance` 为 true 时：human-verify 自动批准，decision 自动选择第一个选项，human-action 仍然停止（认证门控不能自动化）
+</overview>
+
+<checkpoint_types>
+
+<type name="human-verify">
+## 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>Build responsive dashboard layout</name>
+  <files>src/components/Dashboard.tsx, src/app/dashboard/page.tsx</files>
+  <action>Create dashboard with sidebar, header, and content area. Use Tailwind responsive classes for mobile.</action>
+  <verify>npm run build succeeds, no TypeScript errors</verify>
+  <done>Dashboard component builds without errors</done>
+</task>
+
+<task type="auto">
+  <name>Start dev server for verification</name>
+  <action>Run `npm run dev` in background, wait for "ready" message, capture port</action>
+  <verify>curl http://localhost:3000 returns 200</verify>
+  <done>Dev server running at http://localhost:3000</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Responsive dashboard layout - dev server running at http://localhost:3000</what-built>
+  <how-to-verify>
+    Visit http://localhost:3000/dashboard and verify:
+    1. Desktop (>1024px): Sidebar left, content right, header top
+    2. Tablet (768px): Sidebar collapses to hamburger menu
+    3. Mobile (375px): Single column layout, bottom nav appears
+    4. No layout shift or horizontal scroll at any size
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe layout issues</resume-signal>
+</task>
+```
+
+**示例：Xcode 构建**
+```xml
+<task type="auto">
+  <name>Build macOS app with Xcode</name>
+  <files>App.xcodeproj, Sources/</files>
+  <action>Run `xcodebuild -project App.xcodeproj -scheme App build`. Check for compilation errors in output.</action>
+  <verify>Build output contains "BUILD SUCCEEDED", no errors</verify>
+  <done>App builds successfully</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Built macOS app at DerivedData/Build/Products/Debug/App.app</what-built>
+  <how-to-verify>
+    Open App.app and test:
+    - App launches without crashes
+    - Menu bar icon appears
+    - Preferences window opens correctly
+    - No visual glitches or layout issues
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+```
+</type>
+
+<type name="decision">
+## checkpoint:decision（9%）
+
+**何时：** 人工必须做出影响实现方向的选择。
+
+**用于：**
+- 技术选型（哪个认证提供商、哪个数据库）
+- 架构决策（monorepo vs 独立仓库）
+- 设计选择（配色方案、布局方式）
+- 特性优先级（构建哪个变体）
+- 数据模型决策（schema 结构）
+
+**结构：**
+```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>Select authentication provider</decision>
+  <context>
+    Need user authentication for the app. Three solid options with different tradeoffs.
+  </context>
+  <options>
+    <option id="supabase">
+      <name>Supabase Auth</name>
+      <pros>Built-in with Supabase DB we're using, generous free tier, row-level security integration</pros>
+      <cons>Less customizable UI, tied to Supabase ecosystem</cons>
+    </option>
+    <option id="clerk">
+      <name>Clerk</name>
+      <pros>Beautiful pre-built UI, best developer experience, excellent docs</pros>
+      <cons>Paid after 10k MAU, vendor lock-in</cons>
+    </option>
+    <option id="nextauth">
+      <name>NextAuth.js</name>
+      <pros>Free, self-hosted, maximum control, widely adopted</pros>
+      <cons>More setup work, you manage security updates, UI is DIY</cons>
+    </option>
+  </options>
+  <resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
+</task>
+```
+
+**示例：数据库选择**
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <decision>Select database for user data</decision>
+  <context>
+    App needs persistent storage for users, sessions, and user-generated content.
+    Expected scale: 10k users, 1M records first year.
+  </context>
+  <options>
+    <option id="supabase">
+      <name>Supabase (Postgres)</name>
+      <pros>Full SQL, generous free tier, built-in auth, real-time subscriptions</pros>
+      <cons>Vendor lock-in for real-time features, less flexible than raw Postgres</cons>
+    </option>
+    <option id="planetscale">
+      <name>PlanetScale (MySQL)</name>
+      <pros>Serverless scaling, branching workflow, excellent DX</pros>
+      <cons>MySQL not Postgres, no foreign keys in free tier</cons>
+    </option>
+    <option id="convex">
+      <name>Convex</name>
+      <pros>Real-time by default, TypeScript-native, automatic caching</pros>
+      <cons>Newer platform, different mental model, less SQL flexibility</cons>
+    </option>
+  </options>
+  <resume-signal>Select: supabase, planetscale, or convex</resume-signal>
+</task>
+```
+</type>
+
+<type name="human-action">
+## checkpoint:human-action（1% - 罕见）
+
+**何时：** 操作没有 CLI/API 且需要人工交互，或 Claude 在自动化过程中遇到认证门控。
+
+**仅用于：**
+- **认证门控** - Claude 尝试了 CLI/API 但需要凭据（这不是失败）
+- 邮件验证链接（点击邮件）
+- 短信 2FA 验证码（手机验证）
+- 手动账户审批（平台需要人工审核）
+- 信用卡 3D Secure 流程（基于 Web 的支付授权）
+- OAuth 应用审批（基于 Web 的审批）
+
+**不要用于预先计划的手动工作：**
+- 部署（使用 CLI - 需要时设认证门控）
+- 创建 webhook/数据库（使用 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>Create SendGrid account via API</name>
+  <action>Use SendGrid API to create subuser account with provided email. Request verification email.</action>
+  <verify>API returns 201, account created</verify>
+  <done>Account created, verification email sent</done>
+</task>
+
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Complete email verification for SendGrid account</action>
+  <instructions>
+    I created the account and requested verification email.
+    Check your inbox for SendGrid verification link and click it.
+  </instructions>
+  <verification>SendGrid API key works: curl test succeeds</verification>
+  <resume-signal>Type "done" when email verified</resume-signal>
+</task>
+```
+
+**示例：认证门控（动态检查点）**
+```xml
+<task type="auto">
+  <name>Deploy to Vercel</name>
+  <files>.vercel/, vercel.json</files>
+  <action>Run `vercel --yes` to deploy</action>
+  <verify>vercel ls shows deployment, curl returns 200</verify>
+</task>
+
+<!-- 如果 vercel 返回 "Error: Not authenticated"，Claude 动态创建检查点 -->
+
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Authenticate Vercel CLI so I can continue deployment</action>
+  <instructions>
+    I tried to deploy but got authentication error.
+    Run: vercel login
+    This will open your browser - complete the authentication flow.
+  </instructions>
+  <verification>vercel whoami returns your account email</verification>
+  <resume-signal>Type "done" when authenticated</resume-signal>
+</task>
+
+<!-- 认证后，Claude 重试部署 -->
+
+<task type="auto">
+  <name>Retry Vercel deployment</name>
+  <action>Run `vercel --yes` (now authenticated)</action>
+  <verify>vercel ls shows deployment, curl returns 200</verify>
+</task>
+```
+
+**关键区别：** 认证门控是 Claude 遇到认证错误时动态创建的。不是预先计划的，Claude 先自动化，只在被阻塞时才请求凭据。
+</type>
+</checkpoint_types>
+
+<execution_protocol>
+
+当 Claude 遇到 `type="checkpoint:*"` 时：
+
+1. **立即停止** - 不要继续下一个任务
+2. **清晰显示检查点** - 使用以下格式
+3. **等待用户响应** - 不要幻想完成
+4. **如果可能则验证** - 检查文件、运行测试等
+5. **恢复执行** - 仅在确认后继续下一个任务
+
+**对于 checkpoint:human-verify：**
+```
+╔═══════════════════════════════════════════════════════╗
+║  CHECKPOINT: Verification Required                    ║
+╚═══════════════════════════════════════════════════════╝
+
+Progress: 5/8 tasks complete
+Task: Responsive dashboard layout
+
+Built: Responsive dashboard at /dashboard
+
+How to verify:
+  1. Visit: http://localhost:3000/dashboard
+  2. Desktop (>1024px): Sidebar visible, content fills remaining space
+  3. Tablet (768px): Sidebar collapses to icons
+  4. Mobile (375px): Sidebar hidden, hamburger menu appears
+
+────────────────────────────────────────────────────────
+→ YOUR ACTION: Type "approved" or describe issues
+────────────────────────────────────────────────────────
+```
+
+**对于 checkpoint:decision：**
+```
+╔═══════════════════════════════════════════════════════╗
+║  CHECKPOINT: Decision Required                        ║
+╚═══════════════════════════════════════════════════════╝
+
+Progress: 2/6 tasks complete
+Task: Select authentication provider
+
+Decision: Which auth provider should we use?
+
+Context: Need user authentication. Three options with different tradeoffs.
+
+Options:
+  1. supabase - Built-in with our DB, free tier
+     Pros: Row-level security integration, generous free tier
+     Cons: Less customizable UI, ecosystem lock-in
+
+  2. clerk - Best DX, paid after 10k users
+     Pros: Beautiful pre-built UI, excellent documentation
+     Cons: Vendor lock-in, pricing at scale
+
+  3. nextauth - Self-hosted, maximum control
+     Pros: Free, no vendor lock-in, widely adopted
+     Cons: More setup work, DIY security updates
+
+────────────────────────────────────────────────────────
+→ YOUR ACTION: Select supabase, clerk, or nextauth
+────────────────────────────────────────────────────────
+```
+
+**对于 checkpoint:human-action：**
+```
+╔═══════════════════════════════════════════════════════╗
+║  CHECKPOINT: Action Required                          ║
+╚═══════════════════════════════════════════════════════╝
+
+Progress: 3/8 tasks complete
+Task: Deploy to Vercel
+
+Attempted: vercel --yes
+Error: Not authenticated. Please run 'vercel login'
+
+What you need to do:
+  1. Run: vercel login
+  2. Complete browser authentication when it opens
+  3. Return here when done
+
+I'll verify: vercel whoami returns your account
+
+────────────────────────────────────────────────────────
+→ YOUR ACTION: Type "done" when authenticated
+────────────────────────────────────────────────────────
+```
+</execution_protocol>
+
+<authentication_gates>
+
+**认证门控 = Claude 尝试了 CLI/API，遇到认证错误。** 不是失败，而是需要人工输入来解除阻塞的门控。
+
+**模式：** Claude 尝试自动化 -> 认证错误 -> 创建 checkpoint:human-action -> 用户认证 -> Claude 重试 -> 继续
+
+**门控协议：**
+1. 认识到这不是失败 - 缺少认证是预期的
+2. 停止当前任务 - 不要反复重试
+3. 动态创建 checkpoint:human-action
+4. 提供精确的认证步骤
+5. 验证认证是否有效
+6. 重试原始任务
+7. 正常继续
+
+**关键区别：**
+- 预先计划的检查点：「我需要你做 X」（错误 - Claude 应该自动化）
+- 认证门控：「我尝试自动化 X 但需要凭据」（正确 - 解除自动化阻塞）
+
+</authentication_gates>
+
+<automation_reference>
+
+**规则：** 如果有 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 calls | API key in .env |
+| 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` |
+
+**密钥收集模式：**
+```xml
+<!-- 错误：让用户在仪表板中添加环境变量 -->
+<task type="checkpoint:human-action">
+  <action>Add OPENAI_API_KEY to Convex dashboard</action>
+  <instructions>Go to dashboard.convex.dev → Settings → Environment Variables → Add</instructions>
+</task>
+
+<!-- 正确：Claude 请求值，然后通过 CLI 添加 -->
+<task type="checkpoint:human-action">
+  <action>Provide your OpenAI API key</action>
+  <instructions>
+    I need your OpenAI API key for Convex backend.
+    Get it from: https://platform.openai.com/api-keys
+    Paste the key (starts with sk-)
+  </instructions>
+  <verification>I'll add it via `npx convex env set` and verify</verification>
+  <resume-signal>Paste your API key</resume-signal>
+</task>
+
+<task type="auto">
+  <name>Configure OpenAI key in Convex</name>
+  <action>Run `npx convex env set OPENAI_API_KEY {user-provided-key}`</action>
+  <verify>`npx convex env get OPENAI_API_KEY` returns the key (masked)</verify>
+</task>
+```
+
+## 开发服务器自动化
+
+| 框架 | 启动命令 | 就绪信号 | 默认 URL |
+|------|----------|----------|----------|
+| Next.js | `npm run dev` | "Ready in" or "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=$!
+
+# 等待就绪（最多 30 秒）
+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」。
+
+```xml
+<!-- 错误：环境损坏的检查点 -->
+<task type="checkpoint:human-verify">
+  <what-built>Dashboard (server failed to start)</what-built>
+  <how-to-verify>Visit http://localhost:3000...</how-to-verify>
+</task>
+
+<!-- 正确：先修复，再设检查点 -->
+<task type="auto">
+  <name>Fix server startup issue</name>
+  <action>Investigate error, fix root cause, restart server</action>
+  <verify>curl http://localhost:3000 returns 200</verify>
+</task>
+
+<task type="checkpoint:human-verify">
+  <what-built>Dashboard - server running at http://localhost:3000</what-built>
+  <how-to-verify>Visit http://localhost:3000/dashboard...</how-to-verify>
+</task>
+```
+
+## 可自动化快速参考
+
+| 操作 | 可自动化？ | 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 是否正确 | 否 | 否 |
+| 测试交互式用户流程 | 否 | 否 |
+
+</automation_reference>
+
+<writing_guidelines>
+
+**要做：**
+- 在检查点前用 CLI/API 自动化一切
+- 具体：「Visit https://myapp.vercel.app」而非「check deployment」
+- 编号验证步骤
+- 说明预期结果：「You should see X」
+- 提供上下文：为什么这个检查点存在
+
+**不要做：**
+- 让人工做 Claude 能自动化的工作 ❌
+- 假设知识：「Configure the usual settings」 ❌
+- 跳过步骤：「Set up database」（太模糊） ❌
+- 在一个检查点中混合多个验证 ❌
+
+**放置位置：**
+- **自动化完成后** - 不是在 Claude 做工作之前
+- **UI 构建后** - 在声明阶段完成之前
+- **依赖工作之前** - 决策在实现之前
+- **集成点** - 配置外部服务之后
+
+**错误放置：** 自动化之前 ❌ | 太频繁 ❌ | 太晚（依赖任务已经需要结果） ❌
+</writing_guidelines>
+
+<examples>
+
+### 示例 1：数据库设置（不需要检查点）
+
+```xml
+<task type="auto">
+  <name>Create Upstash Redis database</name>
+  <files>.env</files>
+  <action>
+    1. Run `upstash redis create myapp-cache --region us-east-1`
+    2. Capture connection URL from output
+    3. Write to .env: UPSTASH_REDIS_URL={url}
+    4. Verify connection with test command
+  </action>
+  <verify>
+    - upstash redis list shows database
+    - .env contains UPSTASH_REDIS_URL
+    - Test connection succeeds
+  </verify>
+  <done>Redis database created and configured</done>
+</task>
+
+<!-- 不需要检查点 - Claude 自动化了一切并通过程序化验证 -->
+```
+
+### 示例 2：完整认证流程（最后一个检查点）
+
+```xml
+<task type="auto">
+  <name>Create user schema</name>
+  <files>src/db/schema.ts</files>
+  <action>Define User, Session, Account tables with Drizzle ORM</action>
+  <verify>npm run db:generate succeeds</verify>
+</task>
+
+<task type="auto">
+  <name>Create auth API routes</name>
+  <files>src/app/api/auth/[...nextauth]/route.ts</files>
+  <action>Set up NextAuth with GitHub provider, JWT strategy</action>
+  <verify>TypeScript compiles, no errors</verify>
+</task>
+
+<task type="auto">
+  <name>Create login UI</name>
+  <files>src/app/login/page.tsx, src/components/LoginButton.tsx</files>
+  <action>Create login page with GitHub OAuth button</action>
+  <verify>npm run build succeeds</verify>
+</task>
+
+<task type="auto">
+  <name>Start dev server for auth testing</name>
+  <action>Run `npm run dev` in background, wait for ready signal</action>
+  <verify>curl http://localhost:3000 returns 200</verify>
+  <done>Dev server running at http://localhost:3000</done>
+</task>
+
+<!-- 最后一个检查点验证完整流程 -->
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Complete authentication flow - dev server running at http://localhost:3000</what-built>
+  <how-to-verify>
+    1. Visit: http://localhost:3000/login
+    2. Click "Sign in with GitHub"
+    3. Complete GitHub OAuth flow
+    4. Verify: Redirected to /dashboard, user name displayed
+    5. Refresh page: Session persists
+    6. Click logout: Session cleared
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+```
+</examples>
+
+<anti_patterns>
+
+### ❌ 错误：让用户启动开发服务器
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Dashboard component</what-built>
+  <how-to-verify>
+    1. Run: npm run dev
+    2. Visit: http://localhost:3000/dashboard
+    3. Check layout is correct
+  </how-to-verify>
+</task>
+```
+
+**为什么错误：** Claude 可以运行 `npm run dev`。用户应该只访问 URL，不执行命令。
+
+### ✅ 正确：Claude 启动服务器，用户访问
+
+```xml
+<task type="auto">
+  <name>Start dev server</name>
+  <action>Run `npm run dev` in background</action>
+  <verify>curl localhost:3000 returns 200</verify>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Dashboard at http://localhost:3000/dashboard (server running)</what-built>
+  <how-to-verify>
+    Visit http://localhost:3000/dashboard and verify:
+    1. Layout matches design
+    2. No console errors
+  </how-to-verify>
+</task>
+```
+
+### ❌ 错误：让人工部署 / ✅ 正确：Claude 自动化
+
+```xml
+<!-- 错误：让用户通过仪表板部署 -->
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Deploy to Vercel</action>
+  <instructions>Visit vercel.com/new → Import repo → Click Deploy → Copy URL</instructions>
+</task>
+
+<!-- 正确：Claude 部署，用户验证 -->
+<task type="auto">
+  <name>Deploy to Vercel</name>
+  <action>Run `vercel --yes`. Capture URL.</action>
+  <verify>vercel ls shows deployment, curl returns 200</verify>
+</task>
+
+<task type="checkpoint:human-verify">
+  <what-built>Deployed to {url}</what-built>
+  <how-to-verify>Visit {url}, check homepage loads</how-to-verify>
+  <resume-signal>Type "approved"</resume-signal>
+</task>
+```
+
+### ❌ 错误：太多检查点 / ✅ 正确：单个检查点
+
+```xml
+<!-- 错误：每个任务后都有检查点 -->
+<task type="auto">Create schema</task>
+<task type="checkpoint:human-verify">Check schema</task>
+<task type="auto">Create API route</task>
+<task type="checkpoint:human-verify">Check API</task>
+<task type="auto">Create UI form</task>
+<task type="checkpoint:human-verify">Check form</task>
+
+<!-- 正确：最后一个检查点 -->
+<task type="auto">Create schema</task>
+<task type="auto">Create API route</task>
+<task type="auto">Create UI form</task>
+
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow (schema + API + UI)</what-built>
+  <how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
+  <resume-signal>Type "approved"</resume-signal>
+</task>
+```
+
+### ❌ 错误：模糊验证 / ✅ 正确：具体步骤
+
+```xml
+<!-- 错误 -->
+<task type="checkpoint:human-verify">
+  <what-built>Dashboard</what-built>
+  <how-to-verify>Check it works</how-to-verify>
+</task>
+
+<!-- 正确 -->
+<task type="checkpoint:human-verify">
+  <what-built>Responsive dashboard - server running at http://localhost:3000</what-built>
+  <how-to-verify>
+    Visit http://localhost:3000/dashboard and verify:
+    1. Desktop (>1024px): Sidebar visible, content area fills remaining space
+    2. Tablet (768px): Sidebar collapses to icons
+    3. Mobile (375px): Sidebar hidden, hamburger menu in header
+    4. No horizontal scroll at any size
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe layout issues</resume-signal>
+</task>
+```
+
+### ❌ 错误：让用户运行 CLI 命令
+
+```xml
+<task type="checkpoint:human-action">
+  <action>Run database migrations</action>
+  <instructions>Run: npx prisma migrate deploy && npx prisma db seed</instructions>
+</task>
+```
+
+**为什么错误：** Claude 可以运行这些命令。用户永远不应该执行 CLI 命令。
+
+### ❌ 错误：让用户在服务之间复制值
+
+```xml
+<task type="checkpoint:human-action">
+  <action>Configure webhook URL in Stripe</action>
+  <instructions>Copy deployment URL → Stripe Dashboard → Webhooks → Add endpoint → Copy secret → Add to .env</instructions>
+</task>
+```
+
+**为什么错误：** Stripe 有 API。Claude 应该通过 API 创建 webhook 并直接写入 .env。
+
+</anti_patterns>
+
+<summary>
+
+检查点将人在回路中的验证和决策点正式化，而非手动工作。
+
+**黄金规则：** 如果 Claude 能自动化，Claude 必须自动化。
+
+**检查点优先级：**
+1. **checkpoint:human-verify**（90%）- Claude 自动化了一切，人工确认视觉/功能正确性
+2. **checkpoint:decision**（9%）- 人工做架构/技术选择
+3. **checkpoint:human-action**（1%）- 真正不可避免的、没有 API/CLI 的手动步骤
+
+**何时不使用检查点：**
+- Claude 可以通过程序化验证的事情（测试、构建）
+- 文件操作（Claude 可以读取文件）
+- 代码正确性（测试和静态分析）
+- 任何可通过 CLI/API 自动化的事情
+</summary>