Spec（规格说明书）与Skill（技能库）实操指南

第一部分：Spec（规格说明书）

核心定位：Spec是软件工程的"需求与规范基准"，明确"做什么"和"按什么标准做"，面向全团队（产品、开发、测试），是功能落地、技术实现的核心依据，贯穿软件工程全流程。

一、软件工程概要（Spec应用背景，极简版）

核心定义：软件工程是一门将系统化、规范化、可度量的方法应用于软件的开发、运行和维护的学科，核心是"用规范流程打造高质量软件"，避免开发无序、后期维护困难。

核心目标：高效交付"规范、可维护、高质量"的软件，杜绝开发混乱、代码杂乱、反复返工等问题，确保软件长期稳定可用。

大致流程：需求分析（拆解用户需求，明确"做什么"）→ 设计（确定架构、接口，明确"怎么设计"）→ 编码（编写代码，落地实现）→ 测试（排查bug，确保达标）→ 维护（修复线上问题、迭代功能，保障长期可用），全程围绕"规范"推进，每一步均有依据、可追溯。

软件工程核心流程图表

拆解用户需求，明确边界
定架构、接口规范
按规范写代码，自查
找bug、修bug，验证达标
修问题/新增功能，更新规范
需求分析
设计阶段
编码阶段
测试阶段
维护与迭代

二、Spec 核心分类与内容（必写，不冗余）

在软件工程中，Spec（规格说明）主要分为「功能Spec」和「Skill Spec」两类，两者相辅相成、各司其职，共同解决"做什么、怎么做、按什么标准做"的问题。

（一）功能Spec（功能规格说明）

核心定位：聚焦"软件要实现什么功能"，面向产品、开发、测试全团队，明确功能的具体表现、交互逻辑，是需求落地的核心依据，不涉及具体技术实现和编码细节。

必写4个关键（极简）：

• 1. 功能描述：明确该功能的核心用途（例：用户登录功能，用于校验用户身份、生成登录凭证）；
• 2. 交互逻辑：明确用户操作步骤与系统反馈（例：用户输入账号密码→点击登录→系统校验→校验成功跳转首页/失败提示错误）；
• 3. 功能边界：明确该功能包含/不包含的子功能（例：登录功能包含账号密码校验，不包含第三方登录）；
• 4. 异常场景：明确功能异常时的表现（例：密码错误提示"用户名或密码不正确"，参数为空提示"请填写必填项"）。

（二）Skill Spec（技能规格说明）

核心定位：聚焦"怎么实现功能"，面向开发人员，是功能Spec的"技术落地手册"，明确实现功能所需的技术、规范和标准，承接功能Spec的需求，落地到具体编码。

必写5个关键（极简）：

• 1. 技能边界：明确开发范围（对应功能Spec，不超出功能边界，不额外开发）；
• 2. 技术栈：指定编程语言、框架、辅助工具（如Java+SpringBoot、Redis）；
• 3. 编码/接口规范：统一变量命名、注释、接口格式（确保代码规范）；
• 4. 约束要求：明确性能（如接口响应<500ms）、安全（如密码加密）等技术约束；
• 5. 测试标准：明确单元测试覆盖率、核心测试场景（确保开发达标）。

核心原则：两者均需"写具体、不模糊"（例：不说"优化性能"，说"单条数据处理≤10ms"；不说"功能正常"，说"密码错误提示具体文案"）。

第二部分：Skill（技能库）

核心定位：Skill是Spec的"落地执行手册"，聚焦"具体怎么做"，面向开发人员，整合Spec落地所需的全流程实操技能、关键技巧，确保Spec能高效、规范落地到编程全流程。

一、Skill Spec 全流程具体实操做法（核心重点，一看就会）

贴合软件工程流程，承接第一部分Spec内容，每步只讲"具体怎么做"，聚焦实操落地，确保开发人员能对照执行：

（一）需求分析阶段（对应软件工程流程第一步）

具体做法：

1. 结合产品需求（PRD），编写「功能Spec」，明确功能描述、交互逻辑、边界和异常场景；

2. 和产品、测试、前后端团队评审功能Spec，确认需求无歧义、边界清晰；

3. 基于评审通过的功能Spec，初步确定Skill Spec的核心技术栈和技能边界。

（二）设计阶段（对应软件工程流程第二步）

具体做法：

1. 完善「Skill Spec」，明确模块结构（如MVC）、函数规范、接口格式、技术约束，确保贴合功能Spec；

2. 模块级设计：每个模块（如用户模块）的Skill Spec，明确依赖关系（不随便依赖其他模块）；

3. 接口级设计：写清接口地址、请求参数、响应格式、异常处理（如登录接口密码错误返回code=402）。

（三）编码阶段（对应软件工程流程第三步）

具体做法：

1. 编码前：仔细查看Skill Spec，明确技术栈、命名规范、性能和安全约束，做到心中有数；

2. 编码中：逐行对照Skill Spec，避免无注释、命名混乱、异常未处理，不偏离规范；

3. 编码后：自我检查，确认代码符合Skill Spec的所有要求（规范、性能、安全），避免遗留问题。

（四）测试阶段（对应软件工程流程第四步）

具体做法：

1. 写单元测试：对照Skill Spec，覆盖核心测试场景，确保单元测试覆盖率达标；

2. 配合测试：将功能Spec、Skill Spec提供给测试人员，协助设计集成测试用例（兼顾功能和技术达标）；

3. 修复bug：对照两个Spec找bug根源（如功能不达标查功能Spec，编码不规范查Skill Spec），修完后再次自查、复测。

（五）维护与迭代阶段（对应软件工程流程第五步）

具体做法：

1. 维护：排查线上问题时，先看功能Spec（确认功能预期），再看Skill Spec（确认技术规范），快速定位问题根源；

2. 迭代：新增功能/优化功能时，先更新「功能Spec」，再同步更新「Skill Spec」，确保两者一致；

3. 传承：将两个Spec与代码同步归档，方便新员工快速了解需求和技术规范，快速上手工作。

第三部分：简单实操案例（Spec落地场景，一看就懂）

案例：实现"简单用户登录功能"，结合功能Spec、Skill Spec，贯穿软件工程全流程（贴合上述流程图表）

1. 需求分析阶段：输出「功能Spec」，明确登录功能的描述、交互逻辑、边界和异常场景，团队评审确认；

2. 设计阶段：基于功能Spec，输出「Skill Spec」，明确技术栈、编码规范、接口格式，确定模块结构；

3. 编码阶段：对照Skill Spec写代码，确保符合规范；

4. 测试阶段：对照功能Spec（查功能是否达标）+ Skill Spec（查技术是否达标），完成测试、修复bug；

5. 维护迭代：后续新增功能，先更新功能Spec，再同步更新Skill Spec，再开展开发、测试。

Spec markdown实操案例（极简可直接复用）

以下分别提供功能Spec、Skill Spec的markdown案例，贴合"简单用户登录功能"，覆盖核心要点，可直接复制修改使用：

（一）功能Spec markdown案例

# 功能Spec：简单用户登录功能
## 1. 功能描述
用于校验用户账号密码合法性，校验通过后生成登录token，允许用户进入系统；校验失败则提示对应错误信息。

## 2. 交互逻辑
1. 用户在登录页面输入用户名（userName）、密码（password）；
2. 用户点击"登录"按钮；
3. 系统自动校验账号密码是否匹配、参数是否完整；
4. 校验成功：生成登录token，跳转至系统首页；
5. 校验失败：页面不跳转，显示对应错误提示（如密码错误、参数为空）。

## 3. 功能边界
- 包含功能：账号密码校验、错误提示、登录成功跳转、token生成；
- 不包含功能：第三方登录（微信、QQ等）、记住密码、密码找回功能。

## 4. 异常场景
- 场景1：用户名/密码为空 → 提示"请填写用户名和密码"；
- 场景2：用户名不存在 → 提示"用户名或密码不正确"；
- 场景3：密码错误 → 提示"用户名或密码不正确"（统一提示，避免泄露信息）；
- 场景4：登录失败3次 → 提示"登录失败次数过多，请15分钟后再试"。

（二）Skill Spec markdown案例

# Skill Spec：简单用户登录功能
## 1. 技能边界
- 实现范围：对应功能Spec的登录功能，完成账号密码校验、token生成、错误提示、页面跳转；
- 不实现范围：第三方登录、记住密码、密码找回功能，不超出功能Spec边界。

## 2. 技术栈
- 后端语言：Java
- 开发框架：SpringBoot 2.7.x
- 辅助工具：Redis（存储token）、BCrypt（密码加密）、MySQL（存储用户账号密码）

## 3. 编码/接口规范
- 命名规范：变量小驼峰、函数命名前缀统一（查询select/校验check）；
- 注释规范：函数需标注功能、输入参数、输出结果、异常说明；
- 接口规范：
  - 接口地址：/api/user/login
  - 请求方式：POST
  - 请求参数：userName（String，必填）、password（String，必填）
  - 响应格式：{"code":状态码,"message":"提示信息","data":{"token":xxx}}

## 4. 约束要求
- 性能约束：接口响应时间<500ms，单用户登录校验耗时≤10ms；
- 安全约束：密码采用BCrypt加密存储（不明文存储），token有效期2小时，登录失败3次锁定账号15分钟；
- 兼容性约束：适配Java 8+，Redis 6.0+。

## 5. 测试标准
- 单元测试覆盖率：≥80%；
- 核心测试场景：参数为空、用户名不存在、密码错误、登录成功、账号锁定、token生成有效性。

关键技巧（4句话，必看）

1. 精简：两个Spec均只写核心内容，不冗余（功能Spec不写技术，Skill Spec不写产品需求）；

2. 同步：功能Spec更新后，必须同步更新Skill Spec，确保两者一致，避免开发偏离需求；

3. 执行：团队达成共识，代码评审必查Skill Spec、功能测试必查功能Spec；

4. 灵活：小项目可简化Spec（核心要点不缺），大项目需细化（补充细节约束）。

核心总结

Spec（规格说明书）定"做什么、按什么标准做"，是软件工程的规范基准；Skill（技能库）定"具体怎么做"，是Spec的落地保障。两者结合，贴合软件工程全流程，能帮助开发人员高效、规范编程，减少返工，落地高质量软件。

（注：文档部分内容可能由 AI 生成）