AI 协作编程工作流

流水线总览

1. 澄清需求 (Brief)
2. 定接口/边界 (Contract)
3. AI 出草案 (Draft)
4. 本地跑通 (Verify)
5. 人工 diff 评审 (Review)
6. 补测试与文档 (Harden)
7. PR / 合并 (Ship)

阶段	人的输出	AI 的输出	完成标准
Brief	用户故事、非目标	需求澄清问题列表	无歧义验收句
Contract	API/表结构草案	OpenAPI/类型草稿	类型可编译
Draft	选定方案	实现代码	能本地跑
Verify	跑测命令	修报错建议	测试绿
Review	合并决策	风险点评	清单勾完

需求 Brief 模板

## 背景
...

## 要做
- [ ] ...

## 不做
- ...

## 验收
给定输入 X，输出 Y；错误时返回 Z。

让 AI 先写「契约」再写实现

TypeScript 接口

/** 用户导出任务 */
export interface ExportJob {
  id: string
  userId: string
  status: 'pending' | 'running' | 'done' | 'failed'
  createdAt: string // ISO-8601
}

export interface ExportService {
  create(userId: string): Promise<ExportJob>
  get(id: string): Promise<ExportJob | null>
}

OpenAPI 片段

paths:
  /export-jobs:
    post:
      summary: Create export job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [userId]
              properties:
                userId:
                  type: string
      responses:
        '201':
          description: Created

SQL 迁移草稿

CREATE TABLE export_jobs (
  id            UUID PRIMARY KEY,
  user_id       TEXT NOT NULL,
  status        TEXT NOT NULL CHECK (status IN ('pending','running','done','failed')),
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_export_jobs_user ON export_jobs (user_id);

本地验证命令（示例 monorepo）

# 安装
pnpm install

# 类型检查
pnpm exec tsc -p packages/api --noEmit

# 单测
pnpm test --filter api

# 只跑与本次改动相关的测试
pnpm exec vitest run src/export

# 格式与静态检查
pnpm lint && pnpm format:check

Git 分支约定

git switch -c feat/export-job
git status
git diff --stat
git add -p
git commit -m "feat(api): add export job skeleton"
git push -u origin HEAD

提交信息规范（展开）

feat: 新功能
fix: 修复
docs: 文档
refactor: 重构（无行为变化）
test: 测试
chore: 杂项/依赖

失败时的回退

情况	动作
AI 改崩一大片	git checkout -- . 或 git restore -p
半对半错	保留文件，人工挑段 cherry-pick
依赖装坏	删 lock 慎用；优先 git diff package-lock

# 查看某次 AI 提交改了什么
git show --stat HEAD
git log --oneline -10