Spec-Kit: iFlow 环境使用教程与最佳实践

本文档提供 spec-kit 在 iFlow 平台中的使用教程和最佳实践，帮助团队通过规范驱动的开发模式，提升与 AI 编码助手的协作效率和软件质量。

简介

spec-kit 是一个旨在将“规范”融入开发流程核心的框架。在我们的项目中，它通过 iFlow 平台（platform.iflow.cn）集成，使用 /speckit 命令来调用。

该工具引导开发者和 AI（如 Gemini）遵循从需求到编码的系统化路径，有效减少因需求不明确导致的开发浪费。其核心理念是 “意图先行 (Intent-first)”：先明确“做什么”和“为什么做”，再关心“如何实现”。

核心阶段

/speckit 命令会引导你走过一个分阶段的流程，每个阶段都有对应的目标和产出物：

1. Constitution (立项): 定义项目的设计原则、技术栈、规范等，是整个项目的“宪法”。
2. Specify (规范): 阐述功能需求、用户故事和验收标准。
3. Clarify (澄清): 通过问答形式，消除需求中的模糊地带。
4. Plan (计划): 制定技术实现方案，包括模块设计、数据结构和接口定义。
5. Tasks (任务): 将计划分解为可执行的编码任务列表。
6. Analyze (分析): 检查各阶段文档的一致性和覆盖率。
7. Implement (实现): 根据任务列表，驱动 AI 进行编码和测试。

iFlow 中的 Spec-Kit 工作流

在 iFlow 聊天窗口中，通过调用 /speckit 命令来启动和推进开发流程。iFlow 会引导你完成 spec-kit 的每一个核心阶段。

启动流程

在 iFlow 中输入以下命令开始一个新的功能规范：

/speckit

iFlow 会启动一个交互式会话，引导你创建或选择一个功能规范，然后逐步完成以下阶段。

1. Constitution (立项) 阶段

这是流程的第一步，通常在项目首次使用 /speckit 时设定。iFlow 会引导你定义项目的核心原则，并将其保存在 .specify/memory/constitution.md。

• 目标: 设定技术选型、代码风格、测试策略、通用设计模式等。
• 作用: 为 AI 提供一个全局上下文，确保所有产出都符合项目标准。

产出示例 (constitution.md):

- **编程语言**: Go 1.25+
- **API 风格**: RESTful + gRPC
- **数据库**: PostgreSQL
- **代码规范**: 遵循 `golangci-lint` 的规则。
- **测试要求**: 所有核心业务逻辑必须有单元测试，覆盖率 > 80%。

2. Specify (规范) 阶段

iFlow 会要求你提供功能的详细描述，并生成规范文件。

• 路径: specs/<feature-name>/spec.md
• 内容: 描述功能的背景、目标用户、需求点和验收标准 (AC)。

产出示例 (spec.md):

**功能**: 用户注册
**背景**: 新用户需要能够通过邮箱和密码创建账户。
**需求**:
- 用户提供有效的邮箱和密码。
- 系统验证邮箱唯一性。
- 密码必须满足特定强度要求。
**验收标准**:
- [ ] 成功注册后，用户自动登录。
- [ ] 使用已存在的邮箱注册，返回错误提示。

3. Plan (计划) 和 Tasks (任务) 阶段

在生成规范后，iFlow 会引导你进行技术规划，并将规划内容补充到 spec.md 文件中。

• Plan: 设计实现该功能所需的技术方案。
• Tasks: 将技术方案拆解为具体的、可执行的步骤。

产出示例 (追加到 spec.md):

---
**模块**: `auth_service`
**接口**:
- `POST /api/v1/register`
**数据模型**:
- `users` 表需要增加 `email` 和 `password_hash` 字段。

---
1.  **数据库**: 更新 `users` 表结构，添加新字段。
2.  **后端**:
    - 创建 `RegisterRequest` 数据结构。
    - 实现 `AuthService.Register` 方法。
    - 添加密码哈希逻辑。
3.  **测试**: 编写 `Register` 方法的单元测试。

4. Implement (实现) 阶段

这是最终的执行阶段。你可以指示 iFlow 或 AI 助手，根据生成的任务列表逐一完成编码。

指令示例:

"根据 specs/001-user-registration/spec.md 中的任务列表，完成第 1 项任务：更新数据库表结构。"

最佳实践

• 原子化规范: 每个由 /speckit 创建的 spec.md 只关注一个独立的功能点，便于管理和追踪。
• 持续澄清: 在开发过程中，不断通过与 iFlow 的交互来记录新的问题和决策，保持信息同步。
• 版本化规范: 将 specs 目录纳入 Git 管理，实现需求和代码的版本对应。
• 善用分析: 定期让 iFlow 运行分析，检查规范与计划之间是否存在冲突或遗漏。
• 小步快跑: 引导 AI 每次只完成一个或少数几个任务，然后立即测试和审查，便于快速纠错。

目录结构

/speckit 命令会在你的项目中创建和维护以下结构：

.
├── .specify/             # spec-kit 的核心工作目录
│   ├── memory/           # 存储长期记忆，如 constitution
│   │   └── constitution.md
│   └── templates/        # 命令模板
└── specs/                # 存放所有功能规范
    ├── 001-feature-a/
    │   └── spec.md
    └── 002-feature-b/
        └── spec.md

通过在 iFlow 中遵循 /speckit 流程，你可以将 AI 无缝集成到规范化的开发生命周期中，从而构建出更健壮、更易于维护的软件系统。