Back to Details

speckit-baseline

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec Kit Baseline Skill

Spec Kit 基础技能

When to Use

使用场景

  • You need a spec for existing or legacy code.
  • You want to document a feature before refactoring.
  • You inherited a codebase without written requirements.
  • 你需要为现有或遗留代码编写规格说明书。
  • 你希望在重构前记录功能细节。
  • 你接手了一个没有书面需求的代码库。

Inputs

输入信息

  • A target path, file list, or glob pattern describing the code to analyze.
  • Repo context with 
    .specify/
    scripts and templates.
If the target is missing or ambiguous, ask a focused question before continuing.
  • 用于描述待分析代码的目标路径、文件列表或通配符模式。
  • 包含 
    .specify/
    脚本和模板的仓库上下文。
如果目标缺失或不明确，请先提出针对性问题再继续。

Goal

目标

Generate a technology-agnostic spec for existing code, then create the feature branch/spec file using the standard Spec Kit templates.
为现有代码生成与技术无关的规格说明书，然后使用标准 Spec Kit 模板创建功能分支/规格文件。

Workflow

工作流程

  1. Parse target input: Identify files, directories, or patterns to analyze.
    • Accept file paths, glob patterns, or directory paths.
    • If empty: stop and ask for a concrete target.
  2. Discover and read source files:
    • Expand globs to a file list.
    • Read file contents for analysis.
    • Identify primary language(s) and frameworks.
    • Map key file relationships and dependencies.
  3. Analyze code structure:
    • Identify entry points and public interfaces.
    • Extract function/method signatures and behaviors.
    • Find data models and entities.
    • Detect API endpoints and routes.
    • Identify user-facing functionality.
  4. Generate a short name (2-4 words) from the analyzed code:
    • Use action-noun format (e.g., "user-auth", "payment-processing").
    • Base on primary functionality discovered.
    • Preserve technical terms where meaningful.
  5. Create the feature branch and spec file:
    • Find the highest existing feature number for this short name (branches/specs).
    • Run 
      .specify/scripts/bash/create-new-feature.sh --json
      with the calculated number and short name.
    • Read BRANCH_NAME, FEATURE_DIR, and SPEC_FILE paths from the script JSON output.
    • For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").
  6. Load the spec template from 
    .specify/templates/spec-template.md
    .
  7. Draft the specification using the template structure:
    • User Stories: Infer from user-facing code paths and interactions.
    • Acceptance Scenarios: Derive from validation logic, error handling, and tests.
    • Functional Requirements: Extract from business rules and constraints.
    • Key Entities: Identify from data models and schemas.
    • Success Criteria: Infer from metrics, logging, or performance-related code.
    • Assumptions: Document inferences made during analysis.
  8. Abstract implementation details:
    • Convert technical patterns to user-focused requirements.
    • Remove framework-specific terminology.
    • Focus on WHAT the code does, not HOW it does it.
  9. Create spec quality checklist at 
    FEATURE_DIR/checklists/requirements.md
    .
  10. Report completion with:
    • Branch name and spec file path.
    • Summary of analyzed files.
    • Key features discovered.
    • Areas needing clarification or review.
  1. 解析目标输入：确定要分析的文件、目录或模式。
    • 接受文件路径、通配符模式或目录路径。
    • 如果为空：停止操作并请求明确的目标。
  2. 发现并读取源文件：
    • 将通配符扩展为文件列表。
    • 读取文件内容以进行分析。
    • 识别主要语言和框架。
    • 映射关键文件关系和依赖项。
  3. 分析代码结构：
    • 识别入口点和公共接口。
    • 提取函数/方法签名和行为。
    • 查找数据模型和实体。
    • 检测 API 端点和路由。
    • 识别面向用户的功能。
  4. 从分析的代码中生成简短名称（2-4个词）：
    • 使用动作-名词格式（例如："user-auth"、"payment-processing"）。
    • 基于发现的主要功能。
    • 在有意义的地方保留技术术语。
  5. 创建功能分支和规格文件：
    • 查找该简短名称对应的现有最高功能编号（分支/规格）。
    • 使用计算出的编号和简短名称运行 
      .specify/scripts/bash/create-new-feature.sh --json
      。
    • 从脚本的 JSON 输出中读取 BRANCH_NAME、FEATURE_DIR 和 SPEC_FILE 路径。
    • 对于参数中的单引号（如 "I'm Groot"），使用转义语法：例如 'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。
  6. 从 
    .specify/templates/spec-template.md
    加载规格模板    。
  7. 使用模板结构起草规格说明书：
    • 用户故事：从面向用户的代码路径和交互中推断。
    • 验收场景：从验证逻辑、错误处理和测试中推导。
    • 功能需求：从业务规则和约束中提取。
    • 关键实体：从数据模型和模式中识别。
    • 成功标准：从指标、日志或性能相关代码中推断。
    • 假设条件：记录分析过程中做出的推断。
  8. 抽象实现细节：
    • 将技术模式转换为以用户为中心的需求。
    • 移除特定于框架的术语。
    • 关注代码做什么，而不是怎么做。
  9. 在 
    FEATURE_DIR/checklists/requirements.md
    创建规格质量检查表    。
  10. 完成报告，包含：
    • 分支名称和规格文件路径。
    • 已分析文件的摘要。
    • 发现的关键功能。
    • 需要澄清或审查的领域。

Outputs

输出

  • specs/<feature>/spec.md
  • specs/<feature>/checklists/requirements.md
  • specs/<feature>/spec.md
  • specs/<feature>/checklists/requirements.md

Key rules

关键规则

  • Focus on extracting WHAT and WHY from HOW.
  • Abstract away implementation details in the generated spec.
  • Document assumptions made during code analysis.
  • Flag areas where code behavior is unclear.
  • Preserve discovered business rules and constraints.
  • Use 
    [NEEDS CLARIFICATION]
    for ambiguous code sections (max 3).
  • Generated specs should be validated by someone who knows the feature.
  • 专注于从实现方式（HOW）中提取功能（WHAT）和原因（WHY）。
  • 在生成的规格说明书中抽象掉实现细节。
  • 记录代码分析过程中做出的假设。
  • 标记代码行为不明确的领域。
  • 保留发现的业务规则和约束。
  • 对模糊的代码部分使用 
    [NEEDS CLARIFICATION]
    （最多3处）。
  • 生成的规格说明书应由了解该功能的人员进行验证。

Examples

示例

Code Pattern → Spec Requirement:
  • if (user.role === 'admin')
    → "System MUST restrict action to administrator users"
  • password.length >= 8
    → "Passwords MUST be at least 8 characters"
  • cache.set(key, value, 3600)
    → "System MUST cache results for improved performance"
  • try { ... } catch (e) { notify(e) }
    → "System MUST notify users when errors occur"
Code Pattern → User Story:
  • Login endpoint with OAuth → "As a user, I can sign in using my social account"
  • Shopping cart logic → "As a customer, I can add items to my cart for later purchase"
  • Report generation → "As an analyst, I can generate reports on system activity"
代码模式 → 规格需求：
  • if (user.role === 'admin')
    → "系统必须将操作限制为管理员用户"
  • password.length >= 8
    → "密码长度必须至少为8个字符"
  • cache.set(key, value, 3600)
    → "系统必须缓存结果以提升性能"
  • try { ... } catch (e) { notify(e) }
    → "系统必须在发生错误时通知用户"
代码模式 → 用户故事：
  • 带有 OAuth 的登录端点 → "作为用户，我可以使用社交账户登录"
  • 购物车逻辑 → "作为客户，我可以将商品添加到购物车以便稍后购买"
  • 报告生成 → "作为分析师，我可以生成系统活动报告"

Next Steps

后续步骤

After generating spec.md:
  • Clarify with domain experts using speckit-clarify.
  • Plan modernization/refactoring with speckit-plan.
  • Compare the generated spec with actual requirements to identify gaps.
生成 spec.md 后：
  • 使用 speckit-clarify 与领域专家澄清疑问。
  • 使用 speckit-plan 规划现代化/重构工作。
  • 将生成的规格说明书与实际需求进行比较，找出差距。