AI 规格驱动编程入门：Spec 如何成为人和 Agent 的共同契约

// ❌ 没有 Spec 约束时，Agent 容易在 UI 层就地处理
// 问题：错误映射和业务组件混在一起，换个页面要重写一遍
async function SearchHeader() {
  const [results, setResults] = useState([])
  const [error, setError] = useState<string | null>(null)
 
  const handleSearch = async (query: string) => {
    try {
      // 直接在组件里调用 API、处理错误、映射状态
      const res = await fetch(`/api/search?q=${query}`)
      if (!res.ok) {
        setError('搜索失败，请重试') // 硬编码文案，无法复用
        return
      }
      const data = await res.json()
      setResults(data.results)
    } catch (e) {
      setError('网络异常') // 所有错误一视同仁，无法区分
    }
  }
}

// ✅ 有 Spec 约束后，按 Spec 的层级划分处理
 
// api/search.ts — API 层统一映射错误对象
// Spec 约束：「API 层负责错误映射，UI 层只消费稳定状态」
export type SearchState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; results: SearchResult[] }
  | { status: 'error'; message: string }
 
export async function search(query: string): Promise<SearchState> {
  try {
    const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`)
    if (!res.ok) return { status: 'error', message: '搜索暂时不可用' }
    const data = await res.json()
    return { status: 'success', results: data.results }
  } catch {
    return { status: 'error', message: '网络连接失败' }
  }
}

// ui/SearchHeader.tsx — UI 层只消费状态，不做错误判断
// 注释说明差异：组件不再处理 API 细节，只根据 SearchState 渲染对应 UI
export function SearchHeader() {
  const [state, setState] = useState<SearchState>({ status: 'idle' })
 
  const handleSearch = async (query: string) => {
    setState({ status: 'loading' })
    setState(await search(query))
  }
 
  if (state.status === 'loading') return <SearchSkeleton />
  if (state.status === 'error') return <InlineError message={state.message} />
  if (state.status === 'success' && state.results.length === 0) {
    return <EmptyHint />
  }
  if (state.status === 'success') return <SearchResults items={state.results} />
  return <SearchInput onSearch={handleSearch} />
}

// ❌ 没有 Spec 约束时，Agent 在每个文件里各自判断
// 问题：同一个权限逻辑出现三次，角色模型变更时容易漏改
 
// components/DeleteButton.tsx
function DeleteButton({ user }: { user: User }) {
  if (user.role !== 'admin') return null // UI 层自己判断角色
  return <Button onClick={handleDelete}>删除</Button>
}
 
// api/posts/[id].ts
export async function DELETE(req: Request) {
  if (req.user.role !== 'admin') { // API 层再判断一次
    return new Response('Forbidden', { status: 403 })
  }
  // ...
}
 
// lib/getPosts.ts
export async function getPosts(user: User) {
  if (user.role !== 'admin') throw new Error('No permission') // 数据层又判断一次
  return db.posts.findMany()
}

// ✅ 有 Spec 约束后，权限归属清晰
 
// lib/permissions.ts — 权限判断集中在一处
// Spec 约束：「权限校验在 API 层，UI 层只读权限状态」
// 注释说明差异：所有角色判断逻辑集中管理，角色模型变更时只改这一处
export function canDelete(user: User, resource: Resource): boolean {
  return user.role === 'admin' || resource.ownerId === user.id
}
 
export function canEdit(user: User, resource: Resource): boolean {
  return user.role === 'admin' || resource.ownerId === user.id
}
 
// api/posts/[id].ts — API 层调用统一的权限函数
import { canDelete } from '@/lib/permissions'
 
export async function DELETE(req: Request, { params }: { params: { id: string } }) {
  const resource = await db.posts.findUnique({ where: { id: params.id } })
  if (!resource || !canDelete(req.user, resource)) {
    return new Response('Forbidden', { status: 403 })
  }
  await db.posts.delete({ where: { id: params.id } })
  return new Response(null, { status: 204 })
}
 
// components/DeleteButton.tsx — UI 层只消费权限结果
// 不再自己判断角色，而是从 API 获取 canDelete 状态
function DeleteButton({ canDelete }: { canDelete: boolean }) {
  if (!canDelete) return null
  return <Button onClick={handleDelete}>删除</Button>
}

// ❌ 没有 Spec 约束时，Agent 直接替换字段
// 问题：旧数据没有 status 字段，读取时全部 undefined，线上崩溃
 
// types/post.ts
interface Post {
  id: string
  title: string
  // isPublished 被直接删除
  status: 'draft' | 'published' | 'archived'
}
 
// lib/getPosts.ts
export async function getPosts(): Promise<Post[]> {
  return db.posts.findMany()
  // 旧记录：{ id: "1", title: "Hello", isPublished: true }
  // 读取 post.status → undefined，下游代码全部异常
}

// ✅ 有 Spec 约束后，增加兼容层
// Spec 约束：「字段变更必须向后兼容，新旧字段共存过渡」
// 注释说明差异：新增字段而非替换，旧数据通过兼容映射保持稳定
 
// types/post.ts
interface Post {
  id: string
  title: string
  isPublished: boolean // 保留旧字段，标记为 @deprecated
  status: 'draft' | 'published' | 'archived' // 新增字段
}
 
// lib/post-compat.ts — 兼容层处理旧数据
// Spec 约束：「迁移期间，读取时自动映射旧字段到新字段」
export function normalizePost(raw: DbRecord): Post {
  // 旧数据没有 status 字段时，从 isPublished 推导
  const status = raw.status ?? (raw.isPublished ? 'published' : 'draft')
  return { ...raw, status }
}
 
// lib/getPosts.ts
export async function getPosts(): Promise<Post[]> {
  const records = await db.posts.findMany()
  return records.map(normalizePost)
}
 
// migrations/add-post-status.sql
// Spec 约束：「数据库变更必须有对应迁移脚本」
ALTER TABLE posts ADD COLUMN status VARCHAR(20) DEFAULT 'draft';
UPDATE posts SET status = 'published' WHERE is_published = true;
UPDATE posts SET status = 'draft' WHERE is_published = false;

// ❌ 没有 Spec —— Agent 在 UI 层就地处理
// 错误映射和业务组件混在一起，无法复用
const res = await fetch('/api/search')
if (!res.ok) setError('搜索失败') // 硬编码、不可复用

// ✅ 有 Spec —— 按层级划分职责
// 注释说明差异：API 层统一映射，UI 层只消费状态对象
const state = await search(query) // 返回 SearchState 联合类型
if (state.status === 'error') return <InlineError message={state.message} />

// ❌ 没有 Spec —— 每个文件各自判断
// 注释说明差异：角色判断散落 5 个文件，改角色模型时容易漏改
if (user.role === 'admin') { /* ... */ }

// ✅ 有 Spec —— 权限函数集中管理
// 注释说明差异：一个文件定义权限规则，全项目消费同一个函数
if (canDelete(user, resource)) { /* ... */ }

// ❌ 没有 Spec —— 直接替换字段
// 注释说明差异：旧数据没有新字段，读取时 undefined 导致线上异常
post.status // 旧记录：undefined

// ✅ 有 Spec —— 兼容层 + 迁移脚本
// 注释说明差异：新增字段 + 旧字段映射，线上零影响
normalizePost(raw).status // 旧记录也能正确推导

<!-- ❌ 低质量 Spec —— 只有目标，没有边界和验收 -->
# 加搜索功能
给首页加一个搜索框，要快。
<!-- 问题：没有 Non-goals、没有错误处理、没有验收标准 -->
<!-- Agent 会把「要快」理解为加 loading 动画，而非优化查询 -->

<!-- ✅ 高质量 Spec —— 目标、边界、验收齐全 -->
# Change: add-home-search
 
## Problem
首页缺少搜索入口，用户需要跳转后才能搜索。
 
## Goals
- Header 增加搜索框，输入后实时查询
- 搜索失败时展示行内错误提示
 
## Non-goals
- 不做搜索建议/自动补全
- 不修改后端搜索排序逻辑
 
## Design
- API 层统一映射错误对象（SearchState 联合类型）
- UI 层只消费状态，不做 API 细节处理
 
## Acceptance
- `pnpm typecheck` 通过
- 模拟 API 500 时页面展示错误提示，不白屏
- 搜索成功时结果正常渲染