11 KiB
Based on RPI and Effective Context Theory, Let Claude Code Focus on One Thing at a Time
⭐ Star us on GitHub ~ Your support means a lot to us! 🙏😊
English | 简体中文
1. Introduction
GudaStudio Commands is a collection of Claude Code custom commands developed by GudaStudio. The core command gudaspec implements a complete workflow based on RPI (Research-Plan-Implementation) Coding Theory, integrating OpenSpec and multi-model collaboration to make Claude Code more suitable for complex scenarios and long-duration coding tasks. Additionally, this project introduces a human-centric operational philosophy, allowing users to manually segment context across multiple phases, maximizing Claude Code's effective context window (~80K)! Check out the usage examples for full features!
gudaspec Command Set
| Command | Function |
|---|---|
/gudaspec:init |
Initialize OpenSpec environment, verify MCP tool availability |
/gudaspec:research |
Parallel codebase exploration, transform requirements into constraint sets |
/gudaspec:plan |
Multi-model analysis, generate zero-decision execution plans with PBT properties |
/gudaspec:implementation |
Multi-model collaborative implementation, refactor prototypes into production-grade code |
2. Quick Start
0. Prerequisites
- Claude Code (v2.1.15+)
- Auggie MCP
1. Clone the Repository
git clone https://github.com/GuDaStudio/commands
cd commands
2. Install Commands
Linux / macOS
# User-level installation (applies to all projects)
./install.sh --user
# Project-level installation (applies to current project only)
./install.sh --project
# Custom path
./install.sh --target /your/custom/path
Windows (PowerShell)
# User-level installation (applies to all projects)
.\install.ps1 -User
# Project-level installation (applies to current project only)
.\install.ps1 -Project
# Custom path
.\install.ps1 -Target C:\your\custom\path
Parameter Reference
| Bash | PowerShell | Short | Description |
|---|---|---|---|
--user |
-User |
-u |
Install to user-level directory (~/.claude/commands/) |
--project |
-Project |
-p |
Install to project-level directory (./.claude/commands/) |
--target <path> |
-Target <path> |
-t |
Install to custom path |
--help |
-Help |
-h |
Show help information |
3. Verify Installation
After launching Claude Code, type /gudaspec to view available commands.
4. Configure Global Prompt 🎊
Add the following prompt to ~/.claude/CLAUDE.md:
# CLAUDE.md
## 0. Global Protocols
All operations must strictly follow these system constraints:
- **Interaction Language**: Tool-model interactions MUST use **English**; user output MUST use **English**.
- **Multi-turn Conversations**: If a tool returns a persistent conversation field like `SESSION_ID`, it indicates the tool supports multi-turn conversations. Record this field and **force deliberation** in subsequent tool calls on whether to continue the conversation. For example, Codex/Gemini sometimes interrupt sessions during tool calls; if you don't get the needed response, continue the conversation.
- **Sandbox Security**: Codex/Gemini are PROHIBITED from performing write operations to the filesystem. All code retrieval must request `unified diff patch` format.
- **Code Sovereignty**: Code generated by external models serves only as logical reference (Prototype). Final delivered code **MUST be refactored** to ensure no redundancy and enterprise-grade standards.
- **Style Definition**: Overall code style is **always positioned** as lean, efficient, with zero redundancy. This requirement also applies to comments and documentation, and for these two, strictly follow the core principle of **form only when necessary**.
- **Targeted Changes Only**: PROHIBITED from affecting user's existing other functionalities.
- **Context Retrieval**: When calling `mcp__auggie-mcp__codebase-retrieval`, minimize the number of search/find/grep operations.
- **Judgment Basis**: Always use project code and grok search results as the basis for judgment. PROHIBITED from guessing based on general knowledge. Expressing uncertainty to users is allowed.
3. Usage Examples
The core philosophy of this project is focusing effective context on one thing at a time. This section will demonstrate the unique charm of this project using Building a Visual Weather Page from Scratch as an example! 😀
All examples below use Claude Opus 4.5, and we strongly recommend enabling reasoning mode to enhance Claude's instruction-following capability!
0. Init - Project Initialization
0.1 Enter the project, open Claude Code, and type /gudaspec:init to initialize gudaspec for this project.
0.2 Claude will automatically install openspec for you and detect whether Codex-MCP and Gemini-MCP are available.
0.3 This phase's task is complete. Type /clear to clear the current context and start a new conversation.
1. Research - Requirements Research
This phase aims to develop a preliminary understanding of user requirements based on existing code/initial information, and form a standard OpenSpec document.
1.1 In the new conversation window, enter the following:
/gudaspec:research
I need to create a beautiful real-time weather display page. Requirements:
1. Real-time weather info must be real data, including temperature, humidity, etc.
2. Users can select from three cities: Beijing, Shanghai, Shenzhen
3. Four different basic weather conditions (windy, rainy, sunny, snowy) have different page displays
4. UI design is highly aesthetic, referencing Apple's top-tier frontend design
Claude will automatically research and generate a preliminary proposal in OpenSpec format.
1.2 When your requirements contain obvious ambiguities, Claude will proactively seek your opinion.
1.3 Finally, Claude will generate a preliminary spec document for you. At this point, only 59.5K of context has been used, still well within Claude's most focused context length of 80K. 🥳
2. Plan - Planning
This phase's task is to completely eliminate uncertainty in user requirements and generate an executable plan, while providing verifiable properties for the plan.
2.1 In a new conversation window, enter the following. Claude will automatically find the pending requirements for you.
/gudaspec:plan
2.2 Claude will launch multi-model (Codex/Gemini) collaboration to analyze and refine the implementation approach in the preliminary requirements report.
2.3 After obtaining analysis from multiple models, Claude will further refine the requirements to completely eliminate technical ambiguity.
2.4 After all decision items are completed, Claude will extract Property-Based Testing properties for verification in subsequent phases.
2.5 Until the plan becomes a zero-decision sequentially executable pipeline, Claude will generate the complete spec document. This phase's task is complete. Type /clear to clear the current context and start a new conversation window.
3. Implementation - Code Implementation
This phase's goal is to execute specific code implementation until user requirements are fulfilled.
3.1 In a new conversation window, execute the following command. Claude will automatically identify pending requirement proposals for you.
/gudaspec:implementation
3.2 Claude will automatically identify minimal verifiable tasks for incremental implementation, helping you control context better!
3.3 After completing a phase task, Claude will pause and ask for your opinion on whether to continue. At this point, we strongly recommend you pay attention to the context window. If it's less than 80K, you can continue to the next phase of implementation; otherwise, you can type /clear to start a new conversation window and continue implementation from 3.1.
3.4 During the process, Claude will automatically enable multi-model code prototype retrieval (Frontend/UI → Gemini | Backend/Logic → Codex), and enable multi-model review after completing each phase task to ensure code reliability.
3.5 Result showcase. Once all tasks are completed, we get a weather system with real data! 😀 (Left: system screenshot, Right: China Meteorological Administration screenshot)
FAQ
Q1: What is OpenSpec?
OpenSpec is a standardized requirements-to-implementation workflow framework that ensures traceability and consistency from requirements to code through structured constraint set management.
Q2: Is Codex/Gemini MCP required?
No, it's not mandatory. However, to use the complete multi-model collaboration features, you need to install the corresponding MCP tools. Running /gudaspec:init will detect and prompt for installation.
Q3: What is the purpose of constraint sets?
Constraint sets transform requirements into specific technical constraints, eliminating decision points during implementation. Each constraint narrows the solution space, making the implementation phase pure mechanical execution without real-time judgment needed.
License
This project is open-sourced under the MIT License.
Copyright (c) 2025 guda.studio