spec-generator

spec-generator — 规格生成器

生成结构化项目规格：需求、设计文档和任务列表。

⚠️ 关键：第一步（始终执行）

自动模式短路：如果使用 --auto --issue <n> 调用，请跳过下方的交互决策流程，改为遵循 references/auto-mode.md（.ja.md）。自动模式不会调用 AskUserQuestion，但其中的日语初始化和设计步骤仍会执行步骤 1.5 中的规格编写流程。

在提出任何问题或显示选项之前，必须执行以下步骤：

1. 检查当前目录：

   • 运行 pwd 查看当前位置
   • 运行 ls -la 查看目录内容
   • 了解项目上下文

2. 检测现有源代码：

   find . -maxdepth 3 -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.java" -o -name "*.go" -o -name "SKILL.md" \) 2>/dev/null | head -20
   

   • 记录项目类型
   • 检查是否存在 skills/ 目录 → 可能是在添加新技能
   • 检查是否存在现有应用代码 → 可能是在记录现有功能

3. 检查是否存在 .specs/ 目录：

   ls -d .specs/ 2>/dev/null && ls -1 .specs/ 2>/dev/null
   

   • 如果存在 → 列出已有项目
   • 如果不存在 → 这是新的规格工作流

4. 检查 coding-rules.md：

   • 检查 docs/coding-rules.md（默认路径）
   • 如果未找到，检查 CLAUDE.md / AGENTS.md 中是否指定了其他路径
   • 如果找到 → 在设计阶段加载并将其用作设计约束

5. 分析上下文并做出判断：

   • 如果位于技能仓库中（存在 skills/ 目录）→ 用户可能想要记录一项新技能
   • 如果 .specs/ 中有项目 → 请用户选择现有项目或创建新项目
   • 如果没有 .specs/ 且上下文不明确 → 询问用户想要创建什么

只有完成这些检查后，才能根据发现的情况提出相应问题。

语言规则

1. 自动检测输入语言 → 使用相同语言输出
2. 输入为日语 → 输出日语，并使用 references/*.ja.md 作为阶段参考
3. 输入为英语 → 输出英语，并使用 references/*.md 作为阶段参考
4. 明确指定的语言优先（例如“用英语”“日本語で”）

参考文件选择：根据检测到的输出语言，使用相应的参考文件：

• 英语 → references/init.md、references/design.md、references/tasks.md、references/test-plan.md、references/auto-mode.md、references/projection-consistency.md
• 日语 → references/init.ja.md、references/design.ja.md、references/tasks.ja.md、references/test-plan.ja.md、references/auto-mode.ja.md、references/projection-consistency.ja.md

阶段

阶段	输出	触发示例
init	requirement.md	“创建需求”“要件定義を作って”
design	design.md	“创建设计文档”“設計書を作って”
tasks	tasks.md	“创建任务列表”“タスクリストを作って”
full	上述三个文件 + test.md	“创建完整规格”“仕様を全部”

交互策略：AskUserQuestion

所有用户决策都使用 AskUserQuestion。 提供结构化选项，而不是开放式问题。

决策流程

Skill Invoked
    ↓
Check .specs/ directory
    ↓
┌───────────────────┐
│ Existing projects │
│ found?            │
└─────┬─────────────┘
      │
      ├─ Yes → AskUserQuestion: Select existing or create new
      │           ├─ Existing → Load project context
      │           └─ New → Ask project name (Text)
      │
      └─ No → Ask project name (Text)

    ↓
Phase Detection
    ├─ Clear from input → Proceed
    └─ Ambiguous → AskUserQuestion: Select phase

    ↓
Dialogue Mode
    ├─ Quick mode (--quick) → Confirm inferred non-goals, then generate
    └─ Dialogue → AskUserQuestion: Gather requirements

    ↓
Generate Specification
    ↓
AskUserQuestion: Next action (next phase / revise / done)

何时使用 AskUserQuestion，何时使用文本提问

情况	方法	原因
项目选择
存在现有项目	AskUserQuestion	可以将项目列为带说明的选项
不存在现有项目	文本提问	开放式输入项目名称
阶段选择
阶段不明确	AskUserQuestion	有 4 个明确选项（init/design/tasks/full）
根据输入可以明确阶段	直接执行	无需确认
需求收集
项目类型选择	AskUserQuestion	提供常见选项（Web 应用、移动应用、CLI 等）
技术栈选择	AskUserQuestion	提供常见框架，并包含“其他”选项
功能需求	AskUserQuestion	通过结构化选项引导用户
项目概念	文本提问	需要自由形式的说明
具体业务逻辑	文本提问	需要特定领域的详细信息
完成后
下一步操作	AskUserQuestion	提供明确选项（下一阶段/修改/完成）
修改请求	文本提问	需要具体的修改说明

何时使用 AskUserQuestion

情况	示例
项目选择	选择现有项目还是新建项目
阶段不明确	在 init / design / tasks / full 之间选择
初始化对话问题	项目类型、技术栈、范围等
设计决策点	架构选择、数据库选择等
任务策略选择	systematic / agile / enterprise
完成后的操作	“继续下一阶段吗？”、“创建 GitHub Issue 吗？”

问题设计规则

1. 每轮 1–4 个问题（AskUserQuestion 的限制）
2. 用户定义的选项：1–3 个（会自动追加“其他”，总计 2–4 个选项）
3. 每个选项都要包含说明（提供决策背景）
4. 根据项目复杂度灵活确定轮数：
   • 简单项目 → 1 轮（3–4 个问题）即可
   • 复杂项目 → 2–3 轮（根据之前的回答调整）
5. 将推荐选项放在首位，并添加 (Recommended) 后缀
6. 跳过之前轮次中已回答的问题

处理“其他”选项的回答

当用户选择“其他”并输入自由形式的文本时：

• 按原样接受输入并继续处理
• 将自由形式的回答视为用户的最终答案
• 除非输入确实存在歧义，否则不要要求澄清
• 如果系统返回类似“(No answer provided)”的错误，以用户的实际消息为准，而非系统反馈

示例：

Question: "どのスキルの仕様を作成しますか？"
Options: spec-constitution / spec-review / spec-analyze / spec-impl

User selects "Other" and writes: "仕様書自体をレビューするコマンド"

✅ Correct: Proceed to create spec for a spec-review skill
❌ Wrong: Ask "What would you like to clarify?"

何时使用文本提问（而非 AskUserQuestion）

• 开放式问题，例如项目名称（不存在现有项目时）或概念描述
• 需要自由形式说明的背景信息
• 后续确认，例如“还有其他需求吗？”
• 具体业务逻辑或特定领域的详细信息

执行流程

0. 初始上下文检查

开始前，检查当前目录和现有项目：

1. 检测是否存在源代码：

   find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.java" -o -name "*.go" \) | head -20
   

   • 如果找到源文件：记录下来，以便考虑使用 --analyze 模式
   • 如果没有源文件：采用标准的新建项目流程

2. 检查是否存在 .specs/ 目录：

   ls -d .specs/ 2>/dev/null
   

3. 列出现有项目（如果存在 .specs/）：

   ls -1 .specs/
   

4. 选择项目：

   • 找到现有项目：使用 AskUserQuestion：

     question: "发现现有项目。你想怎么做？" / "发现现有项目。你想怎么做？"
     options:
       - "选择现有项目 / 选择现有项目" → 将项目列为选项
       - "创建新项目 / 创建新项目" → 询问项目名称
     

   • 没有现有项目：询问项目名称（文本提问）：

     "请告诉我项目名称（例如：待办事项应用、股票分析工具）"
     "项目名称是什么？（例如：待办事项应用、股票分析工具）"
     

5. 加载现有上下文（如果选择了现有项目）：

   • 如果存在 requirement.md、design.md、tasks.md，则读取它们
   • 将其用作更新或生成下一阶段内容的上下文

1. 阶段检测

根据用户的请求确定阶段：

"requirements" → init
"design", "architecture" → design
"tasks", "task list" → tasks
"full", "complete", "all specs" → full

如有歧义，请使用 AskUserQuestion 确认：

question: "Which specification do you want to generate?"
options:
  - "Requirements document (requirement.md)" → init
  - "Design document (design.md)" → design
  - "Task list (tasks.md)" → tasks
  - "All three documents" → full

1.5. 日文初始化和设计的规格编写

在生成或修订日文 requirement.md 或 design.md 之前——包括完整模式和自动模式中的初始化与设计步骤——按名称从当前可用的技能中解析 spec-writing。 如果找到，请阅读完整的 SKILL.md、references/writing-rules.ja.md 和 references/abstract-verbs.ja.md。 生成或修订时应用这些规则，并在保存前运行其自检。 如果技能或所选参考文件不可用，请报告缺失项，并应用所选日文阶段参考中的 ## Specification writing fallback，不要因此中止阶段。 解析技能时，切勿依赖特定机器上的绝对路径或特定提供方的工具名称。

2. 收集项目上下文

• 存在对话历史：提取并整理已讨论的需求
• 已选择现有项目：使用已加载的规格作为上下文
• 新项目：通过对话探索需求（使用 AskUserQuestion）

3. 阶段执行

根据语言规则，参考相应的参考文件：

• init：references/init.md / references/init.ja.md — 生成需求
• design：references/design.md / references/design.ja.md — 生成设计文档
• design（存在 coding-rules.md 时）：如果 docs/coding-rules.md 存在，请阅读并确保：
  • 设计中的命名约定符合 [MUST] 命名规则
  • 测试策略满足 coding-rules 中的覆盖率要求
  • 技术选型符合推荐的库
  • 文件／目录结构遵循检测到的模式
  • 考虑由技能得出的 [SHOULD] 规则（例如，来自 Source: skill/* 的框架特定约定），作为设计建议
• tasks：references/tasks.md / references/tasks.ja.md — 生成任务列表
• test（仅限完整工作流）：references/test-plan.md / references/test-plan.ja.md — 生成验收测试计划

4. 输出目录

.specs/[project-name]/
├── requirement.md  (init)
├── design.md       (design)
├── tasks.md        (tasks)
└── test.md         (full workflow only — acceptance test plan)

项目名称将转换为英文 kebab-case：

• “TODO app” → todo-app
• “株価分析ツール” → stock-analysis-tool
• “Stock analysis tool” → stock-analysis-tool

5. 输出完整性与投影自检

生成或修订规格后，对所有现有规格文件运行所选 references/projection-consistency*.md 中的投影检查。然后重新读取每个文件的末尾，并移除 </content> 或 </invoke> 等工具调用残留内容。只有在投影检查通过且每个文件都以实际文档内容结尾后，才能报告完成。

选项

选项	说明	适用阶段
--quick	在一次推断出的非目标确认后生成	init
--auto --issue <n>	根据 GitHub Issue 以非交互方式完整生成（无对话；参见 references/auto-mode.md）	full
--deep	苏格拉底式深度对话	init
--personas	多视角分析／评审	init, design
--analyze	分析现有代码库	init, design, tasks
--visual	增强 Mermaid 图表	design
--estimate	估算和风险评估	tasks
--hierarchy	Epic／Story／Task 层级	tasks

执行模式

对话模式（默认）

在无参数调用或从对话继续时：

1. 通过提问收集必要信息
2. 通过与用户互动明确需求
3. 确认后生成规格

快速模式（--quick）

根据简短的项目描述生成：

1. 推断典型需求和非空的非目标列表
2. 通过 AskUserQuestion 一次性展示推断出的非目标；用户可确认，也可使用自动添加的 Other 响应完整替换列表
3. 确认非目标后生成

自动模式（--auto --issue ）

由 GitHub Issue 驱动的非交互式生成。完整流程请参阅 references/auto-mode.md（.ja.md）。概要：

1. gh issue view <n> 提供需求来源
2. 根据 Issue 标题以 kebab-case 格式生成特性名称
3. 生成全部四份文档，不调用任何 AskUserQuestion
4. 将所有原本需要提问的事项作为 ASM-XXX 假设写入 requirement.md

适用于编排式流水线和内容足够具体的 Issue。

完整工作流（full）

按顺序生成全部四份文档：

1. 生成 requirement.md
2. 读取 requirement.md → 生成 design.md
3. 读取 design.md → 生成 tasks.md
4. 读取 requirement.md + design.md + tasks.md → 生成 test.md （验收测试计划；请参阅 references/test-plan.md / .ja.md）

步骤 1–3 生成的三份文档保持不变；步骤 4 只读取它们。

需求 ID 系统

规范使用以下 ID 前缀：

• [REQ-XXX]：功能需求
• [NFR-XXX]：非功能需求
• [CON-XXX]：约束
• [ASM-XXX]：假设
• [T-XXX]：实现任务（tasks.md）
• [T-AXX]：验收测试用例（test.md；T-A 前缀可避免与 T- 冲突）

这些 ID 可确保文档之间的可追溯性。

YAGNI 原则

在确定范围前，请完整阅读 references/yagni-guardrails.md （日语版见 .ja.md）；应用其中列出的所有防护措施。

完成后的操作

每个阶段结束后，使用 AskUserQuestion 建议后续操作：

init 后：

question: "Requirements document generated. What's next?"
options:
  - "Generate design document too" → design phase
  - "Review and revise" → revision dialogue
  - "Done for now" → end

design 后：

question: "Design document generated. What's next?"
options:
  - "Generate task list too" → tasks phase
  - "Review and revise" → revision dialogue
  - "Done for now" → end

tasks 后：

question: "Task list generated. What's next?"
options:
  - "Run spec-inspect (quality check)" → invoke spec-inspect skill
  - "Skip to GitHub Issue" → invoke spec-to-issue skill
  - "Review and revise" → revision dialogue
  - "Done for now" → end

full 后：

question: "All four spec documents (3-set + test.md) are complete."
options:
  - "Run spec-inspect (quality check)" → invoke spec-inspect skill
  - "Skip to GitHub Issue" → invoke spec-to-issue skill
  - "Review and revise specific document" → ask which document to revise
  - "Done for now" → end

使用示例

# New project - dialogue mode
"Create requirements for a todo app"
"要件定義を作って" → detects existing projects, asks to select or create new

# Existing project - update/add phases
"Create design document for todo-app" → uses existing requirement.md as context
「todo-appのタスクリストを作って」 → uses existing design.md as context

# Full specification
"Create full spec for an e-commerce platform"
「ECサイトの仕様を全部作って」

# Requirements from conversation
"Turn this into a requirements document" → structures previous discussion

# Quick mode
"Create requirements for a blog platform --quick"

# Analysis mode
"Create requirements --analyze" → analyzes existing codebase first