在今天这个 AI 辅助编码的时代，我们似乎拥有了前所未有的开发效率。AI 能够帮助我们分析仓库、编写测试甚至设计架构。然而，这一切工作流的起点，往往只是一个随意的、一次性的 Prompt。这种即兴的交互或许能点燃创意的火花，但却难以构建一个稳定、可靠、可维护的系统。

随着 AI Agent 越来越多地参与到生产环境中，我们需要的不再仅仅是灵光一现的即兴创作，而是结构化的思考、清晰的上下文以及对产出负责的机制。这，就是“规格驱动开发”（Spec-Driven Development, SDD）的核心价值所在。

本文将探讨一种类似的理念——我们称之为“以规格先行的编码方式”（Spec Coding）。它并非要复古地回到瀑布模型的繁文缛节，而是要在敏捷和 AI 盛行的当下，重新找回“设计先行”的纪律与清晰度，并将其转化为 Android 开发中的具体实践。

从 SDLC 到 Spec Coding

要理解为什么“规格先行”如此重要，我们不妨回顾一下软件开发方法的演进：

1. 软件开发生命周期 (SDLC) ：它为软件开发带来了秩序，定义了从需求、设计、实现到测试、部署和维护的清晰阶段，确保了项目的可预测性和责任划分。但其僵化的流程也拖慢了创新，限制了迭代的灵活性。

2. 产品需求文档 (PRD) ：为了连接战略与执行，团队引入了 PRD。它将业务目标翻译为技术方向。然而，PRD 很快沦为“静态产物”——在共享文档中“永垂不朽”，却在实际开发中迅速过时。它捕捉了最初的意图，却跟不上持续的演进。

3. 测试驱动开发 (TDD) 与行为驱动开发 (BDD) ：TDD 让验证变得可执行——先写测试，再写代码让测试通过。BDD 则更进一步，使用人类可读的 “Given-When-Then” 语言，让开发者和产品、测试同学围绕预期的用户行为达成共识。这两种实践都将“期望”转化为了“可验证的成果”，但它们依然默认一个前提：编码的参与者主要是人类。

4. AI 带来的范式转移：今天，AI Agents 已经可以设计、编码、测试甚至重构整个系统。我们开发的瓶颈，不再是“智力”，而是“意图” (Intention)。没有结构化的输入，AI 的输出是短暂且不一致的。我们需要一个框架来捕捉设计意图，一个能让人类和机器都能理解并遵循的蓝图。

“以规格先行” (Spec Coding) 正是为此而生。它复兴了早期工程的核心纪律——先设计，后编码——但将其适配到了这个“人机协作”的新时代。在这里，“规格” (Spec) 不再是束之高阁的文档，而是可执行、可版本化、可被机器解读的行动指南，它能像 TDD 指导开发者一样，精确地指导 AI Agents 完成任务。

Spec Coding 到底意味着什么？

简单来说，Spec Coding 重新确立了“做什么”之前先想清楚“为什么做”和“怎么做”的原则。它倡导一个清晰、可追溯的工作流：

1. 编写规格 (Write a Spec) ：用结构化的方式定义一个功能或模块的范围边界、核心意图和关键约束。
2. 生成计划 (Generate a Plan) ：基于规格，推导出具体的实现步骤。在 AI 时代，这一步可以由 AI 辅助完成。
3. 执行编码 (Execute with Agents/Engineers) ：无论是工程师还是 AI Agent，都遵循着这份计划和规格进行编码。
4. 评审与测试 (Review and Test) ：对照规格验证产出，提交代码，并进行迭代优化。

这听起来似乎增加了前期工作，但实际上，这份“规格”是杠杆，它将模糊的需求转化为清晰的、可落地的工程蓝图。

工具化落地：Spec-Kit 与 Plan Mode

理念需要工具来承载，才能在工程实践中真正发挥价值。Spec-Kit 和 Plan Mode 正是将“规格驱动”理念转化为标准化流程的关键工具。

[补充说明]
以下关于 Spec-Kit 与 Plan Mode 的介绍，非原文核心内容，是作者根据其官方文档、GitHub 仓库及相关技术文章整理而成，旨在为读者提供更全面的背景知识。所有引用的功能特性均基于公开可查的资料。

Spec-Kit：将规格转化为行动的工具包

Spec-Kit 是一个由 GitHub 开源的工具包，其核心目标是帮助开发者实践“规格驱动开发”。它并非一个全新的编程语言或框架，而是一套流程框架、脚手架和命令行工具的集合，旨在让“先写规格、再写代码”的流程变得系统化、自动化。

核心理念：

• 意图驱动 (Intent-Driven) ：首先定义要构建什么（What）和为什么构建（Why），代码实现服务于这个核心意图。
• 可执行的规格 (Executable Specifications) ：规格不再是束之高阁的文档，而是能够直接或间接驱动计划生成、任务拆分甚至代码实现的核心产物。
• 渐进式细化 (Progressive Refinement) ：开发过程是一个从“规格”到“澄清”再到“计划”和“实施”的渐进式流程，每一步都可能与 AI 或工具进行交互，不断将高层级的意图细化为具体的任务。
• 技术栈无关 (Tech-Stack Agnostic) ：Spec-Kit 的核心流程与具体的技术栈解耦，使其可以广泛应用于不同类型的项目，包括 Android、iOS、Web 前后端等。

Spec-Kit 通过一系列以 /speckit. 为前缀的命令，串联起整个开发流程，如 /speckit.constitution (建立项目宪章), /speckit.specify (编写需求规格), /speckit.plan (制定技术规划), /speckit.tasks (拆分任务), /speckit.implement (执行实现) 等。通过这样一套结构化的流程，Spec-Kit 将模糊的“想法”一步步精炼为高质量的、可维护的软件。

Plan Mode：在编码前与 AI 达成共识

在“写清楚 Spec”之后，我们还需要一种机制来确保这份规格能被准确地理解和执行。Plan Mode 正是为此而生，它是许多现代 AI 编码助手（如 GitHub Copilot、Claude Code）的一项核心功能。其核心思想非常简单：在对文件系统进行任何修改之前，AI 必须首先提出一个只读的、可供审查的计划（Plan），并获得用户的确认。

这个“计划”本质上是 AI 对接下来要执行的操作（如创建文件、修改代码、运行命令）的一个详细说明。它强制在 AI 的“思考”和“行动”之间增加了一个关键的“确认”环节。

核心价值：

• 建立契约，减少幻觉：Plan Mode 就像是开发者与 AI 之间签订的一份“施工图”。开发者可以快速审查这份计划，如果发现 AI 的理解有偏差，可以在造成实际影响前及时纠正。
• 安全探索与上下文构建：在 Plan Mode 下，AI 处于只读状态。它可以安全地浏览整个代码库，阅读相关文件，分析依赖关系，以构建完成任务所需的完整上下文。
• 模拟资深工程师的工作流：Plan Mode 的“规划-执行”两阶段流程，实际上是在模拟一位资深工程师的工作方式：先全面理解问题、思考解决方案、规划步骤，然后再动手编码。

协作关系：Spec-Kit 与 Plan Mode

Spec-Kit 与 Plan Mode 并非竞争关系，而是一对理想的合作伙伴，共同构成了一条完整的规格驱动开发流水线：

• Spec-Kit 负责“产出”：它作为上游，专注于将模糊的业务需求，通过结构化的方式转化为清晰、版本化的规格文档（spec.md）、技术方案（plan.md）和任务清单（tasks.md）。这些产物是整个开发过程的“唯一事实源”。
• Plan Mode 负责“消费”：它作为下游，消费 Spec-Kit 产出的规格和代码库的现有上下文，生成一份精细的、可供审查的实施计划。待计划确认后，再驱动 AI Agent 精准地执行编码任务。

对于大型、复杂的 Android 项目而言，直接让 AI 修改代码风险很高。通过 Spec-Kit 明确意图，再结合 Plan Mode 的安全规划，可以确保 AI 的每一步行动都在人类的监督和掌控之下，使其成为一个可靠的“手术刀”，而非失控的“推土机”。

Android 项目中的阶段式实践

现在，我们将 Spec-Kit 的工作流范式与一个典型的 Android 功能开发过程相结合，展示如何在每个阶段应用其核心思想。假设我们要开发一个“展示用户动态列表”的功能。

---

阶段 0：定义项目宪章 (/speckit.constitution)

在功能开发开始前，整个项目应该已经有了一份“宪章”，它规定了团队的技术选型和开发准则。

Android 要点:

• 语言与架构: 明确项目统一使用 Kotlin，遵循 MVVM 或 MVI 架构模式。
• 核心组件库: 规定网络请求使用 Retrofit + OkHttp，数据库使用 Room，异步处理使用 Kotlin Coroutines，UI 框架为 Jetpack Compose。
• 代码质量: 强制要求代码格式化遵循 ktlint 规则，新功能的单元测试覆盖率不低于 70%。
• API 设计: 所有 API 响应体必须包裹在一个标准的 ApiResponse<T> 结构中，包含 code, message, data 字段。

示例片段 (constitution.md):

# Article I: Architecture & Language
- All new features MUST be implemented using the Model-View-ViewModel (MVVM) pattern.
- The primary programming language is Kotlin.

# Article II: Core Libraries
- **Networking**: Retrofit for API declaration, OkHttp for transport, Moshi for JSON serialization.
- **Database**: Room for local persistence.
- **Asynchronicity**: Kotlin Coroutines for all background tasks and data streams.
- **UI**: Jetpack Compose for all new UI development.

# Article III: Quality & Testing
- All code MUST pass `ktlint` checks before merging.
- Unit test coverage for new business logic in ViewModels and Repositories MUST exceed 70%.

---

阶段 1：规格化需求 (/speckit.specify)

产品经理或开发者提出高层级需求，AI 协助生成结构化的 spec.md。

需求: “为我们的 App 创建一个动态（Feed）列表页面。用户应该能看到一个可滚动的动态卡片列表，每张卡片包含发布者头像、昵称、发布内容和一张图片。需要支持下拉刷新和上拉加载更多。”

Android 要点:

• 用户故事: 清晰描述用户看到什么、可以做什么。
• 验收标准: 明确定义“完成”的标准，例如“列表成功显示至少10条动态”、“下拉刷新后列表内容更新”、“滚动到底部时自动加载下一页”。
• 非功能需求: 定义性能指标（如，列表首次加载时间 < 1.5s）、离线行为（如，无网络时应显示缓存或错误提示）。

示例片段 (spec.md):

# Feature: User Feed List

## 1. User Stories
- **As a user**, I want to see a list of recent feeds, so that I can stay updated.
- **As a user**, I want to be able to refresh the list, so that I can see the very latest content.
- **As a user**, I want the list to load more items as I scroll down, so that I can browse content seamlessly.

## 2. Acceptance Criteria
- [ ] The screen successfully displays a list of feed cards.
- [ ] Each card shows an avatar, username, content text, and a single image.
- [ ] Pulling down from the top of the list triggers a refresh.
- [ ] Scrolling to the bottom of the list loads and displays the next page of feeds.
- [ ] When offline, a cached version of the list is shown, if available.

## 3. Non-Functional Requirements
- **Performance**: P95 of initial list rendering time should be under 1.5 seconds.
- **[NEEDS CLARIFICATION]**: What should be displayed if the cache is empty and the network is unavailable?

注意 [NEEDS CLARIFICATION] 标记，这是 AI 发现的模糊点，引出下一阶段。

---

阶段 2：澄清需求 (/speckit.clarify)

团队（在 AI 辅助下）解决上一阶段的模糊点。

澄清问题: 如果缓存为空且无网络，应该显示什么？
团队决策: 显示一个标准的“网络错误”通用空页面组件。

AI 会将此决策更新回 spec.md。

---

阶段 3：技术规划 (/speckit.plan)

将 spec.md 转化为具体的 Android 技术方案。

Android 要点:

• 组件划分:
  • FeedScreen.kt: Jetpack Compose 可组合函数，负责 UI 展示。
  • FeedViewModel.kt: 负责业务逻辑、状态管理，并从 Repository 获取数据。
  • FeedRepository.kt: 数据层，负责从网络或本地数据库获取数据。
  • FeedApiService.kt: 使用 Retrofit 定义网络接口。
  • FeedDao.kt & FeedEntity.kt: 使用 Room 定义数据访问对象和数据库实体。
• 数据模型: 定义 FeedItem 数据类。
• API 协约: 定义 /feeds 接口的请求参数（如 page, limit）和响应结构。

示例片段 (plan.md):

# Technical Plan: User Feed List

## 1. Architecture
- Follows the project's standard MVVM pattern.

## 2. Component Breakdown
- **UI Layer**: `FeedScreen.kt` (Composable) will observe `StateFlow<FeedUiState>` from the ViewModel.
- **ViewModel Layer**: `FeedViewModel.kt` will expose UI state and handle user events (refresh, load more).
- **Data Layer**: `FeedRepository.kt` will orchestrate data fetching from network and local cache.

## 3. API Contract (`contracts/feed_api.json`)
- **Endpoint**: `GET /v1/feeds`
- **Query Params**: `page: Int`, `limit: Int`
- **Success Response (200)**: `{"code": 0, "data": {"items": [FeedItem], "hasMore": Boolean}}`

## 4. Data Model (`data-model.md`)
- **`FeedItem.kt` (Data Class)**: `id: String`, `author: Author`, `content: String`, `imageUrl: String`
- **`FeedEntity.kt` (Room Entity)**: Mirrored structure for caching.

---

阶段 4：任务拆分 (/speckit.tasks)

将技术计划分解为可执行的编码任务。

Android 要点:

• 任务粒度要小，依赖关系清晰。
• 标注可并行任务，如“实现 API 接口”和“设计 UI 界面”可以同时进行。

示例片段 (tasks.md):

# Task List: User Feed List

- **Group 1 (Data & Network - Can be parallel)**
  - [ ] **Task 1.1**: Define `FeedItem` data class and `FeedEntity` for Room.
  - [P] **Task 1.2**: Implement `FeedApiService.kt` with Retrofit for the `/v1/feeds` endpoint.
  - [P] **Task 1.3**: Implement `FeedDao.kt` for Room database access.

- **Group 2 (Repository - Depends on Group 1)**
  - [ ] **Task 2.1**: Implement `FeedRepository.kt`, including caching logic (fetch from network, save to Room).

- **Group 3 (ViewModel & UI - Depends on Group 2)**
  - [ ] **Task 3.1**: Implement `FeedViewModel.kt` to fetch data and manage `FeedUiState` (Loading, Success, Error).
  - [ ] **Task 3.2**: Create the `FeedCard.kt` Composable for a single feed item.
  - [ ] **Task 3.3**: Implement `FeedScreen.kt` to display the list, handle pull-to-refresh and pagination.

---

阶段 5：实施与测试 (/speckit.implement)

开发者或 AI 开始根据任务列表编写代码，并严格遵循 TDD（测试驱动开发）。

Android 要点:

• 先写测试: 对 FeedViewModel，先编写单元测试来验证其状态转换逻辑。

  // FeedViewModelTest.kt
  @Test
  fun `when repository returns success, state becomes Success`() = runTest {
      // Given
      val fakeRepository = FakeFeedRepository()
      fakeRepository.setNextResponse(Result.success(fakeFeedList))
      val viewModel = FeedViewModel(fakeRepository)
  
      // When
      viewModel.loadFeeds()
  
      // Then
      assert(viewModel.uiState.value is FeedUiState.Success)
  }
  

• 后写实现: 然后再去实现 FeedViewModel 的 loadFeeds 方法，使其能通过测试。

  // FeedViewModel.kt
  fun loadFeeds() {
      viewModelScope.launch {
          _uiState.value = FeedUiState.Loading
          val result = repository.getFeeds(page = 1)
          _uiState.value = result.fold(
              onSuccess = { FeedUiState.Success(it) },
              onFailure = { FeedUiState.Error(it.message) }
          )
      }
  }
  

---

阶段 6 & 7：分析一致性与演进

• 分析 (/speckit.analyze): 持续检查代码实现是否满足 spec.md 中的所有“验收标准”。例如，自动化测试可以验证所有定义的业务场景。
• 演进: 当新的需求（如“支持点赞功能”）出现时，流程不是直接修改代码，而是回到阶段 1，创建一个新的 spec 或在原有基础上进行演进，再次经历完整的“规格 → 计划 → 任务 → 实现”循环。这保证了项目的长期可维护性。

---

适用场景与陷阱

引入“规格先行”的理念，并不是要回到僵化的瀑布流，而是要在敏捷开发中增加一个“校准”步骤。在实践中需要权衡其利弊。

适用场景

• 复杂功能模块：涉及多个组件、复杂状态管理或前后端深度协作的功能。
• 核心基础库：如网络库、数据库模块、UI 组件库，这些被广泛依赖的部分值得投入更多设计。
• 团队协作：当多个开发者或多个团队（前端、后端、测试）需要围绕同一个功能协作时，一份清晰的 Spec 是最好的沟通语言。
• AI 辅助开发：当你希望 AI Agent 能够更精确地完成任务时，一份结构化的 Spec 是最高效的 Prompt。

潜在陷阱与应对

• 前期投入增加：编写 Spec 需要时间，对于一些简单、紧急的需求，可能会显得“太重”。
  • 应对: 灵活调整流程的粒度。对于小型任务，可以将多个阶段合并，或者简化 spec 文档。
• 过度设计的风险：沉迷于设计完美的 Spec，而忽略了实际需求和快速交付的压力。Spec 应该是“刚刚好”的，而不是“面面俱到”的。
  • 应对: 严格遵循“YAGNI (You Aren’t Gonna Need It)”原则，只设计当前 spec 中明确要求的内容。
• 文档与代码的同步：这是最大的挑战。当开发压力大时，团队可能会绕过流程直接修改代码，导致 spec 与实现脱节。
  • 应对: 将流程工具（如 Spec-Kit 的命令）与 CI/CD 流程深度集成。例如，要求合并请求必须关联到一个已完成的 spec，并通过自动化检查（/speckit.analyze）确保一致性。同时，将 Spec 视为“活的文档”，与代码一同存放在版本控制系统中，在代码迭代时保持同步更新。
• 团队协作与版本化: 规格和计划本身也需要像代码一样被版本化管理。
  • 应对: 将所有产出物（.md, .json 文件）都存放在 Git 仓库中，并使用功能分支来管理 spec 的变更，确保所有讨论和修改都有迹可循。

结论：Spec 是新的沟通界面

“以规格先行”的编码方式标志着一种安静而深刻的转变。它提醒我们，清晰度本身就是一种杠杆。无论是人类开发者还是 AI Agent，当我们给予它们结构化的意图、明确的约束和清晰的目标时，它们的产出效率和质量都会得到极大的提升。

在 Android 开发中，这意味着在埋头于 Activity、Fragment 或 Composable 之前，我们先花一点时间，将脑中的设计显性化、结构化。这份 Spec 不仅是你自己的思考沉淀，更是与团队、与未来的自己、乃至与 AI 沟通的界面。

通过拥抱这种“设计先行”的原则，我们不仅能构建出更健壮、更易于维护的 App，还能确保我们所构建的，真正符合我们所设想的。