GuDaStudio/commands
1
0
Fork 0
mirror of https://github.com/GuDaStudio/commands.git synced 2026-03-22 19:18:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

v1.0：gudaspec正式版，不再依赖于openspec

Browse Source
This commit is contained in:
GuDaStudio
2026-02-06 11:11:39 +08:00
parent 32d5902088
commit 34b2c931b6
8 changed files with 3669 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

361
gudaspec/research.md
View File

@@ -1,97 +1,296 @@
---
name: GudaSpec Research
description: Transform user requirements into constraint sets through parallel exploration and analysis
name: GudaSpec: Research
description: Internal codebase research - analyze existing code constraints and generate requirement ID.
category: GudaSpec
tags: [gudaspec, research, constraints, exploration, subagents]
tags: [gudaspec, research, internal, brownfield, constraints]
---
<!-- GUDASPEC:RESEARCH:START -->
**Core Philosophy**
- If the project is detected to lack `./openspec/` dir, prompt the user to initialize the project using `/gudaspec:init`.
- Research produces **constraint sets**, not information dumps. Each constraint narrows the solution space.
- Constraints tell subsequent stages "don't consider this direction," enabling mechanical execution without decisions.
- The output is "約束集合 + 可验证的成功判据" (constraint sets + verifiable success criteria).
- Eliminate ambiguity through structured exploration and user interaction.
- Strictly adhere to **OpenSpec** rules when writing **standardized spec-structured projects**.
**Guardrails**
- **NEVER** divide subagent tasks by roles (e.g., "架构师agent", "安全专家agent").
- **ALWAYS** divide by context boundaries (e.g., "user-related code", "authentication logic", "infrastructure config").
- Each subagent context must be self-contained with independent output.
- **MANDATORY**: Use `mcp__auggie-mcp__codebase-retrieval` to minimize search/grep/find operations.
- All subagents must follow the same structured output template for aggregation.
- Do not make architectural decisions—surface constraints that guide decisions.
## CRITICAL: DOCUMENT ONLY, NO SUGGESTIONS
**Steps**
0. **Generate OpenSpec Proposal**
- Run `/opsx:explore <user question>` always first.
- **DO NOT** suggest improvements or changes
- **DO NOT** critique implementation or identify problems
- **DO NOT** recommend refactoring or optimizations
- **ONLY** describe: what exists, where it exists, how components interact
- You are creating a **technical map** of constraints, not a roadmap for changes
1. **Initial Codebase Assessment**
- Combine user requirements with quick codebase scan using `mcp__auggie-mcp__codebase-retrieval`.
- Determine project scale: single directory vs. multi-directory structure.
- **Decision point**: If code spans multiple subdirectories or modules → enable parallel Explore subagents.
- Document finding: "Single agent serial exploration is inefficient; parallel subagents required."
## Purpose
2. **Define Exploration Boundaries (Context-Based Division)**
- Identify natural context boundaries in the codebase (NOT functional roles).
- Example divisions:
* Subagent 1: User domain code (user models, user services, user UI)
* Subagent 2: Authentication & authorization code (auth middleware, session, tokens)
* Subagent 3: Configuration & infrastructure (configs, deployments, build scripts)
- Each boundary should be self-contained: no cross-communication needed between subagents.
- Define exploration scope and expected output for each subagent.
- The subagent takes forever to run, forcing you to wait—absolutely nothing else can be done until the subagent's results are fully obtained.
执行代码域调研（Internal Research），分析现有代码库约束，生成需求ID和待审查的内部研究文档。
3. **Prepare Standardized Output Template**
- Define a unified JSON schema that all Explore subagents must follow:
```json
{
"module_name": "string - context boundary explored",
"existing_structures": ["list of key structures/patterns found"],
"existing_conventions": ["list of conventions/standards in use"],
"constraints_discovered": ["list of hard constraints that limit solution space"],
"open_questions": ["list of ambiguities requiring user input"],
"dependencies": ["list of dependencies on other modules/systems"],
"risks": ["list of potential risks or blockers"],
"success_criteria_hints": ["observable behaviors that indicate success"]
}
```
- Communicate template to all subagents for consistency.
## Guardrails
4. **Parallel Subagent Dispatch**
- For each defined context boundary, spawn an Explore subagent with:
* **Explicit instruction**: "You MUST use `mcp__auggie-mcp__codebase-retrieval` to reduce search operations."
* Defined scope and context boundary.
* Required output template (from Step 3).
* Clear success criteria: complete analysis of assigned boundary.
- Monitor subagent execution and collect structured reports.
- If project lacks `./openspec/` directory, prompt user to run `/gudaspec:init`.
- **MANDATORY**: Use `mcp__auggie-mcp__codebase-retrieval` to minimize grep/find operations.
- **NEVER** divide tasks by roles. **ALWAYS** divide by context boundaries.
- Base all judgments on code evidence. Speculation prohibited.
- All findings must include file:line references.
5. **Aggregate and Synthesize Reports**
- Collect all subagent JSON outputs.
- Merge findings into unified constraint sets:
* **Hard constraints**: Technical limitations, existing patterns that cannot be violated.
* **Soft constraints**: Conventions, preferences, style guides.
* **Dependencies**: Cross-module relationships that affect implementation order.
* **Risks**: Potential blockers that need mitigation.
- Identify **open questions** from all reports that require user clarification.
- Synthesize **success criteria** from scenario hints across all contexts.
---
6. **User Interaction for Ambiguity Resolution**
- Compile prioritized list of open questions from aggregated reports.
- Use `AskUserQuestions` tool to present questions systematically:
* Group related questions together.
* Provide context for each question.
* Suggest default answers when applicable.
- Capture user responses as additional constraints.
- Update constraint sets with confirmed decisions.
## Steps
7. **Generate OpenSpec Proposal**
- Run `/opsx:ff <requirement-description>` and follow it.
- When generate `proposal.md`, strictly prohibit abbreviating user requirements; only expansion is allowed. The generated document MUST NOT contain any ambiguous content. For example, specific project files mentioned by the user must be accurately referenced down to the file path, and should not be abbreviated in a way that misleads document readers into thinking it refers to an online-searched project rather than a local one.
### Step 0: Receive Requirement
When invoked, respond:
```
我已准备好进行代码域调研。请描述您的需求，我将：
1. 分析现有代码库中的相关约束
2. 生成需求ID便于后续管理
3. 输出待审查的内部研究文档
请描述您的需求：
```
Wait for user input.
### Step 1: Generate Requirement ID
Based on user's requirement description, generate a kebab-case ID:
**命名规范**（参考OpenSpec）：
- 格式: `<action>-<target>[-<scope>]`
- 动作词: `add`, `fix`, `update`, `remove`, `refactor`, `migrate`
- 全小写，单词间用连字符
- 长度: 3-5个单词
- 避免缩写，保持可读性
**示例**：
| 用户需求 | 生成的需求ID |
|----------|--------------|
| "添加Outlook邮件前端" | `add-outlook-email-frontend` |
| "修复用户登录超时问题" | `fix-user-login-timeout` |
| "重构支付模块" | `refactor-payment-module` |
| "添加双因素认证" | `add-two-factor-auth` |
| "迁移数据库到PostgreSQL" | `migrate-database-postgresql` |
Confirm with user:
```
需求ID: <generated-id>
确认此ID或提供修改建议：
```
### Step 2: Read Mentioned Files
- If user mentions specific files, read them **FULLY** before proceeding
- This ensures complete context before decomposition
### Step 3: Codebase Assessment
Use `mcp__auggie-mcp__codebase-retrieval` to:
- Scan project structure
- Identify relevant modules/directories
- Determine context boundaries for parallel research
### Step 4: Define Context Boundaries
Divide by **context**, not roles:
| Correct (Context) | Incorrect (Role) |
|-------------------|------------------|
| User-related code | "架构师 agent" |
| Authentication layer | "安全专家 agent" |
| Data access layer | "DBA agent" |
| Target feature area | "领域专家 agent" |
### Step 5: Parallel Subagent Research
For each context boundary, spawn subagent:
```
You are a documentarian, NOT a critic.
Document what EXISTS, not what SHOULD BE.
Context: [boundary_name]
Scope: [directories/files]
Output JSON:
{
"context_boundary": "string",
"relevant_files": [{"path": "", "purpose": "", "key_exports": [], "lines": ""}],
"existing_patterns": ["pattern - location"],
"hard_constraints": ["constraint - file:line - reason"],
"soft_constraints": ["convention - where observed"],
"dependencies": {"internal": [], "external": []},
"information_flow": "description",
"integration_points": ["where new code must connect"],
"open_questions": ["question - context"]
}
```
### Step 6: Aggregate and Generate Internal Document
Create directory and file:
```
gudaspec/research/<requirement-id>/internal.md
```
**Document Template**:
````markdown
---
requirement_id: <requirement-id>
created: <ISO timestamp>
researcher: claude
git_commit: <current commit>
branch: <current branch>
status: pending-review
type: internal
---
# Internal Research: <Requirement Description>
## 需求概述
<用户原始需求描述 - 完整记录>
## 代码库概况
### 项目结构
```
<relevant directory tree>
```
### 技术栈
| 类型 | 技术 | 版本 | 配置位置 |
|------|------|------|----------|
| 框架 | | | |
| 数据库 | | | |
| ... | | | |
---
## 约束发现
### 硬约束 (CANNOT violate)
> 以下约束必须严格遵守，违反将导致系统故障或不兼容
| ID | 约束描述 | 来源 | 原因 | 确认 |
|----|----------|------|------|------|
| HC-1 | | `file:line` | | [ ] |
| HC-2 | | `file:line` | | [ ] |
| HC-3 | | `file:line` | | [ ] |
### 软约束 (SHOULD follow)
> 以下为项目惯例，建议遵循以保持一致性
| ID | 约束描述 | 观察位置 | 灵活度 | 确认 |
|----|----------|----------|--------|------|
| SC-1 | | | | [ ] |
| SC-2 | | | | [ ] |
---
## 相关文件分析
### 核心文件
| 文件路径 | 用途 | 关键导出 | 与需求关系 | 确认 |
|----------|------|----------|------------|------|
| | | | | [ ] |
| | | | | [ ] |
### 信息流
```
<ASCII diagram showing data flow relevant to requirement>
```
确认信息流准确: [ ]
---
## 集成点
> 新代码需要与以下位置对接
| ID | 集成位置 | 文件 | 对接方式 | 确认 |
|----|----------|------|----------|------|
| IP-1 | | | | [ ] |
| IP-2 | | | | [ ] |
---
## 依赖关系
### 内部依赖
| 模块 | 依赖 | 关系类型 | 确认 |
|------|------|----------|------|
| | | | [ ] |
### 外部依赖
| 包名 | 版本 | 用途 | 确认 |
|------|------|------|------|
| | | | [ ] |
---
## 现有测试
| 测试文件 | 覆盖范围 | 状态 | 与需求相关 | 确认 |
|----------|----------|------|------------|------|
| | | | | [ ] |
---
## 开放问题
> 以下问题需要您的确认
| ID | 问题 | 上下文 | 您的回答 |
|----|------|--------|----------|
| OQ-1 | | | __________ |
| OQ-2 | | | __________ |
| OQ-3 | | | __________ |
---
## External Research 初步判断
基于以上内部研究，以下情况可能需要外部调研：
| 触发条件 | 检测结果 | 说明 |
|----------|----------|------|
| 引入新技术/库 | ⬜ 是 / ⬜ 否 | |
| 代码库无相关参考 | ⬜ 是 / ⬜ 否 | |
| 新架构模式 | ⬜ 是 / ⬜ 否 | |
| 未知领域知识 | ⬜ 是 / ⬜ 否 | |
| 用户显式要求 | ⬜ 是 / ⬜ 否 | |
初步建议: [ ] 需要 External Research / [ ] 不需要
````
### Step 7: Final Output
```
✅ Internal Research 完成
需求ID: <requirement-id>
文档位置: gudaspec/research/<requirement-id>/internal.md
发现摘要:
- 硬约束: [X] 条
- 软约束: [Y] 条
- 集成点: [Z] 处
- 开放问题: [N] 个
📋 下一步操作:
1. 输入 /clear 清空当前上下文
2. 输入 /gudaspec:research-review <requirement-id> 开始审查
```
---
## Exit Criteria
- [ ] Requirement ID generated and confirmed
- [ ] All context boundaries explored
- [ ] Internal document saved to `gudaspec/research/<id>/internal.md`
- [ ] All checkboxes initialized as unchecked
- [ ] User reminded to `/clear` and proceed to review
**Reference**
- Inspect codebase structure: `ls -R` or `mcp__auggie-mcp__codebase-retrieval`
- Validate subagent outputs conform to template before aggregation.
- Use `AskUserQuestions` for ANY ambiguity—do not assume or guess.
- Always base judgments on project codes, strictly prohibiting the use of general knowledge for speculation. It is permissible to indicate uncertainty to users.
<!-- GUDASPEC:RESEARCH:END -->