Vibe Coding 知识库

规格驱动开发 ​

规格驱动开发的核心是：先把需求、边界、验收标准和风险写清楚，再让 AI 或开发者进入实现。它不是为了增加文档负担，而是为了减少返工、误解和不可审查的自动生成代码。

标准流程 ​

为什么适合 AI 编程 ​

AI 编程工具依赖上下文。需求越模糊，AI 越容易：

  • 自行扩大范围。
  • 引入不必要依赖。
  • 忽略权限、安全、异常状态。
  • 生成看似完整但无法验收的代码。

规格文档把“我想要什么”拆成“系统必须满足什么”。这会让 Claude Code 和 Codex 都更容易产出可验证结果。

推荐文档集合 ​

text
docs/project/
  requirements.md
  acceptance.md
  architecture.md
  api-contract.md
  data-model.md
  test-strategy.md
  risk-register.md
  release-checklist.md

小项目可以只保留前三个：

  • requirements.md
  • acceptance.md
  • test-strategy.md

requirements.md 模板 ​

markdown
# Requirements

## Background

The team needs an AI project delivery dashboard to track tasks, blockers, owners, and delivery status.

## Users

- Project manager: reviews project health and blockers.
- Developer: updates task progress and AI assistance notes.
- QA engineer: checks acceptance and testing status.

## Goals

- Create, edit, and delete delivery tasks.
- Track status, owner, priority, due date, and blocker reason.
- Show summary cards for total, in progress, blocked, and done.
- Persist demo data locally.

## Non-goals

- No database in v1.
- No authentication in v1.
- No multi-tenant permissions in v1.
- No external AI API integration in v1.

## Constraints

- Use React, TypeScript, and Vite.
- Store data in localStorage.
- Must run with documented npm commands.

acceptance.md 模板 ​

markdown
# Acceptance Criteria

## Task Management

- Given I am on the dashboard, when I create a task, then it appears in the task list.
- Given a task exists, when I change its status, then summary counts update immediately.
- Given a task is blocked, when I add a blocker reason, then the reason is visible in the list.

## Dashboard

- Show total task count.
- Show in-progress count.
- Show blocked count.
- Show completed count.
- Empty state is visible when there are no tasks.

## Persistence

- Data remains after page refresh.
- Reset action restores the initial demo dataset.

## Quality

- Build command passes.
- Unit tests cover task reducer or task utility functions.
- UI has no obvious overflow on desktop and mobile widths.

architecture.md 模板 ​

markdown
# Architecture

## Overview

The app is a single-page React application. It stores task data in localStorage for the training demo.

## Modules

- `src/features/tasks`: task state, task list, task form, filters.
- `src/features/dashboard`: summary cards and delivery health view.
- `src/lib/storage`: localStorage read/write helpers.
- `src/types`: shared TypeScript types.

## Data Model

Task:

- id: string
- title: string
- owner: string
- status: todo | in_progress | blocked | done
- priority: low | medium | high
- dueDate: string
- aiNotes: string
- blockerReason?: string

## Boundaries

- UI components should not directly call localStorage.
- Storage helpers should not know about rendering.
- Filters should be pure functions and unit tested.

plan.md 模板 ​

markdown
# Implementation Plan

## Step 1: Project skeleton

- Verify scripts.
- Create base layout.
- Add task type definitions.

## Step 2: Task state

- Add seed data.
- Add create/update/delete functions.
- Persist to localStorage.

## Step 3: Dashboard

- Add summary counts.
- Add blocked task view.

## Step 4: Tests

- Test task summary calculation.
- Test filter logic.

## Step 5: Verification

- Run tests.
- Run build.
- Browser smoke test.

IDE 联动方式 ​

  1. 在 IDE 左侧打开 docs/project/requirements.md。
  2. 在右侧打开 src/。
  3. 终端运行 Claude Code 或 Codex。
  4. 第一轮只让 AI 阅读文档并输出计划。
  5. 第二轮只允许实现一个小步骤。
  6. 每一步结束后运行测试或构建。
  7. 把稳定经验写回 AGENTS.md 或 CLAUDE.md。

常见错误 ​

错误后果修正
只写一句需求AI 自行脑补拆成背景、用户、目标、非目标
没有验收标准无法判断完成用 Given/When/Then 写行为
没有非目标范围失控明确 v1 不做什么
没有验证命令难以交付写清 build、test、lint
文档不更新后续上下文失效每次复盘后更新稳定规则

课堂练习 ​

让学员用同一个示例项目分别驱动 Claude Code 和 Codex：

  • Claude Code：先读 CLAUDE.md 和规格文档，生成交互式计划。
  • Codex：先读 AGENTS.md 和规格文档，输出文件范围、风险和验证命令。

比较两者输出时重点看：是否遵守非目标、是否给出验证、是否控制 diff 范围。