Back to Details

project-specification

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Table of Contents

目录

Project Specification Skill

项目规格说明技能

Transform project briefs into structured, testable specifications with acceptance criteria.
将项目简报转换为结构化、可测试且带有验收标准的规格说明。

When To Use

何时使用

  • After brainstorming phase completes
  • Have project brief but need detailed requirements
  • Need testable acceptance criteria for implementation
  • Planning validation and testing strategy
  • Translating business requirements into technical specs
  • Defining scope boundaries and out-of-scope items
  • 头脑风暴阶段完成后
  • 已有项目简报但需要详细需求
  • 需要为实现阶段提供可测试的验收标准
  • 规划验证与测试策略
  • 将业务需求转换为技术规格说明
  • 定义范围边界与范围外内容

When NOT To Use

何时不使用

  • Still exploring problem space (use 
    Skill(attune:project-brainstorming)
    instead)
  • Already have detailed specification (use 
    Skill(attune:project-planning)
    instead)
  • Refining existing implementation (use code review skills)
  • Making strategic decisions (use 
    Skill(attune:war-room)
    for complex choices)
  • 仍处于问题探索阶段（请改用 
    Skill(attune:project-brainstorming)
    ）
  • 已有详细规格说明（请改用 
    Skill(attune:project-planning)
    ）
  • 优化现有实现（使用代码审查类技能）
  • 制定战略决策（复杂决策请使用 
    Skill(attune:war-room)
    ）

Integration

集成

With spec-kit:
  • Delegates to 
    Skill(spec-kit:spec-writing)
    for methodology
  • Uses spec-kit templates and validation
  • Enables clarification workflow
Without spec-kit:
  • Standalone specification framework
  • Requirement templates
  • Acceptance criteria patterns
与spec-kit集成：
  • 委托 
    Skill(spec-kit:spec-writing)
    提供方法论支持
  • 使用spec-kit模板与验证机制
  • 启用澄清工作流
不使用spec-kit：
  • 独立的规格说明框架
  • 需求模板
  • 验收标准模式

Specification Structure

规格说明结构

1. Overview Section

1. 概述部分

  • Purpose: What the project achieves (1-2 sentences)
  • Scope: IN/OUT boundaries
  • Stakeholders: Who cares and why
  • 目的：项目要实现的目标（1-2句话）
  • 范围：包含/排除的边界
  • 利益相关者：相关人员及其关注点

2. Functional Requirements (FR-XXX)

2. 功能需求（FR-XXX）

Format per requirement:
markdown
undefined
每个需求的格式：
markdown
undefined

FR-001: [Requirement Name]

FR-001: [需求名称]

Description: Clear, unambiguous description
Acceptance Criteria:
  • Given [context], when [action], then [expected result]
  • Given [context], when [action], then [expected result]
Priority: High | Medium | Low Dependencies: FR-002, FR-005 Estimated Effort: S | M | L | XL
**Verification:** Run the command with `--help` flag to verify availability.

**Validation Rules**:
- Description has no ambiguous words (might, could, maybe, probably)
- At least 2 acceptance criteria (happy path + error case)
- Criteria use Given-When-Then format
- Criteria are testable (observable outcomes)
- Dependencies are explicit
描述：清晰、无歧义的描述
验收标准：
  • 给定[上下文]，当[执行操作]，则[预期结果]
  • 给定[上下文]，当[执行操作]，则[预期结果]
优先级：高 | 中 | 低 依赖项：FR-002, FR-005 预估工作量：S | M | L | XL
**验证方式**：运行命令时添加`--help`参数以确认可用性。

**验证规则**：
- 描述中无模糊词汇（might, could, maybe, probably等）
- 至少包含2条验收标准（正常流程 + 错误场景）
- 标准采用Given-When-Then格式
- 标准可测试（结果可观测）
- 依赖项明确

3. Non-Functional Requirements (NFR-XXX)

3. 非功能需求（NFR-XXX）

Categories:
  • Performance: Response times, throughput, resource limits
  • Security: Authentication, authorization, data protection, compliance
  • Reliability: Uptime, error handling, recovery, fault tolerance
  • Usability: UX requirements, accessibility, documentation
  • Maintainability: Code quality, testing, observability
Format:
markdown
undefined
类别：
  • 性能：响应时间、吞吐量、资源限制
  • 安全：身份验证、授权、数据保护、合规性
  • 可靠性：可用性、错误处理、恢复能力、容错性
  • 易用性：UX需求、可访问性、文档
  • 可维护性：代码质量、测试、可观测性
格式：
markdown
undefined

NFR-001: [Category] - [Requirement]

NFR-001: [类别] - [需求]

Requirement: [Specific, measurable requirement]
Measurement: [How to verify]
  • Metric: [What to measure]
  • Target: [Specific threshold]
  • Tool: [How to measure]
Priority: Critical | High | Medium | Low
**Verification:** Run the command with `--help` flag to verify availability.
需求：[具体、可衡量的需求]
衡量方式：[验证方法]
  • 指标：[要测量的内容]
  • 目标：[具体阈值]
  • 工具：[测量工具]
优先级：关键 | 高 | 中 | 低
**验证方式**：运行命令时添加`--help`参数以确认可用性。

4. Technical Constraints

4. 技术约束

  • Technology stack selections with rationale
  • Integration requirements
  • Data requirements (schema, migrations)
  • Deployment constraints
  • Regulatory/compliance requirements
  • 技术栈选择及理由
  • 集成需求
  • 数据需求（schema、迁移）
  • 部署约束
  • 监管/合规要求

5. Out of Scope

5. 范围外内容

Explicit exclusions to prevent scope creep:
markdown
undefined
明确排除项，以防止范围蔓延：
markdown
undefined

Out of Scope (v1.0)

范围外内容（v1.0）

  • [Feature explicitly NOT included]
  • [Capability deferred to later version]
  • [Integration not planned]
Rationale: [Why these are excluded]
**Verification:** Run the command with `--help` flag to verify availability.
  • [明确不包含的功能]
  • [推迟到后续版本的能力]
  • [未计划的集成]
理由：[为何排除这些内容]
**验证方式**：运行命令时添加`--help`参数以确认可用性。

Clarification Workflow

澄清工作流

Ambiguity Detection

歧义检测

Scan specification for:
  • Vague quantifiers (many, few, several, most)
  • Ambiguous terms (user-friendly, fast, scalable)
  • Missing dependencies
  • Untestable criteria
  • Conflicting requirements
扫描规格说明中的以下内容：
  • 模糊量词（many, few, several, most等）
  • 模糊术语（user-friendly, fast, scalable等）
  • 缺失的依赖项
  • 不可测试的标准
  • 冲突的需求

Question Generation

问题生成

For each ambiguity:
markdown
**Question [N]**: [Reference to FR/NFR]

**Ambiguity**: [What is unclear]

**Impact**: [Why this matters]

**Options**:
- Option A: [Interpretation 1]
- Option B: [Interpretation 2]

**Recommendation**: [Preferred option with rationale]
Verification: Run the command with 
--help
flag to verify availability.
针对每个歧义点：
markdown
**问题[N]**：[参考FR/NFR编号]

**歧义点**：[不清晰的内容]

**影响**：[为何这一点很重要]

**选项**：
- 选项A：[解释1]
- 选项B：[解释2]

**建议**：[推荐选项及理由]
验证方式：运行命令时添加
--help
参数以确认可用性。

Clarification Session

澄清会议

Run interactive Q&A:
  1. Present all questions
  2. Gather stakeholder responses
  3. Update specification
  4. Re-validate for new ambiguities
  5. Iterate until clear
运行交互式问答：
  1. 展示所有问题
  2. 收集利益相关者的反馈
  3. 更新规格说明
  4. 重新验证是否存在新的歧义
  5. 迭代直至内容清晰

Quality Checks

质量检查

Before completing specification:
  • ✅ All requirements have unique IDs (FR-XXX, NFR-XXX)
  • ✅ All functional requirements have ≥2 acceptance criteria
  • ✅ All criteria use Given-When-Then format
  • ✅ No ambiguous language detected
  • ✅ Dependencies documented
  • ✅ Effort estimates provided
  • ✅ Out of scope explicitly stated
  • ✅ Success criteria defined
完成规格说明前，请检查：
  • ✅ 所有需求都有唯一ID（FR-XXX、NFR-XXX）
  • ✅ 所有功能需求都包含≥2条验收标准
  • ✅ 所有标准采用Given-When-Then格式
  • ✅ 未检测到模糊语言
  • ✅ 依赖项已记录
  • ✅ 提供了工作量预估
  • ✅ 明确说明了范围外内容
  • ✅ 定义了成功标准

Output Format

输出格式

Save to 
docs/specification.md
:
markdown
undefined
保存至
docs/specification.md
：
markdown
undefined

[Project Name] - Specification v[version]

[项目名称] - 规格说明 v[版本号]

Author: [Name] Date: [YYYY-MM-DD] Status: Draft | Review | Approved | Implemented
作者：[姓名] 日期：[YYYY-MM-DD] 状态：草稿 | 评审中 | 已批准 | 已实现

Change History

变更历史

VersionDateAuthorChanges
0.1.02026-01-02AlexInitial draft
版本日期作者变更内容
0.1.02026-01-02Alex初始草稿

Overview

概述

Purpose: [1-2 sentence purpose]
Scope:
  • IN: [What's included]
  • OUT: [What's excluded]
Stakeholders:
  • [Stakeholder 1]: [Their interest]
  • [Stakeholder 2]: [Their interest]
目的：[1-2句话说明目的]
范围：
  • 包含：[包含的内容]
  • 排除：[排除的内容]
利益相关者：
  • [利益相关者1]：[他们的关注点]
  • [利益相关者2]：[他们的关注点]

Functional Requirements

功能需求

[FR-XXX sections]
[FR-XXX章节内容]

Non-Functional Requirements

非功能需求

[NFR-XXX sections]
[NFR-XXX章节内容]

Technical Constraints

技术约束

[Technology, integration, data, deployment]
[技术、集成、数据、部署相关内容]

Out of Scope

范围外内容

[Explicit exclusions with rationale]
[明确的排除项及理由]

Dependencies

依赖项

[External dependencies, third-party services]
[外部依赖项、第三方服务]

Acceptance Testing Strategy

验收测试策略

[How requirements will be validated]
[如何验证需求]

Success Criteria

成功标准

  • [Measurable success indicator 1]
  • [Measurable success indicator 2]
  • [可衡量的成功指标1]
  • [可衡量的成功指标2]

Glossary

术语表

[Domain terms and definitions]
[领域术语及定义]

References

参考资料

[Related documents, research, prior art]
**Verification:** Run `pytest -v` to verify tests pass.
[相关文档、研究、已有成果]
**验证方式**：运行`pytest -v`以确认测试通过。

Acceptance Criteria Patterns

验收标准模式

Given-When-Then

Given-When-Then

markdown
Given [initial context/state]
When [action occurs]
Then [expected outcome]
Verification: Run the command with 
--help
flag to verify availability.
Examples:
  • Given unauthenticated user, when accessing dashboard, then redirect to login
  • Given valid credentials, when logging in, then create session and redirect to dashboard
  • Given expired session, when making API request, then return 401 Unauthorized
markdown
Given [初始上下文/状态]
When [执行操作]
Then [预期结果]
验证方式：运行命令时添加
--help
参数以确认可用性。
示例：
  • Given 未认证用户，当访问仪表板时，Then 重定向至登录页
  • Given 有效凭据，当登录时，Then 创建会话并重定向至仪表板
  • Given 过期会话，当发起API请求时，Then 返回401 Unauthorized

Error Cases

错误场景

Always include error scenarios:
  • Invalid input handling
  • Authentication/authorization failures
  • Network/service failures
  • Resource exhaustion
  • Edge cases and boundaries
务必包含错误场景：
  • 无效输入处理
  • 身份验证/授权失败
  • 网络/服务故障
  • 资源耗尽
  • 边缘情况与边界值

Performance Criteria

性能标准

Make performance requirements testable:
  • "Dashboard loads in < 2 seconds" (measurable)
  • NOT "Dashboard is fast" (vague)
让性能需求可测试：
  • "仪表板加载时间<2秒"（可衡量）
  • 而非"仪表板速度快"（模糊）

Security Criteria

安全标准

Make security requirements verifiable:
  • "All API endpoints require authentication" (testable)
  • NOT "System is secure" (vague)
让安全需求可验证：
  • "所有API端点均需身份验证"（可测试）
  • 而非"系统是安全的"（模糊）

Related Skills

相关技能

  • Skill(spec-kit:spec-writing)
    - Spec-kit methodology (if available)
  • Skill(attune:project-brainstorming)
    - Previous phase
  • Skill(attune:project-planning)
    - Next phase
  • Skill(spec-kit:spec-writing)
    - Spec-kit方法论（若可用）
  • Skill(attune:project-brainstorming)
    - 上一阶段技能
  • Skill(attune:project-planning)
    - 下一阶段技能

Related Commands

相关命令

  • /attune:specify
    - Invoke this skill
  • /attune:specify --clarify
    - Run clarification workflow
  • /attune:blueprint
    - Next step in workflow
  • /attune:specify
    - 调用此技能
  • /attune:specify --clarify
    - 运行澄清工作流
  • /attune:blueprint
    - 工作流的下一步

Examples

示例

See 
/attune:specify
command documentation for complete examples.
查看
/attune:specify
命令文档获取完整示例。

Troubleshooting

故障排除

Common Issues

常见问题

Command not found Ensure all dependencies are installed and in PATH
Permission errors Check file permissions and run with appropriate privileges
Unexpected behavior Enable verbose logging with 
--verbose
flag
命令未找到 确保所有依赖项已安装且在PATH中
权限错误 检查文件权限并使用适当权限运行
意外行为 添加
--verbose
参数启用详细日志