AI 辅助编程全生命周期

主题

快速上手：从零到完整开发循环 ​

两个递进式练习，带你掌握 AI 辅助开发的核心工作流。

  • Part 1：Todo API — 30 分钟跑通基础循环
  • Part 2：知识库 API — 进阶实战（/spec、/impact、子代理、三会话审查）
  • Part 3：体系导航 — 按需深入

Part 1：Todo API（30 分钟基础循环） ​

前置条件 ​

  • Node.js 18+
  • Claude Code CLI 已安装（npm install -g @anthropic-ai/claude-code）
  • 一个空目录

1.1 创建项目 + 初始化体系（5 分钟） ​

bash
npx create-next-app@latest todo-app --typescript --tailwind --eslint --app --src-dir
cd todo-app
npx ai-dev-cli init --level 0    # Level 0：最小可用

或手动创建 CLAUDE.md：

markdown
# Todo App

## Commands
- `npm run dev` — start dev server
- `npm run test` — run tests

## Architecture
- `src/app/` — Next.js App Router pages
- `src/services/` — business logic
- `src/types/` — TypeScript type definitions
- `prisma/` — database schema

## Key Rules
- MUST use zod for input validation
- MUST write tests for service functions
- NEVER use `any` type
- NEVER use default export

安装数据库：

bash
claude "安装 Prisma + SQLite，创建 Todo model（id, title, completed, createdAt），运行 migrate"

1.2 /plan — 需求分析（3 分钟） ​

/plan 实现 Todo CRUD API：
- POST /api/todos — 创建（title 必填）
- GET /api/todos — 列表（支持 ?completed=true 过滤）
- PATCH /api/todos/:id — 更新
- DELETE /api/todos/:id — 删除

AI 输出实现方案。审阅后确认，不满意就要求调整。

1.3 契约先行开发（10 分钟） ​

按契约先行工作流实现 Todo CRUD：
1. 先定义类型 → src/types/todo.ts
2. 再写测试 → src/services/__tests__/todo.test.ts
3. 最后实现 → src/services/todo.service.ts + src/app/api/todos/route.ts

参考 Prisma schema 中的 Todo model。每完成一步跑一次测试。

关键审查点（每步完成后检查 diff）：

  • [ ] 类型定义完整？（CreateTodoInput, UpdateTodoInput, TodoOutput）
  • [ ] 测试覆盖三条路径？（正常创建 / 空 title 报错 / 不存在的 id 返回 404）
  • [ ] Service 函数有返回类型注解？
  • [ ] API Route 用 zod 校验了输入？

发现问题立即纠正，不要等全部写完。

1.4 /review → /test → /commit → /retro（10 分钟） ​

/review           # 审查代码，按 必须修复/建议改进/小建议 分级
/test             # 确认覆盖：正常 + 边界 + 错误路径
/commit           # 自动生成 Conventional Commits message
/retro            # 回答：AI 犯了什么错？哪个 prompt 好？更新 CLAUDE.md？

1.5 基础循环总结 ​

/plan → 实现 → /review → /test → /commit → /retro

这就是日常开发的核心节奏。每个新功能都重复这个循环。

Part 2：知识库 API（进阶实战） ​

前置条件：已完成 Part 1 的基础配置。

这个练习演示完整体系的进阶能力：/spec 需求挖掘、/impact 影响分析、子代理并行、三会话隔离审查。

2.1 项目概述 ​

Space（空间）—— 文档容器，类似文件夹
  └── Document（文档）—— 知识内容主体
        └── Tag（标签）—— 文档分类标记（多对多）

技术栈：Next.js App Router + Prisma + SQLite + TypeScript

2.2 /spec — 需求挖掘 ​

/spec 做一个个人知识库 API

/spec 会启动苏格拉底提问（"个人使用还是多人协作？内容格式？搜索是刚需吗？"），逐步挖掘清晰需求。

产出：docs/spec.md（背景、目标、数据模型、用户故事、API 概要）

你的动作：审阅 spec.md，确认范围和优先级。

2.3 /plan — 方案设计 ​

/plan 基于 docs/spec.md 设计实现方案

AI 输出结构化方案：

Phase 1 — Foundation：Schema + 类型定义
Phase 2 — Core：三个 Service（Space/Document/Tag）+ 测试
Phase 3 — Integration：API 路由 + 集成测试
Phase 4 — Polish：搜索 + 错误处理 + 文档

关键发现：方案设计阶段发现 Document-Tag 多对多关系需要中间表 DocumentTag。先设计后实现避免返工。

你的动作：审阅方案，确认后说"方案批准，开始 Phase 1"。

2.4 锚定文件 + 契约先行 ​

实现 Phase 1。
参考 @prisma/schema.prisma 中现有模型的风格，
添加 Space、Document、Tag、DocumentTag 四个模型。
改完跑 npx prisma validate 确认。

验证通过后：

/commit
→ feat(db): add Space, Document, Tag, DocumentTag models

2.5 /impact — 改动分析 ​

Phase 2 开始前，先做影响分析：

/impact 新增 Space Service，需要在 services/ 目录添加新文件

AI 输出影响报告：直接影响文件、间接影响、测试覆盖缺口、建议改动顺序。

这次是新增模块影响范围小，但修改共享类型时 /impact 价值会显著体现。

2.6 子代理并行 ​

三个独立 Service 可以利用子代理加速：

并行执行以下任务：
1. 实现 services/space.service.ts（参考 @src/services/ 目录中已有的 Service 模式）
2. 用 Explore Agent 研究项目中现有的测试模式，
   给我一份总结，包括测试框架、mock 方式、文件组织方式。

Explore Agent 在独立上下文中搜索，不消耗主会话上下文。返回总结后，用它作为参考写测试。

接着 Document 和 Tag Service 也可以并行：

并行执行：
1. 实现 services/document.service.ts + 测试
2. 实现 services/tag.service.ts + 测试
参考 space.service.ts 的模式，保持风格一致。

2.7 三会话隔离审查 ​

Phase 2 完成后，开新会话做代码审查（信息隔离打破确认偏差）：

（新会话）
审查 git diff main..HEAD 中的所有改动。
重点关注：
1. Prisma 查询的正确性（N+1 问题）
2. 类型安全（有没有隐式 any）
3. 错误处理（Service 层是否正确抛出 AppError）

审查发现：

  • Document Service 的 getBySpace 有潜在 N+1 查询 → 改用 include
  • Tag Service 缺少"不存在时创建"的原子操作 → 补充 connectOrCreate

回到实现会话修复 → 再跑全量测试 → /commit。

2.8 /retro — 经验沉淀 ​

/retro

回顾三个问题：

1. 哪个 prompt 好？→ "参考 @已有文件 的模式" 效果很好 → 沉淀为 CLAUDE.md 规则
2. 哪里浪费时间？→ Prisma 多对多语法第一次写错 → 应该先读文档
3. AI 犯了什么错？→ connectOrCreate 语法错误 → 加入 CLAUDE.md 常见陷阱

2.9 复盘：体系要素协同 ​

/spec   → 把"做个知识库"变成结构化需求，提前发现多对多关系
/plan   → 四阶段实现顺序，避免边写边改
锚定文件 → 所有新代码和现有代码风格一致
/impact → 改动影响分析，建立习惯
子代理   → Explore 研究测试模式 + 并行 Service，节省时间
/test   → 发现缺失的边界测试
/review → 新会话审查发现 N+1 和原子操作问题
/commit → 语义化提交，清晰变更历史
/retro  → 经验沉淀到 CLAUDE.md，下次不犯同样的错

核心认知：

  1. 验证优先 — 每个 Service 写完立刻跑测试
  2. 子代理保护上下文 — Explore 搜索不占主会话
  3. 新会话审查有用 — 没有实现者偏见，能发现更多问题
  4. 经验沉淀是闭环 — /retro 把踩过的坑写入 CLAUDE.md

Part 3：体系导航 ​

按需求找文档 ​

想做什么设计文档Prompt 食谱
理解体系全貌00-总体架构—
写好 CLAUDE.md01-CLAUDE.md 设计—
了解所有 Skills02-Skills 技能体系—
配置自动质量闸门04-Hooks 体系—
掌握高效习惯12-效率最佳实践—
接管已有项目09-脚手架设计—
需求分析—00-需求分析
架构设计—01-架构设计
代码实现—02-代码实现
测试验证—03-测试验证
代码审查—04-代码审查
调试排错—05-调试排错
重构优化—06-重构优化
文档写作—07-文档写作
运维部署—08-运维部署
进阶技巧15-Prompt 工程实战09-进阶技巧
技术调研14-技术栈选型10-技术调研

Skills 速查 ​

日常核心：  /plan → /review → /test → /commit → /retro
需求阶段：  /spec → /plan → /features
调试优化：  /debug → /impact
持续合规：  /check → /takeover → /docaudit → /health-report
脚手架：    /ui-page → /docs-site
技术调研：  /tech-research
编码规范：  code-standards（自动参考）

渐进式采用建议 ​

Level 0（5 分钟）：CLAUDE.md + settings.json → 立即可用
Level 1（+ 10 分钟）：+3 核心 Skills（/plan /review /commit）
Level 2（+ 15 分钟）：+5 Hooks（安全防火墙 + 格式化 + 行数守卫）
Level 3（按需）：+ MCP + 12 完整 Skills

三条最重要的习惯 ​

  1. 先读后写 — AI 修改任何文件前必须先读，你审查每个 diff
  2. 小步验证 — 改一个函数跑一次测试，不积累
  3. 频繁提交 — 每个可工作的状态都 commit，给自己留回滚点

面向个人开发者的 AI 辅助编程工程化方案

基于 Claude Code 构建