mirror of
https://github.com/GuDaStudio/commands.git
synced 2026-03-22 19:18:52 +08:00
377 lines
20 KiB
Markdown
377 lines
20 KiB
Markdown
---
|
||
name: GudaSpec: Init
|
||
description: Initialize GudaSpec environment with directory structure and MCP tools validation.
|
||
category: GudaSpec
|
||
tags: [gudaspec, init, setup, mcp, rpi]
|
||
---
|
||
|
||
<!-- GUDASPEC:INIT:START -->
|
||
|
||
## Purpose
|
||
|
||
初始化GudaSpec环境，创建目录结构，验证MCP工具可用性，输出GudaSpec简介。
|
||
|
||
## Guardrails
|
||
|
||
- Detect the current operating system and adapt commands accordingly.
|
||
- Do not proceed to the next step until the current step completes successfully.
|
||
- Provide clear, actionable error messages when a step fails.
|
||
- Respect user's existing configurations and avoid overwriting without confirmation.
|
||
|
||
---
|
||
|
||
## Steps
|
||
|
||
### Step 1: Detect Environment
|
||
|
||
```bash
|
||
# 检测操作系统
|
||
uname -s 2>/dev/null || echo "Windows"
|
||
|
||
# 检测当前目录
|
||
pwd
|
||
```
|
||
|
||
Report detected environment:
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
🔍 环境检测
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
| 项目 | 检测结果 |
|
||
|------|----------|
|
||
| 操作系统 | <OS> |
|
||
| 当前目录 | <path> |
|
||
| Git仓库 | <yes/no> |
|
||
```
|
||
|
||
---
|
||
|
||
### Step 2: Check Existing GudaSpec Installation
|
||
|
||
```bash
|
||
# 检查是否已存在gudaspec目录
|
||
if [ -d "gudaspec" ]; then
|
||
echo "GUDASPEC_EXISTS=true"
|
||
ls -la gudaspec/
|
||
else
|
||
echo "GUDASPEC_EXISTS=false"
|
||
fi
|
||
```
|
||
|
||
**If gudaspec/ exists:**
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
⚠️ 检测到已有GudaSpec安装
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
现有目录结构:
|
||
gudaspec/
|
||
├── research/ (<N>个需求)
|
||
├── plans/ (<N>个计划)
|
||
└── archive/ (<N>个归档)
|
||
```
|
||
|
||
Use `AskUserQuestions`:
|
||
```
|
||
question: "如何处理现有安装？"
|
||
options: [
|
||
"保留现有数据，仅验证MCP工具",
|
||
"重新初始化（现有数据将移动到backup/）",
|
||
"取消初始化"
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### Step 3: Create GudaSpec Directory Structure
|
||
|
||
```bash
|
||
# 创建目录结构
|
||
mkdir -p gudaspec/{research,plans,archive}
|
||
|
||
# 创建初始化标记文件
|
||
cat > gudaspec/.gudaspec.json << 'EOF'
|
||
{
|
||
"version": "1.0.0",
|
||
"initialized_at": "<ISO timestamp>",
|
||
"initialized_by": "claude",
|
||
"test_level_default": 1
|
||
}
|
||
EOF
|
||
```
|
||
|
||
Verify creation:
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
📁 目录结构创建
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
gudaspec/
|
||
├── .gudaspec.json ✅ 配置文件
|
||
├── research/ ✅ 研究文档目录
|
||
├── plans/ ✅ 计划文档目录
|
||
└── archive/ ✅ 归档目录
|
||
|
||
目录结构创建: ✅ 完成
|
||
```
|
||
|
||
---
|
||
|
||
### Step 4: Validate MCP Tools Availability
|
||
|
||
Check each required MCP tool:
|
||
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
🔧 MCP工具验证
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
```
|
||
|
||
**Check Codex MCP:**
|
||
- Attempt to invoke `mcp__codex__codex` with a simple test query
|
||
- Record availability status
|
||
|
||
**Check Gemini MCP:**
|
||
- Attempt to invoke `mcp__gemini__gemini` with a simple test query
|
||
- Record availability status
|
||
|
||
**Check Grok Search MCP:**
|
||
- Attempt to invoke `mcp__grok-search` with a simple test query
|
||
- Record availability status
|
||
|
||
**Display results:**
|
||
```
|
||
| MCP工具 | 状态 | 用途 |
|
||
|---------|------|------|
|
||
| mcp__codex__codex | ✅ / ❌ | 后端逻辑实现与审查 |
|
||
| mcp__gemini__gemini | ✅ / ❌ | 前端UI实现与审查 |
|
||
| mcp__grok-search | ✅ / ❌ | 实时在线搜索 |
|
||
```
|
||
|
||
**For each unavailable tool, display installation instructions:**
|
||
|
||
```
|
||
【缺失工具安装指南】
|
||
|
||
❌ mcp__codex__codex 不可用
|
||
用途: GudaSpec使用Codex作为后端逻辑实现引擎和代码审查器
|
||
安装: https://github.com/GuDaStudio/codexmcp
|
||
|
||
❌ mcp__gemini__gemini 不可用
|
||
用途: GudaSpec使用Gemini作为前端UI设计引擎和代码审查器
|
||
安装: https://github.com/GuDaStudio/geminimcp
|
||
|
||
❌ mcp__grok-search 不可用
|
||
用途: GudaSpec使用Grok Search进行实时在线文档搜索
|
||
安装: https://github.com/GuDaStudio/GrokSearch
|
||
```
|
||
|
||
---
|
||
|
||
### Step 5: Summary Report
|
||
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
📊 初始化总结
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
【环境状态】
|
||
| 项目 | 状态 |
|
||
|------|------|
|
||
| GudaSpec目录 | ✅ 已创建 |
|
||
| mcp__codex__codex | ✅ / ❌ |
|
||
| mcp__gemini__gemini | ✅ / ❌ |
|
||
| mcp__grok-search | ✅ / ❌ |
|
||
|
||
【功能可用性】
|
||
| 功能 | 状态 | 依赖 |
|
||
|------|------|------|
|
||
| 内部研究 (Research) | ✅ | - |
|
||
| 外部调研 (Deep Research) | ✅ / ⚠️ | Grok Search |
|
||
| 计划制定 (Plan) | ✅ | - |
|
||
| 后端实现 | ✅ / ⚠️ | Codex |
|
||
| 前端实现 | ✅ / ⚠️ | Gemini |
|
||
| 多模型审查 | ✅ / ⚠️ | Codex + Gemini |
|
||
|
||
⚠️ = 功能可用但体验受限（缺少对应MCP工具）
|
||
```
|
||
|
||
**If any tools missing:**
|
||
```
|
||
【待处理事项】
|
||
请安装缺失的MCP工具以获得完整功能：
|
||
1. <missing tool> — <installation url>
|
||
2. ...
|
||
```
|
||
|
||
---
|
||
|
||
### Step 7: Output GudaSpec Introduction
|
||
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
GudaSpec 简介
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
GudaSpec 是基于 RPI (Research-Plan-Implementation) 编码理论的 Claude Code
|
||
自定义命令集，融合多模型协作与TDD测试驱动开发，专为复杂场景设计。
|
||
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 核心理念 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 📊 RPI工作流 │
|
||
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
|
||
│ │ RESEARCH │───▶│ PLAN │───▶│ IMPLEMENT │ │
|
||
│ │ 需求研究 │ │ 计划制定 │ │ 代码实现 │ │
|
||
│ └───────────────┘ └───────────────┘ └───────────────┘ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ ▼ │
|
||
│ 约束集文档 规格文档 可运行代码 │
|
||
│ │
|
||
│ 🎯 核心原则 │
|
||
│ • 有效上下文专注 — 通过阶段分离极致利用上下文窗口（保持40-60%利用率） │
|
||
│ • 频繁意向压缩 — 每阶段产出紧凑文档，/clear后作为下阶段种子 │
|
||
│ • 高杠杆审查点 — 审查规格而非代码，一行错误规格=百行错误代码 │
|
||
│ │
|
||
│ 🔧 多模型协作 │
|
||
│ • Codex — 后端逻辑实现与审查 │
|
||
│ • Gemini — 前端UI实现与审查 │
|
||
│ • Grok — 实时在线搜索与文档查询 │
|
||
│ • 双模型LGTM — 交叉审查确保代码质量 │
|
||
│ │
|
||
│ 🧪 TDD测试驱动（可选） │
|
||
│ • Level 0: 标准验证（Success Criteria） │
|
||
│ • Level 1: TDD模式（Red-Green-Refactor） │
|
||
│ • Level 2: TDD + Property Testing（发现边界情况） │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 命令速查 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 【Research阶段】将需求转化为约束集 │
|
||
│ ┌─────────────────────────────────────────────────────────────────────────┐│
|
||
│ │ /gudaspec:research │ 内部研究：分析代码库约束 ││
|
||
│ │ /gudaspec:research-review <id> │ 内部审查：确认约束，判断是否需外部 ││
|
||
│ │ /gudaspec:deepresearch <id> │ 外部研究：调研技术选型与最佳实践 ││
|
||
│ │ /gudaspec:deep-research-review <id> │ 外部审查：确认选型，生成需求文档 ││
|
||
│ └─────────────────────────────────────────────────────────────────────────┘│
|
||
│ ↓ /clear │
|
||
│ 【Plan阶段】将需求转化为零决策规格 │
|
||
│ ┌─────────────────────────────────────────────────────────────────────────┐│
|
||
│ │ /gudaspec:plan <requirement.md> │ 结构设计：Phase划分，测试策略选择 ││
|
||
│ │ /gudaspec:plan-review <id> │ 详细规格：接口定义，测试规格，审批 ││
|
||
│ └─────────────────────────────────────────────────────────────────────────┘│
|
||
│ ↓ /clear │
|
||
│ 【Implementation阶段】执行规格产出代码 │
|
||
│ ┌─────────────────────────────────────────────────────────────────────────┐│
|
||
│ │ /gudaspec:implementation <plan.md> [Phase N] ││
|
||
│ │ • TDD循环：RED（写测试）→ GREEN（写实现）→ REFACTOR（审查优化） ││
|
||
│ │ • 多模型协作：Codex实现后端，Gemini实现前端，交叉审查 ││
|
||
│ │ • 逐Phase执行，每Phase后暂停等待人工确认 ││
|
||
│ └─────────────────────────────────────────────────────────────────────────┘│
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 目录结构 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ gudaspec/ │
|
||
│ ├── research/ # 研究文档 │
|
||
│ │ └── <requirement-id>/ │
|
||
│ │ ├── internal.md # 内部研究（代码库约束） │
|
||
│ │ ├── external.md # 外部研究（技术选型） │
|
||
│ │ └── requirement.md # 最终需求文档 │
|
||
│ ├── plans/ # 计划文档 │
|
||
│ │ └── <requirement-id>/ │
|
||
│ │ ├── structure.md # 计划结构 │
|
||
│ │ ├── plan.md # 详细计划 │
|
||
│ │ └── tests/ # 测试规格 │
|
||
│ └── archive/ # 已完成需求归档 │
|
||
│ └── <date>-<requirement-id>/ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 典型工作流 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 简单需求（Bug修复、小改动）: │
|
||
│ /gudaspec:research → 描述需求 │
|
||
│ /clear → /gudaspec:research-review <id> → 跳过外部 → requirement.md │
|
||
│ /clear → /gudaspec:plan <req.md> │
|
||
│ /clear → /gudaspec:plan-review <id> │
|
||
│ /clear → /gudaspec:implementation <plan.md> │
|
||
│ │
|
||
│ 复杂需求（新功能、新技术）: │
|
||
│ /gudaspec:research → 描述需求 │
|
||
│ /clear → /gudaspec:research-review <id> → 需要外部 │
|
||
│ /clear → /gudaspec:deepresearch <id> │
|
||
│ /clear → /gudaspec:deep-research-review <id> → requirement.md │
|
||
│ /clear → /gudaspec:plan <req.md> │
|
||
│ /clear → /gudaspec:plan-review <id> │
|
||
│ /clear → /gudaspec:implementation <plan.md> │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
### Step 8: Next Steps
|
||
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
✅ GudaSpec 初始化完成
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
📋 下一步操作:
|
||
|
||
1. 输入 /clear 清空当前上下文
|
||
（初始化信息较多，清空后开始新任务更高效）
|
||
|
||
2. 开始您的第一个需求:
|
||
输入 /gudaspec:research
|
||
然后描述您的需求
|
||
|
||
💡 提示:
|
||
• 每个阶段完成后记得 /clear 保持上下文干净
|
||
• 简单需求可跳过外部研究阶段
|
||
• 使用 Level 1 TDD模式可获得更高代码质量
|
||
• 多模型审查会自动进行，无需手动触发
|
||
|
||
📚 参考资源:
|
||
• RPI理论: https://github.com/humanlayer/humanlayer
|
||
• GudaSpec命令集: https://github.com/GuDaStudio/commands
|
||
• Codex MCP: https://github.com/GuDaStudio/codexmcp
|
||
• Gemini MCP: https://github.com/GuDaStudio/geminimcp
|
||
• Grok Search: https://github.com/GuDaStudio/GrokSearch
|
||
```
|
||
|
||
---
|
||
|
||
## Exit Criteria
|
||
|
||
- [ ] Operating system detected
|
||
- [ ] gudaspec/ directory structure created
|
||
- [ ] .gudaspec.json configuration file created
|
||
- [ ] All MCP tools checked and status reported
|
||
- [ ] Summary report displayed
|
||
- [ ] GudaSpec introduction output
|
||
- [ ] User directed to /clear and /gudaspec:research
|
||
|
||
---
|
||
|
||
## Reference
|
||
|
||
- GudaSpec Commands: https://github.com/GuDaStudio/commands
|
||
- HumanLayer RPI: https://github.com/humanlayer/humanlayer
|
||
- Codex MCP: https://github.com/GuDaStudio/codexmcp
|
||
- Gemini MCP: https://github.com/GuDaStudio/geminimcp
|
||
- Grok Search: https://github.com/GuDaStudio/GrokSearch
|
||
|
||
<!-- GUDASPEC:INIT:END -->
|