SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsspec-interview

spec-interview

Coding & development

View repository

Updated 10-15 20:05

About this skill

Specification Interview Skill

Overview

Through in-depth Socratic interviews, transform draft specifications into complete, executable technical documents. After the interviews are completed, automatically create an OpenSpec proposal to enable Spec-Driven Development.

Core Features

  • Systematic requirements interviewing and refinement
  • Engineering principles review (KISS, YAGNI, DRY, SOLID)
  • Technical solution design and trade-off analysis
  • Automatically generate an OpenSpec proposal
  • Risk identification and mitigation strategy formulation

Workflow

1. Document Reading and Analysis

Read plan.md or a user-specified document, and analyze:

  • Core business goals and value proposition
  • Completeness of the existing technical solution
  • Ambiguous or missing key information
  • Potential technical debt and risk points

2. Systematic Interview

Use AskUserQuestionTool to conduct multi-dimensional in-depth interviews:

A. Engineering Principles Review (Required)

Simplicity Check (KISS & YAGNI)

  • Is this feature required for the MVP? Can it be deferred to a later iteration?
  • Is there a simpler solution that can achieve 80% of the effect?
  • Is the current level of abstraction reasonable? Is there over-engineering?

Duplication Identification (DRY)

  • Identify similar logic patterns and evaluate the feasibility of abstracting them into a common module
  • Will the configuration pattern recur in the project?
  • Can duplication be reduced through code generation or templates?

Architectural Robustness (SOLID)

  • Does the module have a single responsibility? Does it bear too many responsibilities?
  • Does the interface design support future extension?
  • Are the dependencies reasonable? Is there a risk of circular dependencies?

B. Technical Implementation Details

  • Basis for technology stack selection and comparison of alternatives
  • Performance impact of data structure and algorithm choices
  • Performance bottleneck prediction and optimization strategies
  • Necessity, licenses, and maintenance risks of third-party dependencies
  • Testing strategy (unit testing, integration testing, E2E, performance testing)

C. API Design (if applicable)

  • Clarity of API titles and descriptions
  • Logical grouping of resource paths and operations
  • Completeness of request/response models
  • Authentication and authorization mechanisms
  • Error handling and status code design
  • Versioning strategy
  • Pagination, filtering, and sorting specifications
  • Idempotency and concurrency control

D. UI/UX Design (if applicable)

  • Completeness and consistency of user interaction flows
  • UI feedback for edge cases (loading, errors, empty states, network exceptions)
  • Responsive design and cross-device compatibility
  • Accessibility (WCAG standards)
  • Internationalization and localization requirements

E. Risks and Trade-offs

  • Acceptable level of technical debt and repayment plan
  • Security considerations (authentication, authorization, data encryption, input validation)
  • Balance between maintainability vs development speed
  • Cost estimation (development time, infrastructure, operations cost)
  • Vendor lock-in risk

F. Edge cases and exception handling

  • Network exceptions, timeouts, retry mechanisms
  • Concurrency conflicts and data consistency guarantees
  • Fallback plans and fault-tolerant design
  • Logging and monitoring strategy
  • Disaster recovery and business continuity

G. Project conventions and standards

  • Shell script cross-platform compatibility (Bash/PowerShell)
  • Documentation format and metadata standards (Markdown frontmatter)
  • Target platform deployment requirements (Claude Code/Codex CLI)
  • Code style and Lint rules
  • Git workflow and branching strategy

3. High-risk operation detection

If the specification involves the following operations, proactive reminders will be given:

⚠️ 高风险操作检测
操作类型：[文件删除 / Git 强制推送 / 环境变量修改 / 数据库结构变更 / 批量依赖更新]
影响范围：[具体描述]
建议措施：
  - 回滚方案：[具体步骤]
  - 备份策略：[备份内容与频率]
  - 测试要求：[测试环境与验证标准]
请确认是否继续执行。

4. Create OpenSpec Proposal

After the interview is completed, the system will automatically call the OpenSpec workflow to create a proposal:

Invocation method

Depending on the AI tool the user is using, use the corresponding command:

Claude Code / Codex / Qoder / RooCode:

/openspec:proposal

Cursor / Continue / GitHub Copilot / Windsurf:

/openspec-proposal

Other tools (AGENTS.md compatible):

请创建一个 OpenSpec proposal

OpenSpec output structure

openspec/
├── changes/
│   └── <change-name>/
│       ├── proposal.md          # 变更提案
│       ├── tasks.md             # 任务清单
│       └── specs/               # 规格差异（delta）
│           └── <spec-name>/
│               └── spec.md      # 规格变更
└── specs/                       # 当前规格（归档后更新）
    └── <spec-name>/
        └── spec.md

Content of the generated files

1. Proposal (openspec/changes/<change-name>/proposal.md)

  • Change overview and business value
  • Technical solution and architecture decisions
  • Engineering principles review results
  • Risk assessment and mitigation measures
  • Success metrics and acceptance criteria

2. Tasks (openspec/changes/<change-name>/tasks.md)

  • Implementation task list (based on interview results)
  • Priority ranking (high/medium/low)
  • Task dependencies
  • Estimated effort

3. Spec Deltas (openspec/changes/<change-name>/specs/*/spec.md)

Use delta format to mark changes:

## 新增功能

+++ 新增的内容描述
+++ 包括接口定义、数据模型等

## 修改功能

--- 删除的旧内容
+++ 新增的替代内容

## 删除功能

--- 删除的内容描述

5. Follow-up workflow

After creating the proposal, the user can:

  1. Review and refine

    • Check the generated proposal and specs
    • Adjust and supplement as needed

  2. Implement changes

    • Use /openspec:apply or /openspec-apply command
    • The system will implement step by step according to tasks.md

  3. Archive changes

    • After implementation is complete, use /openspec:archive or /openspec-archive
    • Merge spec deltas into openspec/specs/ in

Technical constraints

  • Path representation: Use double quotes and forward slashes /
  • Search tools: Prefer rg over grep
  • Git strategy: Do not perform commit or branch operations unless explicitly requested
  • Code understanding: Follow the Read-before-Write principle

Questioning principles

  1. Depth first: Avoid obvious questions, dig into hidden assumptions and risks
  2. Structured: Ask questions in the order of engineering principles → technical details → risk trade-offs
  3. Guided: Help users think about "why" rather than just "what"
  4. Pragmatic: Focus on implementability, avoid excessive theorizing
  5. Context-aware: Adjust interview focus according to project type (API/CLI/library/application)

Usage example

Trigger method

  • "Help me improve this plan"
  • "Conduct an in-depth interview on this technical solution"
  • "Create a spec proposal"
  • "spec-driven development"

Typical Conversation Flow

Step 1: Start the Interview

User: Help me refine this plan

System: Read plan.md. This project plans to build a user management API. Before starting the interview, please confirm: Is this a public-facing API or an internal service?

Step 2: In-Depth Questioning

User: Internal service

System: Understood. Regarding the authentication mechanism, internal services usually have several options:

  1. Shared secret between services (simple but less secure)
  2. mTLS (high security but complex to configure)
  3. Internal OAuth 2.0 (flexible but requires additional infrastructure)

Considering your team size and operational capabilities, which approach do you prefer? Or is there already a unified internal authentication standard?

Step 3: Engineering Principles Review

System: Regarding user role management, how many roles are planned to be supported? Is this an essential feature for the MVP?

According to the YAGNI principle, if only two roles—administrator and regular user—are needed initially, it is recommended to first implement a simple binary permission model and later extend it to RBAC. This can reduce development time by 30-40%. What is your view?

Step 4: Create OpenSpec Proposal

System: Interview complete! Now creating an OpenSpec proposal for you...

[Call /openspec:proposal or equivalent command]

✅ Created proposal: openspec/changes/user-management-api/

Next steps:

  1. Review proposal.md and tasks.md
  2. Use /openspec:apply to start implementation
  3. When complete, use /openspec:archive to archive

Integration Advantages with OpenSpec

  1. Requirement Lock-In: Interview results are solidified into a proposal, preventing requirements from being lost in chat history
  2. Traceability: All decisions and trade-offs are recorded in the proposal
  3. Reviewability: Team members can review the proposal without reading code
  4. Incremental Development: Spec deltas clearly show the impact scope of each change
  5. Documentation Sync: After archiving, living specs are automatically updated, keeping documentation consistent with code

Best Practices

  • Be Well Prepared: Prepare business context and constraints before the interview
  • Answer Honestly: For uncertain questions, you can request multiple options and their trade-off analysis
  • Iterative Refinement: After the proposal is created, you can continue the interview to refine it
  • Team Collaboration: Share the proposal with team members for review
  • Continuous Archiving: Archive completed changes promptly to keep the specs directory accurate

Reference Resources