requirements-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Requirements Builder

需求构建器

Intelligent requirements gathering system that discovers codebase context, asks structured yes/no questions, and generates comprehensive requirements documentation.

Based on claude-code-requirements-builder.

智能需求收集系统，可探查代码库上下文、提出结构化的是/否问题，并生成完整的需求文档。

基于 claude-code-requirements-builder 开发。

Arguments

参数

$ARGUMENTS

— description of the feature or requirement to gather (e.g., "add user profile photo upload")

$ARGUMENTS

— 待收集的功能或需求的描述（例如："add user profile photo upload"）

Setup

配置

Ensure the

requirements/

directory exists in the project root:

mkdir -p requirements
touch requirements/.current-requirement

确保项目根目录下存在

requirements/

mkdir -p requirements
touch requirements/.current-requirement

Workflow Overview

工作流概览

Phase 1: Initial Setup & Codebase Analysis
    → Create timestamped folder, analyze codebase structure
Phase 2: Context Discovery Questions (5 yes/no questions)
    → Ask about problem space, workflows, integrations
Phase 3: Targeted Context Gathering (autonomous)
    → Deep-dive into relevant code, patterns, similar features
Phase 4: Expert Requirements Questions (5 yes/no questions)
    → Ask like a senior dev who knows the codebase
Phase 5: Requirements Documentation
    → Generate comprehensive spec with acceptance criteria

Phase 1: Initial Setup & Codebase Analysis
    → 创建带时间戳的文件夹，分析代码库结构
Phase 2: Context Discovery Questions (5 yes/no questions)
    → 询问问题空间、工作流、集成相关的内容
Phase 3: Targeted Context Gathering (autonomous)
    → 深度探查相关代码、模式、相似功能
Phase 4: Expert Requirements Questions (5 yes/no questions)
    → 像熟悉代码库的高级开发一样提问
Phase 5: Requirements Documentation
    → 生成包含验收标准的完整规格说明书

Phase 1: Initial Setup & Codebase Analysis

阶段1：初始配置与代码库分析

Create timestamp-based folder:
```
requirements/YYYY-MM-DD-HHMM-[slug]
```
Extract slug from
```
$ARGUMENTS
```
(e.g., "add user profile" → "user-profile")
Create initial files:
- ```
00-initial-request.md
```
  with the user's request
- ```
metadata.json
```
  with status tracking
Read and update
```
requirements/.current-requirement
```
with folder name
Analyze the codebase to understand overall structure:
- Get high-level architecture overview
- Identify main components and services
- Understand technology stack
- Note patterns and conventions

创建基于时间戳的文件夹：
```
requirements/YYYY-MM-DD-HHMM-[slug]
```
从
```
$ARGUMENTS
```
中提取slug（例如："add user profile" → "user-profile"）
创建初始文件：
- 包含用户需求的
```
00-initial-request.md
```
- 用于状态追踪的
```
metadata.json
```
读取并更新
```
requirements/.current-requirement
```
中的文件夹名称
分析代码库以理解整体结构：
- 获取高层架构概览
- 识别核心组件和服务
- 了解技术栈
- 记录开发模式和规范

Phase 2: Context Discovery Questions

阶段2：上下文探查问题

Generate the five most important yes/no questions to understand the problem space:
- Questions informed by codebase structure
- Questions about user interactions and workflows
- Questions about similar features users currently use
- Questions about data/content being worked with
- Questions about external integrations or third-party services
- Questions about performance or scale expectations
- Write all questions to
```
01-discovery-questions.md
```
  with smart defaults
- Begin asking questions one at a time proposing the question with a smart default option
- Only after all questions are asked, record answers in
```
02-discovery-answers.md
```
  as received and update
```
metadata.json
```
  . Not before.

生成5个最重要的是/否问题以理解问题空间：
- 基于代码库结构设计问题
- 关于用户交互和工作流的问题
- 关于用户当前使用的相似功能的问题
- 关于所处理的数据/内容的问题
- 关于外部集成或第三方服务的问题
- 关于性能或规模预期的问题
- 将所有问题连同智能默认值写入
```
01-discovery-questions.md
```
- 每次提出一个问题并附带智能默认选项
- 仅在所有问题询问完毕后，将收到的答案记录到
```
02-discovery-answers.md
```
  并更新
```
metadata.json
```
  ，不可提前操作。

Discovery Question Format:

探查问题格式：

undefined

undefined

Q1: Will users interact with this feature through a visual interface?

Default if unknown: Yes (most features have some UI component)

Q2: Does this feature need to work on mobile devices?

Default if unknown: Yes (mobile-first is standard practice)

undefined

Default if unknown: Yes (mobile-first is standard practice)

undefined

Phase 3: Targeted Context Gathering (Autonomous)

阶段3：定向上下文收集（自动执行）

After all discovery questions answered:
- Search for specific files based on discovery answers
- Read relevant code in batch
- Deep dive into similar features and patterns
- Analyze specific implementation details
- Use WebSearch and/or context7 for best practices or library documentation
- Document findings in
```
03-context-findings.md
```
  including:
  - Specific files that need modification
  - Exact patterns to follow
  - Similar features analyzed in detail
  - Technical constraints and considerations
  - Integration points identified

所有探查问题答复完成后：
- 根据探查答案搜索特定文件
- 批量读取相关代码
- 深度研究相似功能和开发模式
- 分析具体实现细节
- 使用WebSearch和/或context7查询最佳实践或库文档
- 将发现结果记录到
```
03-context-findings.md
```
  ，包含：
  - 需要修改的具体文件
  - 需遵循的明确开发模式
  - 详细分析过的相似功能
  - 技术约束和注意事项
  - 识别到的集成点

Phase 4: Expert Requirements Questions

阶段4：专业需求问题

Now ask questions like a senior developer who knows the codebase:
- Write the top 5 most pressing unanswered detailed yes/no questions to
```
04-detail-questions.md
```
- Questions should be as if you were speaking to the product manager who knows nothing of the code
- These questions are meant to clarify expected system behavior now that you have a deep understanding of the code
- Include smart defaults based on codebase patterns
- Ask questions one at a time
- Only after all questions are asked, record answers in
```
05-detail-answers.md
```
  as received

现在像熟悉代码库的高级开发一样提问：
- 将最重要的5个未解决的细节类是/否问题写入
```
04-detail-questions.md
```
- 问题应该像是你在和完全不了解代码的产品经理沟通
- 这些问题用于在你深度理解代码的基础上，明确预期的系统行为
- 包含基于代码库模式的智能默认值
- 每次提出一个问题
- 仅在所有问题询问完毕后，将收到的答案记录到
```
05-detail-answers.md
```

Expert Question Format:

专业问题格式：

undefined

undefined

Q7: Should we extend the existing UserService at services/UserService.ts?

Default if unknown: Yes (maintains architectural consistency)

Q8: Will this require new database migrations in db/migrations/?

Default if unknown: No (based on similar features not requiring schema changes)

undefined

Default if unknown: No (based on similar features not requiring schema changes)

undefined

Phase 5: Requirements Documentation

阶段5：需求文档生成

Generate comprehensive requirements spec in
```
06-requirements-spec.md
```
:
- Problem statement and solution overview
- Functional requirements based on all answers
- Technical requirements with specific file paths
- Implementation hints and patterns to follow
- Acceptance criteria
- Assumptions for any unanswered questions

在
```
06-requirements-spec.md
```
中生成完整的需求规格说明书：
- 问题陈述和解决方案概览
- 基于所有答复的功能需求
- 带具体文件路径的技术需求
- 实现提示和需遵循的开发模式
- 验收标准
- 所有未答复问题的假设条件

Important Rules

重要规则

ONLY yes/no questions with smart defaults
ONE question at a time
Write ALL questions to file BEFORE asking any
Stay focused on requirements (no implementation)
Use actual file paths and component names in detail phase
Document WHY each default makes sense

仅允许附带智能默认值的是/否问题
每次仅提一个问题
提问前必须将所有问题写入文件
聚焦需求本身（不涉及实现）
细节阶段使用真实的文件路径和组件名称
记录每个默认值的合理性

Phase Transitions

阶段切换

After each phase, announce: "Phase complete. Starting [next phase]..."
Save all work before moving to next phase

每个阶段结束后播报："Phase complete. Starting [next phase]..."
进入下一阶段前保存所有工作内容

Sub-Commands

子命令

/requirements-status

Show current requirement gathering progress and continue from last unanswered question.

Read
```
requirements/.current-requirement
```
If no active requirement, suggest starting one
If active: show formatted status, load question files, continue from last unanswered question

展示当前需求收集进度，从上次未答复的问题继续推进。

读取
```
requirements/.current-requirement
```
无活跃需求时，建议启动新的需求收集
有活跃需求时：展示格式化的状态，加载问题文件，从上次未答复的问题继续

/requirements-current

Display detailed information about the active requirement (view-only, doesn't continue gathering).

Shows: initial request, codebase overview, all questions/answers, context findings, current phase, next steps.

展示活跃需求的详细信息（仅查看，不继续收集流程）。

展示内容：初始需求、代码库概览、所有问题/答案、上下文发现、当前阶段、下一步操作。

/requirements-list

Display all requirements with their status and summaries, sorted by active first, then complete, then incomplete.

展示所有需求及其状态和摘要，排序规则：活跃需求优先，其次是已完成需求，最后是未完成需求。

/requirements-end

Finalize the current requirement gathering session. Options:

Generate spec with current information (defaults for unanswered)
Mark as incomplete for later
Cancel and delete

结束当前需求收集会话。可选操作：

生成规格说明书 使用现有信息（未答复问题使用默认值）
标记为未完成 后续继续处理
取消并删除

/requirements-remind

Quick correction when deviating from requirements gathering rules. Auto-detects:

Open-ended questions asked → rephrase as yes/no
Multiple questions asked → ask one at a time
Implementation started → redirect to requirements
No default provided → add a default

偏离需求收集规则时的快速纠正。自动检测：

提出开放式问题 → 重写为是/否问题
一次性提出多个问题 → 每次仅提一个
开始讨论实现 → 引导回归需求本身
未提供默认值 → 补充默认值

File Structure

文件结构

Each requirement creates this folder structure:

requirements/
  .current-requirement          # Active requirement folder name
  YYYY-MM-DD-HHMM-[slug]/
    00-initial-request.md       # Original user request
    01-discovery-questions.md   # Context discovery questions
    02-discovery-answers.md     # User's answers
    03-context-findings.md      # AI's codebase analysis
    04-detail-questions.md      # Expert requirements questions
    05-detail-answers.md        # User's detailed answers
    06-requirements-spec.md     # Final requirements document
    metadata.json               # Status tracking

每个需求会创建如下文件夹结构：

requirements/
  .current-requirement          # 活跃需求文件夹名称
  YYYY-MM-DD-HHMM-[slug]/
    00-initial-request.md       # 原始用户需求
    01-discovery-questions.md   # 上下文探查问题
    02-discovery-answers.md     # 用户答复
    03-context-findings.md      # AI的代码库分析结果
    04-detail-questions.md      # 专业需求问题
    05-detail-answers.md        # 用户的详细答复
    06-requirements-spec.md     # 最终需求文档
    metadata.json               # 状态追踪

Metadata Structure

元数据结构

json

{
  "id": "feature-slug",
  "started": "ISO-8601-timestamp",
  "lastUpdated": "ISO-8601-timestamp",
  "status": "active",
  "phase": "discovery|context|detail|complete",
  "progress": {
    "discovery": { "answered": 0, "total": 5 },
    "detail": { "answered": 0, "total": 0 }
  },
  "contextFiles": ["paths/of/files/analyzed"],
  "relatedFeatures": ["similar features found"]
}

json

{
  "id": "feature-slug",
  "started": "ISO-8601-timestamp",
  "lastUpdated": "ISO-8601-timestamp",
  "status": "active",
  "phase": "discovery|context|detail|complete",
  "progress": {
    "discovery": { "answered": 0, "total": 5 },
    "detail": { "answered": 0, "total": 0 }
  },
  "contextFiles": ["paths/of/files/analyzed"],
  "relatedFeatures": ["similar features found"]
}

Final Spec Format

最终规格格式

markdown

undefined

markdown

undefined

Requirements Specification: [Name]

Generated: [timestamp] Status: [Complete with X assumptions / Partial]

Overview

[Problem statement and solution summary]

Detailed Requirements

Functional Requirements

[Based on answered questions]

Technical Requirements

Affected files: [list with paths]
New components: [if any]
Database changes: [if any]

Affected files: [list with paths]
New components: [if any]
Database changes: [if any]

Assumptions

[List any defaults used for unanswered questions]

Implementation Notes

[Specific guidance for implementation]

Acceptance Criteria

[Testable criteria for completion]

undefined

[Testable criteria for completion]

undefined