厦大数据库实验室博客

总结、分享、收获

实验室主页



第5章 基于规范的AI编程-代码和提示词-林子雨编著《AI编程与智能体开发》

林子雨老师
大数据学习路线图

林子雨编著《AI编程与智能体开发》（访问教材官网）

5.3 规范驱动编程工具选型

5.3.2 Spec-Kit

Constitution（工程宪章）是整个框架的顶层约束，定义团队在使用AI编程工具时必须遵守的硬性规则。例如：

# Constitution（工程宪章）

## AI使用原则

### 必须
- 所有AI生成代码必须经过代码审查才能合并
- 安全相关功能（认证、支付、数据加密）必须由人类工程师实现核心逻辑
- 规范文档必须与代码同步更新

### 禁止
- 禁止使用AI生成涉及用户隐私数据的处理逻辑
- 禁止使用AI修改数据库迁移文件
- 禁止在未创建规范文档的情况下直接让AI修改核心业务逻辑

## 代码质量标准

### AI生成代码的最低要求
- 所有函数必须包含中文docstring
- 所有公共API必须有单元测试覆盖
- 代码必须通过团队统一的lint检查

## 规范优先级
- Constitution > Specification > Plan > Tasks
- 下层规范不得与上层规范冲突

Specification（系统级规范）定义系统的功能需求和数据模型。与Constitution不同，Specification关注的是"系统做什么"，而非"团队如何工作"。例如：

# Specification（系统级规范）

## 功能范围

### 核心功能
- 用户注册与登录（邮箱 + 密码）
- 用户资料管理
- 订单创建与查询

### 排除功能（本章不涉及）
- 支付网关集成
- 物流跟踪
- 促销和优惠券

## 数据模型

核心数据模型包括用户和订单两个实体，字段定义如下：

**User实体字段定义**

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | UUID | 主键 | 用户唯一标识 |
| email | VARCHAR(255) | 唯一，非空 | 邮箱地址 |
| hashed_password | VARCHAR(255) | 非空 | bcrypt 哈希密码 |
| created_at | TIMESTAMP | 非空，默认 NOW | 注册时间 |

### Order实体

**Order实体字段定义**

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | UUID | 主键 | 订单唯一标识 |
| user_id | UUID | 外键，非空 | 下单用户 |
| total_amount | DECIMAL(10,2) | 非空 | 订单总金额 |
| status | ENUM | 默认 PENDING | 订单状态 |
| created_at | TIMESTAMP | 非空，默认 NOW | 创建时间 |

5.3.3 OpenSpec

OpenSpec的规范文档格式强调实用性和可操作性，具体格式如下：

# 规范：[功能名称]

## 1. 概述
[功能要解决什么问题，简要描述]

## 2. 功能范围
### 2.1 必须实现
- [功能点 1]
- [功能点 2]

### 2.2 不包含
- [明确排除的功能]

## 3. 数据模型
### 3.1 [实体名称]
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| ... | ... | ... | ... |

## 4. API规范
### 4.1 [端点名称]
**方法**: GET/POST/PUT/DELETE
**路径**: /api/xxx

**请求体**（如有）:
{ ... }

**响应**:
- 成功（200/201）: `{ ... }`
- 错误（4xx/5xx）: `{ "detail": "..." }`

## 5. 验收标准
- [ ] [可验证的标准 1]
- [ ] [可验证的标准 2]

## 6. 技术约束
- [约束 1]
- [约束 2]

## 7. 边界条件
- [边界情况 1]
- [边界情况 2]

5.3.5 在TRAE中安装与配置OpenSpec

使用OpenSpec之前，需要确认本地已安装Node.js 20.19.0或更高版本。读者可以在终端中执行以下命令检查版本：

node --version

如果没有安装，则可以从https://nodejs.org/zh-cn/download下载Node.js进行安装。假设读者根据Node.js的指引安装以后，无法在Git Bash中使用，则一般是环境变量的问题，可以在~/.bashrc文件中添加命令路径：

export PATH="$PATH:/c/Program Files/nodejs/"

OpenSpec以npm全局包的形式发布，执行以下命令即可完成安装：

npm install -g @fission-ai/openspec@latest

安装完成后，执行以下命令验证安装是否成功：

openspec --version

如果安装完OpenSpec以后无法使用，大概率是环境配置的问题，可以在~/.bashrc文件中添加如下命令路径（需要将路径替换为读者的真实路径），然后重新打开Git Bash：

export PATH="$PATH:/c/Users/linziyu/AppData/Roaming/npm"

进入项目根目录，执行初始化命令：

openspec init

使用空格键选择工具，按回车确认。若需要在脚本或CI（Continuous Integration：持续集成）环境中以非交互模式运行，可使用--tools参数：

# 仅为 TRAE 配置
openspec init --tools trae

config.yaml是项目配置文件，其context字段的内容会被自动注入到每一次AI 规划请求中，确保AI始终了解项目的技术背景。下面是一个典型的配置示例：

schema: spec-driven

context: |
  Tech stack: Python 3.12, FastAPI, SQLite, SQLAlchemy
  Testing: pytest
  Architecture: Three-layer (routers → services → repositories)
  We use conventional commits

rules:
  proposal:
    - Always include "## Why" and "## What Changes" sections
  specs:
    - Use Given/When/Then format for scenarios
  tasks:
    - Break tasks into max 2-hour chunks

每个变更目录下的proposal.md必须包含## Why和## What Changes两个段落，否则 openspec validate会报错，示例如下：

# Proposal: 猜数字游戏

## Why

### Background
[背景描述]

### Problem Statement
[问题陈述]

## What Changes

### New Capabilities
- 游戏核心逻辑
- 数据存储

## Capabilities

### New Capabilities
- `game-core`: 游戏核心逻辑
- `game-storage`: localStorage 存储管理

能力规范文件specs/[capability]/spec.md，必须使用“变更类型+Requirement+Scenario”格式，示例如下：

## ADDED Requirements

### Requirement: 随机数生成

系统 SHALL 在每局游戏开始时生成 1~100 之间的随机整数。

**Priority**: P0 (Critical)

**Rationale**: 随机数是猜数字游戏的核心。

#### Scenario: 游戏开始时生成目标数字

Given 玩家点击"开始游戏"
When 系统初始化新一局游戏
Then 系统生成一个 1~100 之间的随机整数作为目标数字
And 玩家不可见该数字

5.4 OpenSpec实践

5.4.1 前置准备

在开始实践之前，请确认已按照5.3.5节完成OpenSpec的安装与初始化。若尚未初始化项目，执行如下命令：

mkdir guess-number-game && cd guess-number-game
openspec init

编辑 openspec/config.yaml，填入猜数字游戏项目的技术栈信息：

schema: spec-driven

context: |
  Tech stack: HTML5, CSS3, Vanilla JavaScript
  Storage: localStorage
  No backend, pure frontend application

rules:
  proposal:
    - Always include "## Why" and "## What Changes" sections
  specs:
    - Use Given/When/Then format for scenarios

5.4.2 第二步：提案（/openspec-propose）

现在我们为一个网页应用实现"猜数字游戏"功能。在TRAE的Agent模式中，新建一个任务（即新建一个对话），输入以下指令，观察AI的输出：

/openspec-propose请为"猜数字游戏"创建规范文档。

需求描述：
实现一个猜数字游戏网页应用。系统在1~100之间随机选择一个整数作为目标数字。
玩家有7次机会猜测，每次猜测后系统给出反馈（太高、太低或正确）。
游戏结束后自动保存记录到 localStorage，支持查看历史记录和统计数据。

5.4.3 第三步：实施（/openspec-apply-change）

在 TRAE 对话框中输入实施命令，即可启动编码流程：

/openspec-apply-change guess-number-game

5.4.4 第四步：归档（/openspec-archive-change）

功能实现并通过验收后，执行/openspec-archive-change将当前变更从 openspec/changes/移动到openspec/changes/archive/，完成归档，也就是在TRAE中输入如下指令：

# 在 TRAE 中输入
/openspec-archive-change guess-number-game

归档不仅仅是"移动文件"，它标志着该功能的规范文档已进入只读状态，除非有新的变更提案，否则不再修改。归档后的文件会纳入版本管理（git），成为项目历史的一部分,手动执行下面的命令将规范纳入到仓库中，和代码一起同源管理：

git add openspec/changes/archive/2026-05-11-guess-number-game/
git commit -m "feat: archive guess-number-game change"

5.5 待办事项管理应用实践

5.5.2 实践实施步骤

在TRAE的Agent模式中，新建一个对话，输入以下指令：

请你严格按照openspec的四个步骤进行功能开发，无确认绝不主动推进、不超前写代码、不跳过任何一个步骤。

固定流程顺序，缺一不可，仅完成当前步骤，等待我确认后再进入下一环。

1. 探索阶段 /skill:openspec-explore 根据用户需求探索当前项目
2. 提案阶段 /skill:openspec-propose 根据探索阶段的讨论进行提案
3. 执行阶段 /skill:openspec-apply-change 根据提案阶段的产出实现代码
4. 归档阶段 /skill:openspec-archive-change 归档变更

1.输出首行标注当前所处步骤
2.每步结束统一话术：本步骤完成，请确认进入下一步
3.未收到确认指令，仅限完善当前内容，禁止输出后续内容与代码
4.严禁自主提速、合并步骤、提前完成开发

现在开始第1步，使用/openspec-expore 重构当前的待办事项应用，使用 SQLite 数据库存储数据，避免服务重启以后数据丢失。

5.5.3 项目验收

完成功能开发以后，有多种方式可以验证功能的正确性，可以直接告诉AI运行程序便于验证，也可以手动执行下面的命令启动程序：

uvicorn main:app –reload
© 2014 厦大数据库实验室