From e61baf7e4e3032fd805d4497117f53d6ca042ae9 Mon Sep 17 00:00:00 2001 From: Yaojia Wang Date: Fri, 20 Mar 2026 00:19:23 +0100 Subject: [PATCH] vault: add GSD methodology deep-dive with examples and zettelkasten insights Comprehensive GSD analysis: 15 sections covering core philosophy (fresh context per agent), 5 methodologies (dream extraction, goal-backward verification, nyquist validation, wave execution, checkpoints), full command reference (37+), agent system (16 agents with model routing), config system, git integration, state management, session continuity, community best practices, pitfalls, framework comparison (GSD vs ECC vs BMAD vs SpecKit), and 4 detailed practical examples (new project, brownfield, debugging, quick tasks). Three zettelkasten notes: context rot vs window isolation tradeoffs, goal-backward vs forward verification, plans-as-prompts design pattern. --- ...Everything Claude Code 方法论与最佳实践.md | 1 + 4 - Resources/GSD 方法论与最佳实践.md | 906 ++++++++++++++++++ ...20260320100100 上下文腐烂与全新窗口隔离.md | 29 + ...260320100200 目标回溯验证vs正向任务检查.md | 27 + ...20260320100300 Plans as Prompts设计模式.md | 27 + 5 files changed, 990 insertions(+) create mode 100644 4 - Resources/GSD 方法论与最佳实践.md create mode 100644 6 - Zettelkasten/20260320100100 上下文腐烂与全新窗口隔离.md create mode 100644 6 - Zettelkasten/20260320100200 目标回溯验证vs正向任务检查.md create mode 100644 6 - Zettelkasten/20260320100300 Plans as Prompts设计模式.md diff --git a/4 - Resources/Everything Claude Code 方法论与最佳实践.md b/4 - Resources/Everything Claude Code 方法论与最佳实践.md index a7ac6f1..a1dcbc7 100644 --- a/4 - Resources/Everything Claude Code 方法论与最佳实践.md +++ b/4 - Resources/Everything Claude Code 方法论与最佳实践.md @@ -927,3 +927,4 @@ ECC 自动检测项目使用的包管理器，遵循 6 级优先级: - [[Everything Claude Code 完整指南]] - [[Everything Claude Code 用法速查]] +- [[GSD 方法论与最佳实践]] diff --git a/4 - Resources/GSD 方法论与最佳实践.md b/4 - Resources/GSD 方法论与最佳实践.md new file mode 100644 index 0000000..a6c1bd0 --- /dev/null +++ b/4 - Resources/GSD 方法论与最佳实践.md @@ -0,0 +1,906 @@ +--- +created: "2026-03-20 10:00" +type: resource +tags: [claude-code, AI-tools, methodology, best-practices, project-management, gsd] +source: "https://github.com/gsd-build/get-shit-done" +--- + +# GSD (Get Shit Done) 方法论与最佳实践 + +GSD 是一个面向 AI 编码 Agent 的**元提示、上下文工程和规格驱动开发框架**。36K+ GitHub stars，支持 Claude Code、OpenCode、Gemini CLI、Codex、Copilot、Antigravity 六种运行时。 + +> **命名空间**: 所有 GSD 命令以 `gsd:` 为前缀（如 `/gsd:plan-phase`），无需额外插件命名空间。 + +--- + +## 一、核心设计哲学 + +**"复杂性在系统中，不在你的工作流中。"** GSD 将上下文工程、XML 提示格式化、子 Agent 编排和状态管理隐藏在几个简单命令后面。 + +**五大设计原则**: + +| 原则 | 说明 | +|------|------| +| **Fresh Context Per Agent** | 每个子 Agent 获得全新 200K token 上下文窗口，消除"上下文腐烂" | +| **Thin Orchestrators** | 工作流文件只做加载上下文、生成 Agent、收集结果、路由下一步 | +| **File-Based State** | 所有状态存在 `.planning/` 目录下的 Markdown 和 JSON 中，无数据库 | +| **Absent = Enabled** | 配置默认为 true，用户显式禁用而非启用 | +| **Defense in Depth** | 计划执行前验证、每任务原子提交、执行后验证、UAT 人类门控 | + +**上下文腐烂模型**: + +``` +Claude 质量随上下文使用率变化: + 0-30% → 峰值质量（GSD 编排器保持在此范围） + 30-50% → 良好质量 + 50-70% → 开始赶工，质量下降 + 70%+ → 幻觉风险显著增加 +``` + +GSD 的核心竞争力: 为每个任务生成全新 200K 上下文窗口，从根本上避免上下文腐烂。 + +--- + +## 二、项目层级结构 + +``` +Project (项目) + └── Milestone (里程碑 v1.0, v2.0...) + └── Phase (阶段 1, 2, 3...) + └── Plan (计划 A, B, C...) + └── Task (任务 1, 2, 3...) +``` + +**核心文档**: + +| 文档 | 位置 | 用途 | +|------|------|------| +| **PROJECT.md** | `.planning/` | 项目愿景、约束、关键决策 | +| **REQUIREMENTS.md** | `.planning/` | 带唯一 ID (REQ-XX) 的需求列表 | +| **ROADMAP.md** | `.planning/` | 阶段分解 + 状态追踪 + 需求可追溯 | +| **STATE.md** | `.planning/` | 活跃记忆: 当前位置、决策、阻塞、指标（<100行）| +| **CONTEXT.md** | 每阶段目录 | 用户在 discuss-phase 中做的决策 | +| **RESEARCH.md** | 每阶段目录 | 领域研究发现 | +| **PLAN.md** | 每计划目录 | XML 结构的原子任务列表（这是提示词，不是文档）| +| **SUMMARY.md** | 每计划目录 | 执行结果、文件变更、偏差记录 | +| **VERIFICATION.md** | 每阶段目录 | 目标回溯验证报告 | +| **config.json** | `.planning/` | 工作流配置（模式、粒度、模型、git 等）| + +--- + +## 三、核心工作流 + +### 完整生命周期 + +``` +/gsd:new-project → 提问 → 研究 → 需求 → 路线图 + │ + ▼ (对每个阶段) +/gsd:discuss-phase N → 捕获用户偏好 → CONTEXT.md +/gsd:plan-phase N → 研究 → 计划 → 计划检查循环 → PLAN.md +/gsd:execute-phase N → 波浪式并行执行 → 原子提交 +/gsd:verify-work N → 目标回溯验证 → VERIFICATION.md +/gsd:validate-phase N → Nyquist 验证 → 补充测试 +/gsd:ship N → 创建 PR + │ + ▼ (所有阶段完成后) +/gsd:audit-milestone → 审计里程碑完成度 +/gsd:complete-milestone → 归档、打 tag +/gsd:new-milestone → 开始下一个版本 +``` + +**自动推进**: `/gsd:next` 自动检测项目状态，运行下一个逻辑步骤。 + +**快速模式**: `/gsd:quick` 对临时任务提供 GSD 保证（原子提交、状态追踪）但跳过完整规划。可组合标志: `--discuss`, `--research`, `--full`。 + +### 例子 — 完整新项目流程 + +```bash +# Step 1: 初始化项目 +/gsd:new-project +# Claude 以协作思考方式提问（不是需求收集）: +# "你在构建什么？解决什么问题？" +# "目标用户是谁？'完成'长什么样？" +# "有技术栈偏好吗？" +# → 4 个研究 Agent 并行启动: +# Researcher 1: 技术栈调研 +# Researcher 2: 功能特性调研 +# Researcher 3: 架构模式调研 +# Researcher 4: 常见陷阱调研 +# → 合成器汇总为 SUMMARY.md +# → 生成 PROJECT.md, REQUIREMENTS.md, ROADMAP.md + +# Step 2: 讨论第一阶段 +/gsd:discuss-phase 1 +# Claude 提问直到理解你的偏好: +# "数据库用 PostgreSQL 还是 SQLite？" +# "认证用 JWT 还是 Session？" +# "需要邮件验证吗？" +# → 你的决策锁定在 CONTEXT.md 中（后续不可变） + +# Step 3: 规划 +/gsd:plan-phase 1 +# → gsd-phase-researcher 调研实现方案 → RESEARCH.md +# → gsd-planner 生成 2-3 个 PLAN.md（每个 ≤50% 上下文预算） +# → gsd-plan-checker 目标回溯验证（最多 3 次迭代）: +# "这些计划能实现阶段目标吗？" +# "CONTEXT.md 中的决策都被尊重了吗？" +# "每个 REQ-XX 都有对应任务吗？" + +# Step 4: 执行 +/gsd:execute-phase 1 +# → 按依赖分组为波浪（wave） +# → Wave 1: Plan A + Plan B（独立，并行执行） +# → Wave 2: Plan C（依赖 A+B，等待完成后执行） +# → 每个任务: 原子 git 提交 +# → 每个 executor 获得全新 200K 上下文 + +# Step 5: 验证 +/gsd:verify-work 1 +# → gsd-verifier 不信任 SUMMARY.md 的声称 +# → 检查实际代码: +# Exists: 文件在预期路径？ +# Substantive: 是真实实现还是桩代码？ +# Wired: 与系统其他部分连接了吗？ +# → 生成 VERIFICATION.md（通过/差距/建议） + +# Step 6: Nyquist 验证 +/gsd:validate-phase 1 +# → 扫描每个 REQ-XX 是否有对应自动化测试 +# → COVERED / PARTIAL / MISSING 分类 +# → gsd-nyquist-auditor 生成缺失的测试（只改测试文件，不改实现） + +# Step 7: 发布 +/gsd:ship 1 +# → 创建 PR，附带验证报告 +``` + +--- + +## 四、Agent 系统 (16 个) + +每个 Agent 是 Markdown 文件 + YAML frontmatter（name, description, tools, color）。由瘦编排器生成，每个获得全新上下文窗口。 + +### Agent 清单 + +| Agent | 角色 | 并行度 | +|-------|------|--------| +| **gsd-project-researcher** | 项目级领域研究 | 4x 并行（栈/功能/架构/陷阱）| +| **gsd-research-synthesizer** | 合并 4 个研究输出为 SUMMARY.md | 在研究者之后串行 | +| **gsd-roadmapper** | 从需求创建阶段化路线图 | 串行 | +| **gsd-phase-researcher** | 调研特定阶段的实现方案 | 串行 | +| **gsd-planner** | 创建 PLAN.md（XML 任务结构）| 串行 | +| **gsd-plan-checker** | 执行前目标回溯验证（最多 3 次迭代）| 串行循环 | +| **gsd-executor** | 执行 PLAN.md，每任务原子提交 | 波浪内并行 | +| **gsd-verifier** | 执行后目标回溯验证 | 串行 | +| **gsd-debugger** | 科学方法 Bug 调查，跨会话持久状态 | 串行/交互 | +| **gsd-codebase-mapper** | 棕地分析 | 4x 并行（技术/架构/质量/关注点）| +| **gsd-integration-checker** | 跨阶段集成验证 | 串行 | +| **gsd-nyquist-auditor** | 为验证缺口生成测试，从不修改实现 | 串行 | +| **gsd-ui-researcher** | 生成 UI-SPEC.md 设计契约 | 串行 | +| **gsd-ui-checker** | 验证 UI-SPEC 完整性（6 维度）| 串行 | +| **gsd-ui-auditor** | 6 支柱视觉审计 | 串行 | +| **gsd-user-profiler** | 8 维度行为分析 | 串行 | + +**关键模式**: 每个 Agent 接收 `` 块，**必须**在任何操作前读取所有列出的文件。这是主要的上下文注入机制。 + +### 模型路由 + +| Agent | quality | balanced | budget | +|-------|---------|----------|--------| +| gsd-planner | Opus | Opus | Sonnet | +| gsd-executor | Opus | Sonnet | Sonnet | +| gsd-verifier | Sonnet | Sonnet | Haiku | +| gsd-debugger | Opus | Sonnet | Sonnet | +| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | +| gsd-phase-researcher | Sonnet | Sonnet | Haiku | + +`inherit` 配置文件用于非 Anthropic 供应商（OpenRouter、本地模型）。 + +### 例子 — Plan 作为 Prompt + +PLAN.md 不是文档——它**就是** prompt。XML 结构直接指导 executor: + +```xml + +--- +phase: 1 +plan: A +goal: "Implement user registration with email verification" +requirements: [REQ-01, REQ-02] +depends_on: [] +--- + + + + Create User model with fields: id, email, passwordHash, verified, createdAt. + Use Prisma schema. Add unique constraint on email. + + + Run: npx prisma validate + Check: prisma/schema.prisma contains User model with all fields + + prisma/schema.prisma updated with User model + + + + + Create POST /api/auth/register endpoint. + Validate input with zod schema (email format, password min 8 chars). + Hash password with bcrypt (12 rounds). + Send verification email via SendGrid. + Return 201 with user ID. + + + Run: npm test -- --grep "register" + Check: tests pass, endpoint returns 201 for valid input + + src/routes/auth/register.ts created and tested + + + + + User confirms: registration endpoint works via manual test + + User verified registration flow works end-to-end + +``` + +--- + +## 五、五大核心方法论 + +### 1. Dream Extraction（梦想提取） + +项目初始化使用"协作思考"而非"需求收集"。 + +``` +传统方式: + 产品经理: "请列出你的需求" + 开发者: "我需要用户认证、支付..." + +GSD 方式: + Claude: "你在构建什么？解决什么真实问题？" + 开发者: "我想让自由职业者更容易管理发票..." + Claude: "当你说'更容易'——现在最痛苦的部分是什么？" + 开发者: "手动追踪哪些发票已付款、哪些逾期" + Claude: "所以核心价值是自动追踪支付状态。 + '完成'对你来说长什么样？" + → 从模糊想法中提取出具体的、可执行的需求 +``` + +**原则**: "你是思考伙伴，不是采访者。" 系统探测模糊性、让抽象变具体。 + +### 2. Goal-Backward Verification（目标回溯验证） + +GSD 的核心验证哲学: **"任务完成 ≠ 目标达成"**。从应该交付的东西开始，反向验证它是否真实存在。 + +**四级验证**: + +``` +Level 1 - Exists: 文件在预期路径？ +Level 2 - Substantive: 是真实实现还是桩代码/占位符？ +Level 3 - Wired: 与系统其他部分连接了？（import 被使用、API 被调用、数据流通） +Level 4 - Functional: 实际调用时能工作？（通常需要人类验证） +``` + +**桩代码检测模式**: + +``` +React 组件: + ❌ return
TODO
+ ❌ return + ✓ return
...
+ +API 路由: + ❌ res.json({ message: "not implemented" }) + ❌ throw new Error("TODO") + ✓ const user = await db.user.create(...) + +数据库 Schema: + ❌ 只有 id 和 createdAt 字段 + ✓ 包含所有业务字段 + 索引 + 约束 +``` + +**应用层级**: + +| 阶段 | 验证者 | 问的问题 | +|------|--------|---------| +| 执行前 | gsd-plan-checker | 计划能**交付**目标吗？| +| 执行后 | gsd-verifier | 执行**达成**了目标吗？| +| 跨阶段 | gsd-integration-checker | 阶段之间**连接**正确吗？| +| 最终 | 人类 UAT | 它真的**能用**吗？| + +### 例子 — 验证报告 + +```markdown +# VERIFICATION.md — Phase 1: User Authentication + +## Goal +Users can register, login, and access protected routes. + +## Observable Truths (从用户角度) +1. New user can register with email + password +2. Registered user can login and receive JWT +3. Protected routes reject unauthenticated requests +4. Protected routes accept valid JWT + +## Verification Results + +| Truth | Exists | Substantive | Wired | Status | +|-------|--------|-------------|-------|--------| +| Registration | ✅ POST /auth/register | ✅ Real bcrypt + DB write | ✅ Called from signup form | PASS | +| Login | ✅ POST /auth/login | ✅ Password compare + JWT sign | ✅ Called from login form | PASS | +| Route protection | ✅ authMiddleware.ts | ✅ JWT verify + user lookup | ⚠️ Not applied to /api/admin/* | GAP | +| JWT validation | ✅ Token generation | ✅ RS256 signing | ✅ Middleware uses it | PASS | + +## Gaps +1. **GAP-01**: authMiddleware not applied to admin routes + - Severity: HIGH + - Fix: Add middleware to admin router in src/routes/admin/index.ts + +## Verdict: PARTIAL PASS (3/4 truths verified, 1 gap) +``` + +### 3. Nyquist Validation（奈奎斯特验证） + +命名来自信号处理的**奈奎斯特采样定理**: 要忠实重建信号，采样率需要 2x 以上。类比: 要忠实验证实现，每个需求都需要对应的自动化测试反馈。 + +``` +原则: AI 生成器越自主，验证、可追溯性和回滚的投资就越大 + +需求 REQ-01 → 必须有自动化测试覆盖 +需求 REQ-02 → 必须有自动化测试覆盖 +... +``` + +**缺口分类**: + +| 分类 | 含义 | +|------|------| +| COVERED | 测试存在、覆盖行为、运行通过 | +| PARTIAL | 测试存在但失败或不完整 | +| MISSING | 没有找到测试 | + +**例子 — Nyquist 验证报告**: + +```markdown +# VALIDATION.md — Phase 1 + +## Coverage Matrix + +| Requirement | Test File | Status | Notes | +|-------------|-----------|--------|-------| +| REQ-01: User registration | tests/auth/register.test.ts | COVERED | 5 test cases | +| REQ-02: Email verification | tests/auth/verify-email.test.ts | COVERED | 3 test cases | +| REQ-03: Login flow | tests/auth/login.test.ts | COVERED | 4 test cases | +| REQ-04: Password reset | — | MISSING | No test file found | +| REQ-05: Rate limiting | tests/middleware/rate-limit.test.ts | PARTIAL | Only tests 429 status, not cooldown | + +## Actions Taken +- Generated: tests/auth/password-reset.test.ts (4 test cases for REQ-04) +- Extended: tests/middleware/rate-limit.test.ts (added cooldown verification for REQ-05) + +## Result: 5/5 COVERED (was 3/5 before audit) +``` + +**关键约束**: gsd-nyquist-auditor **从不修改实现代码** — 只创建/修改测试文件和 VALIDATION.md。实现 Bug 被上报而非修复。 + +### 4. Wave Execution（波浪式执行） + +计划按依赖关系分组为"波浪"，波浪内并行执行，波浪间串行。 + +``` +Phase 1 有 4 个计划: + Plan A: 数据库 Schema (无依赖) + Plan B: API 框架 (无依赖) + Plan C: 认证路由 (依赖 A + B) + Plan D: 前端登录页 (依赖 C) + +执行: + Wave 1: [Plan A, Plan B] ← 并行（2 个独立 executor，各自全新 200K 上下文） + Wave 2: [Plan C] ← 等 Wave 1 完成后执行 + Wave 3: [Plan D] ← 等 Wave 2 完成后执行 + +编排器上下文使用: 仅 30-40%（瘦编排器模式） +执行器上下文使用: 每个 0-50%（全新窗口，最佳质量区间） +``` + +**并行安全**: 并行执行器使用 `--no-verify` 避免 pre-commit hook 锁竞争。编排器在每个波浪完成后统一运行 hooks。 + +**STATE.md 文件锁**: 使用 `O_EXCL` 原子创建 `STATE.md.lock` 防止并行写入竞争。 + +### 5. Checkpoint System（检查点系统） + +形式化的人机交互点: + +| 类型 | 频率 | 含义 | +|------|------|------| +| **human-verify** | 90% | Claude 自动化完成，人类确认结果可用 | +| **decision** | ~8% | 用户在选项中做选择，Claude 实施 | +| **human-action** | ~2% | 需要人类判断的事（认证、视觉检查、秘钥配置）| + +**黄金法则**: "如果 Claude 能运行，Claude 就运行。" 检查点只用于验证和决策。 + +**Auto-mode**: 自动跳过 human-verify 和 decision 检查点，但**永不**跳过 human-action。 + +### 例子 — 检查点交互 + +``` +# executor 遇到 human-verify 检查点: +┌────────────────────────────────────────┐ +│ CHECKPOINT: human-verify │ +│ │ +│ Task 3 of Plan A completed. │ +│ Created: src/routes/auth/register.ts │ +│ │ +│ Please verify: │ +│ 1. POST /api/auth/register returns 201 │ +│ 2. User appears in database │ +│ 3. Verification email received │ +│ │ +│ [Continue] [Fix Issues] [Skip] │ +└────────────────────────────────────────┘ + +# executor 遇到 decision 检查点: +┌────────────────────────────────────────┐ +│ CHECKPOINT: decision │ +│ │ +│ JWT token expiry strategy: │ +│ A) Short-lived (15min) + refresh token │ +│ B) Long-lived (7 days), no refresh │ +│ C) Session-based, no JWT │ +│ │ +│ Your choice: [A/B/C] │ +└────────────────────────────────────────┘ + +# executor 遇到 human-action 检查点: +┌────────────────────────────────────────┐ +│ CHECKPOINT: human-action │ +│ │ +│ I need you to: │ +│ 1. Create a SendGrid account │ +│ 2. Generate an API key │ +│ 3. Set SENDGRID_API_KEY in .env │ +│ │ +│ [Done, continue] │ +└────────────────────────────────────────┘ +``` + +--- + +## 六、状态管理与会话持续性 + +### STATE.md — 项目短期记忆 + +```markdown +# Project State + +**Phase:** 2 of 5 +**Plan:** B of 3 +**Status:** executing +**Velocity:** 1.2 plans/hour +**Last Session:** 2026-03-20 09:30 + +## Recent Decisions +- REQ-03: Use JWT with refresh tokens (user choice) +- Database: PostgreSQL via Prisma (CONTEXT.md) + +## Blockers +- None + +## Pending Todos +- [ ] Add rate limiting to payment endpoints +- [ ] Review admin panel permissions +``` + +### 会话暂停/恢复 + +```bash +# 暂停工作（保存完整状态） +/gsd:pause-work +# → 生成 HANDOFF.json (机器可读): +# { +# "current_task": "Plan B, Task 2", +# "completed": ["Plan A (all tasks)", "Plan B Task 1"], +# "remaining": ["Plan B Task 2-3", "Plan C"], +# "decisions": [...], +# "blockers": [], +# "uncommitted_files": ["src/api/payment.ts"] +# } +# → 生成 .continue-here.md (人类可读): +# "你在做 Phase 2 Plan B 的第 2 个任务..." + +# 恢复工作（在新会话中） +/gsd:resume-work +# → 读 HANDOFF.json → 重建上下文 → 从断点继续 +# → 如果 HANDOFF.json 丢失 → 回退到 .continue-here.md +# → 如果都丢失 → 从 artifacts 重建 +``` + +### 上下文监控 Hook + +``` +Context Monitor（PostToolUse hook）: + ≤35% 剩余 → WARNING: "请准备收尾当前任务" + ≤25% 剩余 → CRITICAL: "立即保存状态，执行 /gsd:pause-work" + 防抖: 每 5 次工具调用之间最多 1 次警告 + 严重度升级时绕过防抖 +``` + +--- + +## 七、Git 集成 + +**核心原则**: "提交结果，不是过程。" + +| 事件 | 提交？ | +|------|--------| +| 项目初始化（brief + roadmap）| YES | +| PLAN.md / RESEARCH.md 创建 | NO（中间产物）| +| 每个任务完成 | YES（原子提交）| +| 计划完成（元数据更新）| YES | +| 暂停/恢复 | YES（WIP）| + +**提交格式**: `{type}({phase}-{plan}): {description}` + +``` +feat(1-A): add User model with Prisma schema +feat(1-A): implement POST /auth/register endpoint +test(1-A): add registration flow tests +feat(1-B): add JWT authentication middleware +fix(1-C): apply auth middleware to admin routes +``` + +**分支策略**: + +| 策略 | 说明 | 适用场景 | +|------|------|---------| +| `none` | 提交到当前分支（默认）| 个人项目 | +| `phase` | 每阶段一个分支 | 需要阶段级 PR 审查 | +| `milestone` | 每里程碑一个分支 | 需要版本级 PR 审查 | + +--- + +## 八、配置系统 + +### config.json 完整配置 + +```json +{ + "mode": "interactive", // interactive | yolo + "granularity": "standard", // coarse | standard | fine + "model_profile": "balanced", // quality | balanced | budget | inherit + "workflow": { + "research": true, // 执行前研究 + "plan_check": true, // 计划质量验证 + "verifier": true, // 执行后验证 + "auto_advance": false, // 自动推进到下一阶段 + "nyquist_validation": true // 奈奎斯特测试验证 + }, + "planning": { + "commit_docs": true, // 提交规划文档 + "search_gitignored": false // 搜索 gitignored 文件 + }, + "parallelization": { + "enabled": true, + "plan_level": true, // 计划级并行 + "task_level": false, // 任务级并行（默认关闭） + "max_concurrent_agents": 3, + "min_plans_for_parallel": 2 + }, + "gates": { + "confirm_project": true, // 确认项目初始化 + "confirm_phases": true, // 确认阶段划分 + "confirm_roadmap": true, // 确认路线图 + "confirm_plan": true, // 确认计划 + "execute_next_plan": true // 确认执行下一计划 + }, + "safety": { + "always_confirm_destructive": true, + "always_confirm_external_services": true + }, + "git": { + "branching_strategy": "none" // none | phase | milestone + } +} +``` + +**配置层级**: 项目 `.planning/config.json` > 全局 `~/.gsd/defaults.json` > 内置默认值 + +--- + +## 九、命令速查（37+ 个） + +### 核心工作流 + +| 命令 | 用途 | +|------|------| +| `/gsd:new-project` | 初始化新项目（提问 → 研究 → 需求 → 路线图）| +| `/gsd:discuss-phase N` | 讨论阶段偏好（→ CONTEXT.md）| +| `/gsd:plan-phase N` | 规划阶段（研究 → 计划 → 验证循环）| +| `/gsd:execute-phase N` | 波浪式并行执行所有计划 | +| `/gsd:verify-work N` | 目标回溯验证 | +| `/gsd:validate-phase N` | Nyquist 测试覆盖验证 | +| `/gsd:ship N` | 创建 PR | +| `/gsd:next` | 自动推进到下一步 | +| `/gsd:quick "描述"` | 快速任务（跳过完整规划）| +| `/gsd:autonomous` | 自主运行所有剩余阶段 | + +### 阶段管理 + +| 命令 | 用途 | +|------|------| +| `/gsd:add-phase "描述"` | 添加新阶段到路线图末尾 | +| `/gsd:insert-phase N "描述"` | 在 N 后插入小数阶段（如 2.1）| +| `/gsd:remove-phase N` | 移除阶段并重新编号 | +| `/gsd:list-phase-assumptions N` | 列出 Claude 对阶段的假设 | + +### 里程碑管理 + +| 命令 | 用途 | +|------|------| +| `/gsd:audit-milestone` | 审计里程碑完成度 | +| `/gsd:complete-milestone` | 归档里程碑，打 tag | +| `/gsd:new-milestone` | 开始新版本 | +| `/gsd:plan-milestone-gaps` | 为审计发现的缺口创建补充阶段 | + +### 会话与导航 + +| 命令 | 用途 | +|------|------| +| `/gsd:pause-work` | 暂停并保存完整状态 | +| `/gsd:resume-work` | 从断点恢复 | +| `/gsd:progress` | 查看当前进度 | +| `/gsd:stats` | 显示项目统计 | +| `/gsd:session-report` | 生成会话报告（token、工作摘要）| + +### 分析与调试 + +| 命令 | 用途 | +|------|------| +| `/gsd:map-codebase` | 分析现有代码库（棕地项目必用）| +| `/gsd:debug` | 科学方法 Bug 调查 | +| `/gsd:health` | 项目健康检查 | + +### 杂项 + +| 命令 | 用途 | +|------|------| +| `/gsd:settings` | 配置 GSD | +| `/gsd:set-profile` | 切换模型配置文件 | +| `/gsd:add-todo` | 捕获想法为 todo | +| `/gsd:check-todos` | 查看待办事项 | +| `/gsd:note` | 零摩擦笔记捕获 | +| `/gsd:do "文本"` | 路由自由文本到正确的 GSD 命令 | +| `/gsd:help` | 显示帮助 | +| `/gsd:update` | 更新 GSD 框架 | + +--- + +## 十、社区最佳实践 + +### 开始之前 + +1. **准备详细的项目描述**: 包括目标、用户、核心功能、约束、技术栈偏好。模糊描述会触发过多追问。 +2. **棕地项目必须先跑 `/gsd:map-codebase`**: 避免与现有模式冲突。 +3. **预算充足**: Max plan ($100-200/月) 是常规使用的推荐。GSD 的多 Agent 架构消耗 token 较高。 + +### 工作中 + +4. **永远不要跳过 `/gsd:discuss-phase`**: 花 5-10 分钟在这里可以节省数小时。大多数计划质量问题源于 Claude 在 CONTEXT.md 中缺少用户决策。 +5. **计划保持 2-3 个任务**: 每个适配 ~50% 的全新上下文窗口。更大的任务超出单个上下文窗口能可靠产出的范围。 +6. **小任务用 `/gsd:quick`**: 完整工作流对修错别字、改颜色等小事是大材小用。 +7. **用 `/gsd:add-todo` 捕获灵感**: 而不是打断当前工作。 +8. **用 `/gsd:progress` 检查位置**: 随时了解当前在哪、下一步做什么。 +9. **阶段间清理上下文**: 保持编排器在 30-40% 使用率的最佳区间。 + +### 验证 + +10. **启用 Nyquist 验证**: 在代码写之前就映射测试覆盖到每个需求，确保秒级反馈循环。 +11. **不要信任 SUMMARY.md**: 验证器会检查实际代码而非声称。 +12. **视觉规格优于纯文本规格**: 带热点的屏幕截图 mockup 比纯文字描述产出更好的结果。 + +--- + +## 十一、常见陷阱 + +| 陷阱 | 影响 | 解决方案 | +|------|------|---------| +| 小改动用完整工作流 | 浪费时间和 token | 用 `/gsd:quick` | +| 跳过 discuss-phase | 计划基于 Claude 的假设而非你的决策 | 始终先 `/gsd:discuss-phase` | +| 计划任务过多 | 超出单个上下文窗口能力 | 限制 2-3 任务/计划 | +| Token 预算耗尽 | 工作中断 | 预算 Max plan；小任务用 quick | +| 棕地项目不扫描 | 与现有代码模式冲突 | 先跑 `/gsd:map-codebase` | +| 上下文累积不清理 | 违背 GSD 核心优势 | 阶段间确保全新上下文 | +| 执行失败后重跑整个阶段 | 浪费。修复应更精准 | 用 `/gsd:quick` 修复或 `/gsd:verify-work` 定位 | +| CLAUDE.md 冲突 | GSD 规则未正确加载 | 手动确保 GSD 规则存在于 CLAUDE.md | + +--- + +## 十二、GSD 独特创新 + +| 创新 | 说明 | +|------|------| +| **Plans as Prompts** | PLAN.md 不是文档变成 prompt，它**就是** prompt。XML 结构直接指导执行 | +| **Dream Extraction** | "协作思考"代替"需求收集"，从模糊想法提取可执行需求 | +| **Nyquist Validation** | 借鉴信号处理定理，每个需求必须有自动化测试反馈 | +| **Goal-Backward Verification** | 从用户可观察的结果反向推导验证（非正向检查任务完成度）| +| **Context Bridge Architecture** | statusline hook 写指标到临时文件，context monitor 读取。解耦的桥接允许跨 hook 通信 | +| **Deviation Handling** | 执行器自动处理计划偏差，适应而非失败 | +| **gsd-tools.cjs** | Node.js CLI 工具（15 模块，100+ 命令），分离确定性逻辑和 AI 推理 | +| **User Profiling** | 8 维度行为分析，个性化工作流响应 | +| **Quick Mode Composable Flags** | `--discuss`, `--research`, `--full` 自由组合临时任务的规划深度 | +| **Multi-Runtime Abstraction** | 安装时转换支持 6 种 AI 运行时（工具名、hook 事件、Agent 前言、路径约定）| + +--- + +## 十三、实战例子 + +### 例子: 棕地项目 — 给现有 SaaS 加支付功能 + +```bash +# Step 0: 扫描现有代码库 +/gsd:map-codebase +# → 4 个并行 mapper 分析: +# tech: Next.js 14 + Prisma + PostgreSQL + Tailwind +# arch: App Router, server components, API routes in /api/ +# quality: 72% test coverage, ESLint + Prettier configured +# concerns: No rate limiting, N+1 queries in /api/users + +# Step 1: 初始化项目（GSD 会读取 codebase 分析） +/gsd:new-project +# → "你在给现有 SaaS 加什么功能？" +# → "支付处理: Stripe 订阅 + 一次性付款" +# → 生成 ROADMAP.md: +# Phase 1: Stripe 集成基础（webhook + 客户同步） +# Phase 2: 订阅管理（创建/升级/降级/取消） +# Phase 3: 一次性付款（checkout session） +# Phase 4: 账单历史 + 发票 UI + +# Step 2: 讨论 Phase 1 +/gsd:discuss-phase 1 +# → "Stripe API version: 2024-12-18 还是 latest?" +# → "Webhook 签名验证: 同步还是异步?" +# → "失败重试策略: 指数退避还是固定间隔?" +# → 决策锁定到 CONTEXT.md + +# Step 3: 规划 +/gsd:plan-phase 1 +# → RESEARCH.md: Stripe Next.js 集成最佳实践 +# → Plan A: Stripe SDK setup + webhook endpoint +# → Plan B: Customer sync (User ↔ Stripe Customer) +# → Plan-checker 验证: +# ✓ CONTEXT.md 决策被尊重 +# ✓ REQ-01 到 REQ-04 都有对应任务 +# ✓ 每个 plan ≤ 50% 上下文预算 + +# Step 4: 执行 +/gsd:execute-phase 1 +# Wave 1: [Plan A, Plan B] 并行 +# Executor A (全新 200K context): +# Task 1: npm install stripe → commit +# Task 2: POST /api/webhooks/stripe → commit +# Task 3: human-verify: 测试 webhook 签名 +# Executor B (全新 200K context): +# Task 1: Prisma schema add stripeCustomerId → commit +# Task 2: Customer sync service → commit + +# Step 5: 验证 +/gsd:verify-work 1 +# → Exists: ✅ webhook endpoint, customer sync service +# → Substantive: ✅ Real Stripe API calls, not mocks +# → Wired: ⚠️ webhook handler dispatches events but +# subscription.updated handler is empty stub +# → GAP-01: subscription.updated handler needs implementation +# (will be covered in Phase 2) + +# Step 6: Nyquist 验证 +/gsd:validate-phase 1 +# → REQ-01 (Stripe setup): COVERED — test/stripe/setup.test.ts +# → REQ-02 (Webhook verify): COVERED — test/api/webhook.test.ts +# → REQ-03 (Customer sync): PARTIAL — test exists but no edge cases +# → REQ-04 (Error handling): MISSING +# → Auditor generates: test/stripe/error-handling.test.ts +# → Auditor extends: test/stripe/customer-sync.test.ts +``` + +### 例子: Bug 调试工作流 + +```bash +/gsd:debug +# → "描述你遇到的问题" +# → "用户点击'升级订阅'后页面白屏" + +# gsd-debugger 使用科学方法: +# 1. 假设: React 渲染错误（未捕获的异常） +# 测试: 检查浏览器控制台 +# 结果: TypeError: Cannot read property 'id' of undefined +# → 假设部分确认 + +# 2. 假设: subscription 对象在某些条件下为 null +# 测试: grep subscription 使用处 +# 结果: src/components/UpgradeModal.tsx:45 +# const planId = subscription.currentPlan.id ← 无空值检查 +# → 根因确认 + +# 3. 修复: +# if (!subscription?.currentPlan) { +# return ; +# } + +# 4. 验证: +# → 添加回归测试 +# → 原子提交: fix(2-A): handle null subscription in UpgradeModal + +# 调试状态持久化到 DEBUG.md（跨会话保留） +``` + +### 例子: 快速任务 + +```bash +# 小改动不需要完整工作流 +/gsd:quick "把登录按钮颜色从蓝色改成品牌紫色 #7C3AED" +# → 直接执行，原子提交 +# → 跳过: research, plan-check, verification +# → 保留: 状态追踪, git commit + +# 需要一点研究的快速任务 +/gsd:quick --research "添加 dark mode 支持" +# → 研究: Tailwind dark mode 最佳实践 +# → 执行: 添加 dark: 变体 +# → 原子提交 + +# 需要讨论的快速任务 +/gsd:quick --discuss "重构用户表添加团队支持" +# → 讨论: "多对多还是多对一？" +# → 执行: Schema migration + model update +# → 原子提交 +``` + +--- + +## 十四、与其他框架对比 + +| 维度 | GSD | ECC | BMAD | SpecKit | Plain Plan Mode | +|------|-----|-----|------|---------|-----------------| +| 定位 | 规格驱动开发 | Agent harness 优化 | 敏捷团队模拟 | 开发者工具包 | 内置功能 | +| Stars | 36K+ | 50K+ | ~5K | 72.7K | N/A | +| 核心优势 | 上下文隔离（全新窗口/任务）| 持续学习 + Hook 驱动 | 完整敏捷流程 | 灵活可定制 | 零开销 | +| Token 成本 | 高（多 Agent 生成）| 中-高 | 高 | 低 | 最低 | +| 适合场景 | 复杂多阶段项目 | 日常重度开发 | 企业敏捷团队 | GitHub 生态用户 | 简单任务 | +| 学习曲线 | 中等（1小时上手）| 陡峭 | 陡峭 | 平缓 | 无 | +| 验证体系 | 目标回溯 + Nyquist | Verification Loop | Scrum review | 手动 | 无 | +| 上下文管理 | 激进隔离（全新窗口）| 策略性压缩 | 无特殊处理 | 无特殊处理 | 自动压缩 | +| 会话持续性 | HANDOFF.json + STATE.md | Memory 系统 | 无 | 无 | 无 | + +**选择建议**: + +- **GSD**: 构建完整产品、多阶段项目、需要严格验证 +- **ECC**: 日常编码、持续改进、多语言多项目 +- **两者结合**: GSD 做项目管理和规划，ECC 做代码质量和学习（你当前的配置） +- **Plain Plan Mode**: 单文件修改、简单 Bug 修复 + +--- + +## 十五、关键数据 + +- GitHub Stars: 36K+ +- 版本: v1.26.0 +- Agents: 16 个 +- 命令: 37+ 个 +- 工作流: 44 个 +- 模板: 50+ 个 +- gsd-tools 命令: 100+ +- 活跃 Discord: 1,200+ 成员 +- 支持运行时: 6 种（Claude Code, OpenCode, Gemini CLI, Codex, Copilot, Antigravity） +- 许可: 开源 + +--- + +## Related + +- [[Everything Claude Code 完整指南]] +- [[Everything Claude Code 用法速查]] +- [[Everything Claude Code 方法论与最佳实践]] diff --git a/6 - Zettelkasten/20260320100100 上下文腐烂与全新窗口隔离.md b/6 - Zettelkasten/20260320100100 上下文腐烂与全新窗口隔离.md new file mode 100644 index 0000000..f30e6f7 --- /dev/null +++ b/6 - Zettelkasten/20260320100100 上下文腐烂与全新窗口隔离.md @@ -0,0 +1,29 @@ +--- +created: "2026-03-20 10:01" +type: zettel +tags: [claude-code, context-window, ai-quality, gsd] +source: "https://github.com/gsd-build/get-shit-done" +--- + +# 上下文腐烂与全新窗口隔离 + +AI 编码 Agent 的输出质量随上下文填充率非线性下降: + +- 0-30%: 峰值质量 +- 50%+: 开始赶工 +- 70%+: 幻觉风险显著增加 + +GSD 的解决方案是**激进隔离**: 每个任务执行器获得全新的 200K token 上下文窗口，编排器保持在 30-40% 使用率。这与 ECC 的"策略性压缩"（在逻辑节点手动 `/compact`）形成对比。 + +两种方法的权衡: +- **全新窗口**: 质量最佳，但 token 成本高（每个 Agent 独立 API 调用） +- **策略性压缩**: 成本低，但依赖人类判断何时压缩，且压缩可能丢失关键上下文 + +理想方案可能是两者结合: 对复杂多阶段项目用 GSD 的窗口隔离，对日常编码用 ECC 的策略压缩。 + +--- + +## Related + +- [[GSD 方法论与最佳实践]] +- [[MCP数量与上下文窗口的反比关系]] diff --git a/6 - Zettelkasten/20260320100200 目标回溯验证vs正向任务检查.md b/6 - Zettelkasten/20260320100200 目标回溯验证vs正向任务检查.md new file mode 100644 index 0000000..5afb7cd --- /dev/null +++ b/6 - Zettelkasten/20260320100200 目标回溯验证vs正向任务检查.md @@ -0,0 +1,27 @@ +--- +created: "2026-03-20 10:02" +type: zettel +tags: [verification, methodology, ai-quality, gsd] +source: "https://github.com/gsd-build/get-shit-done" +--- + +# 目标回溯验证 vs 正向任务检查 + +传统软件验证是正向的: "任务 1 完成了吗？任务 2 完成了吗？全部完成 = 目标达成。" 这隐含假设任务列表是完备的。 + +GSD 的目标回溯验证(Goal-Backward Verification)反转方向: "用户应该能做什么？这个能力在代码中存在吗？不仅存在，还是真实实现（非桩代码）？不仅实现了，还与系统连接了？" + +四级验证层次: +1. Exists — 文件在预期路径 +2. Substantive — 真实实现，非 TODO/placeholder +3. Wired — 与系统其他部分连接（import 被使用，API 被调用） +4. Functional — 实际调用时能工作 + +这对 AI 生成代码尤其重要: LLM 擅长生成"看起来正确"的代码（通过 Level 1-2），但经常遗漏连接（Level 3）。GSD 的桩代码检测模式专门针对这一弱点。 + +--- + +## Related + +- [[GSD 方法论与最佳实践]] +- [[Hook驱动优于提示词驱动]] diff --git a/6 - Zettelkasten/20260320100300 Plans as Prompts设计模式.md b/6 - Zettelkasten/20260320100300 Plans as Prompts设计模式.md new file mode 100644 index 0000000..0da6327 --- /dev/null +++ b/6 - Zettelkasten/20260320100300 Plans as Prompts设计模式.md @@ -0,0 +1,27 @@ +--- +created: "2026-03-20 10:03" +type: zettel +tags: [prompt-engineering, ai-architecture, gsd] +source: "https://github.com/gsd-build/get-shit-done" +--- + +# Plans as Prompts 设计模式 + +GSD 中 PLAN.md 不是"被转化为 prompt 的文档"——它**就是** prompt。XML 结构（``, ``, ``, ``）直接指导执行器的行为。 + +这个设计消除了"文档到 prompt 的翻译损失": 传统方式需要一个中间步骤把文档理解为指令，每次翻译都引入歧义。Plans as Prompts 让计划者直接写执行指令，跳过翻译。 + +关键约束使这成为可能: +- 每个计划 ≤ 50% 上下文预算（确保执行器有足够空间思考） +- XML 结构强制精确性（不是自然语言的模糊描述） +- `` 块要求每个任务都有可执行的验证命令 +- `` 块定义明确的完成状态 + +更广泛的启示: 当 AI Agent 是执行者时，规划文档应该以 Agent 的"母语"（结构化 prompt）书写，而非以人类的可读性为优先。 + +--- + +## Related + +- [[GSD 方法论与最佳实践]] +- [[目标回溯验证vs正向任务检查]]