- 项目开发规范与流程指南（完整版）
项目开发规范与流程指南（完整版）
整合 规范驱动开发（SDD） 与 Claude Code 工作流，从模糊想法到高质量交付的一站式手册。
第一部分：规范驱动开发（SDD）
1.1 为什么 AI 编程需要“规范”
在淘宝买衣服时，你说“我要一件好看的”——结果收到的和你想象的完全不同。这是沟通不精准的代价。
AI 编程也一样。你对 AI 说“帮我做个网站”，它可能输出一个完全跑偏的东西。“垃圾进，垃圾出”——模糊的需求必然导致不准确的结果。
规范（Specification） 就是你和 AI 之间的 “合同”，它明确定义：
- 要做什么（功能需求）
- 怎么做（技术方案）
- 做到什么程度（质量标准）
有了这份“合同”，AI 才能精准理解你的意图，产出符合预期的代码。
1.2 需求规范：PRD 文档
PRD（Product Requirements Document） 回答 “要做什么”。
✅ 用户故事格式
作为一个 [角色]，
我希望 [功能]，
以便 [价值/目的]。
示例：
作为一个博客读者，
我希望能按标签筛选文章，
以便快速找到我感兴趣的内容。
✅ 验收标准格式（Given-When-Then）
Given（前提条件）：系统中有20篇文章，其中5篇标记了“Python”标签
When（操作）：用户点击“Python”标签
Then（预期结果）：页面只显示这5篇标记了“Python”标签的文章
✅ 用 AI 辅助生成 PRD 的 Prompt
将模糊想法快速转化为结构化文档：
我想做一个个人书签管理工具。
请帮我生成一份完整的 PRD 文档，包含：
1. 项目概述（一句话描述）
2. 目标用户
3. 核心功能列表（按优先级：Must Have / Should Have / Nice to Have）
4. 每个功能的用户故事和验收标准
5. 非功能需求（性能、安全、兼容性）
请用 Markdown 格式输出。
1.3 技术规范：TECHNICAL 文档（原 SPEC）
TECHNICAL 文档 回答 “怎么做”。
| 模块 | 内容 | 说明 |
|---|---|---|
| 系统架构 | 整体架构设计图 | 前后端如何交互 |
| 技术选型 | 使用什么技术和框架 | 如 Next.js + Prisma + SQLite |
| 数据模型 | 数据库表结构设计 | 表、字段、关系 |
| API 接口 | 接口定义 | URL、请求参数、返回格式 |
| 目录结构 | 项目文件组织 | 代码文件夹规范 |
✅ 让 AI 从 PRD 生成 TECHNICAL 的 Prompt
基于以下 PRD 文档，请生成对应的技术规范文档（TECHNICAL.md）：
[粘贴你的 PRD 内容]
要求：
1. 推荐技术选型并说明理由
2. 设计完整的数据模型（包含字段类型和关系）
3. 列出所有 API 接口（RESTful 风格）
4. 给出建议的项目目录结构
1.4 质量规范（CHECKLIST 文档）
定义 “做到什么程度算合格”：
- 编码规范：代码风格、命名规则、注释要求
- 测试规范：单元测试、集成测试覆盖范围
- 安全规范：输入验证、认证授权、数据加密
提示：初学者不必一步到位写完美规范，从简单的 PRD 开始，项目复杂后再逐步完善。规范的核心价值是让沟通更精准。
第二部分：项目初始化（6 个习惯性动作）
在开始编码之前，按顺序完成以下 6 项设置，可避免后续 80% 的返工：
| 步骤 | 动作 | 说明 |
|---|---|---|
| Step 1 | 项目初始化 | 用需求模板向 AI 清晰描述目标（用途、设备、功能、页面、设计风格），AI 生成项目骨架。 |
| Step 2 | 建立上下文 | 运行 ./init 或手动创建 CLAUDE.md，记录项目背景、技术栈、编码规范。 |
| Step 3 | 配置权限与模式 | 编辑 .claude/settings.json，复杂项目默认 plan 模式，强制先规划后执行。 |
| Step 4 | 功能开发 | 一次一个功能，严格遵循 Explore → Plan → Implement 节奏（见第三部分）。 |
| Step 5 | 代码审查与测试 | 用 /review 命令让 AI 生成测试用例并运行，验证功能正确性。 |
| Step 6 | 提交代码 | git commit 保存进度，AI 协助生成规范 commit message。 |
第三部分：四阶段工作流（核心执行循环）
每个功能或任务都按以下四个阶段循环推进，一轮结束后回到 Explore 开始下一项。
Explore（探索） → Plan（规划） → Implement（实施） → Commit（提交）
↑ ↓
└──────────────────── 下一轮 ←─────────────────────────┘
阶段详解
| 阶段 | 你该做什么 | AI 在做什么 | 推荐模式 |
|---|---|---|---|
| ① Explore | 告诉 AI 要改动的区域（如“给订单表加软删除”） | 读相关文件、grep 搜索、追踪引用链 | Plan Mode |
| ② Plan | 让 AI 产出详细方案，你审核合理性与边界 | 生成计划、评估影响范围、列出风险点 | Plan Mode |
| ③ Implement | 切出 Plan Mode，按批准计划执行 | 按顺序修改文件、运行构建 | Normal / Auto-Accept |
| ④ Commit | 让 AI 生成 commit message，确认后提交 | 生成规范信息，可选自动发起 PR | Normal |
为什么要分阶段？
你说“加个软删除功能”，15 分钟后 AI 改了 14 个文件，动了全局查询过滤器，破坏 3 个接口——你只能手工回退。
在 Plan Mode 多花 5 分钟讨论方案，换来执行阶段节省 30 分钟返工。规划即节省。
第四部分：项目文档与日志规范
为了统一管理，所有规范文档集中存放在 specs/ 目录下，不再区分 docs 和 specs。开发日志单独存放在 logs/。
4.1 规范文档（specs/ 文件夹）
specs/ 是项目的唯一文档中心，包含以下核心文件：
| 文件 | 内容说明 |
|---|---|
PRD.md |
产品需求文档（用户故事、验收标准、功能优先级） |
TECHNICAL.md |
技术规范（架构、技术选型、数据模型、API接口） |
DESIGN.md |
UI/UX 设计规范（风格、色彩体系、交互说明） |
PROCESS.md |
开发流程与代码规范（四阶段工作流、命名规则、Git策略） |
CHECKLIST.md |
质量审查清单（测试覆盖、安全检查、上线标准） |
4.2 开发日志（logs/ 文件夹）
- 每天自动或手动记录：
- 完成事项：今日已完成的功能、修复的 Bug
- 待办事项：未完成的任务、下一步计划
- 文件名：
YYYY-MM-DD.md，按日期归档。
4.3 项目上下文文件（CLAUDE.md）
在项目根目录下创建 CLAUDE.md，作为 AI 的入口指引，明确指向 specs/ 各文件：
# 项目上下文
## 文档索引（唯一规范中心）
所有项目规范统一存放在 `specs/` 目录下：
- 产品需求 → [specs/PRD.md](specs/PRD.md)
- 技术规范 → [specs/TECHNICAL.md](specs/TECHNICAL.md)
- 设计规范 → [specs/DESIGN.md](specs/DESIGN.md)
- 开发流程 → [specs/PROCESS.md](specs/PROCESS.md)
- 质量审查 → [specs/CHECKLIST.md](specs/CHECKLIST.md)
## 工作说明
- 所有任务严格遵循 **Explore → Plan → Implement → Commit** 四阶段。
- 每日开发日志记录在 `logs/` 目录下，文件名格式 `YYYY-MM-DD.md`。
- 代码提交前必须通过 `/review` 自动化测试，并对照 `specs/CHECKLIST.md` 进行自检。
第五部分：优化后的项目目录结构（精简版）
根目录只保留 specs/（文档中心）和 logs/（日志），避免冗余。
my-project/
├── .claude/ # Claude Code 配置
│ └── settings.json # 权限与默认模式（复杂项目设为 "plan"）
│
├── specs/ # ⭐ 唯一文档中心
│ ├── PRD.md # 产品需求文档
│ ├── TECHNICAL.md # 技术规范（架构、数据模型、API）
│ ├── DESIGN.md # UI/UX 设计规范（风格、色彩）
│ ├── PROCESS.md # 开发流程与代码规范
│ └── CHECKLIST.md # 质量审查清单
│
├── logs/ # 开发日志（每日记录）
│ ├── 2026-07-18.md
│ ├── 2026-07-19.md
│ └── ...
│
├── src/ # 源代码（按项目类型调整）
│ ├── components/
│ ├── pages/
│ ├── utils/
│ └── ...
│
├── tests/ # 测试代码
│ ├── unit/
│ └── integration/
│
├── CLAUDE.md # 项目上下文说明（必填）
├── package.json # 依赖管理（或其他语言对应文件）
└── README.md # 项目简介
说明：src/ 和 tests/ 的实际结构可根据项目框架（如 React、Vue、Node.js）灵活调整，此处仅为示例。
第六部分：需求提交模板（用于 Step 1 初始化）
在项目初始化时，使用以下模板向 AI 描述需求，确保精准生成骨架：
# 项目需求提交模板
## 1. 项目概述
- **软件名称**：（如“任务管理助手”）
- **运行设备**：（如“Web 浏览器 / iOS 手机”）
## 2. 功能目标
- **核心功能**：（如“创建任务、设置截止日期、分配负责人”）
- **解决的问题**：（如“帮助团队跟踪项目进度”）
## 3. 页面与内容
- **页面列表**：（如“任务列表页、任务详情页、统计看板”）
- **关键内容**：（列表页显示标题、状态、截止日期；详情页显示完整描述等）
## 4. 设计风格与色彩
- **设计风格**：（如“极简 / 扁平 / 新拟态”）
- **主色**：（如“#2C3E50（深蓝）+ #E74C3C（珊瑚红）”）
- **辅助色**：（如“背景 #F5F7FA”）
最佳实践总结
| 原则 | 说明 |
|---|---|
| 规范先行 | 先写 PRD 和 TECHNICAL，再让 AI 生成代码。 |
| 小步快跑 | 每次只处理一个功能，完成后立即提交。 |
| 先审后动 | Plan Mode 中充分讨论，避免边写边改。 |
| 文档同步 | 代码变更同时更新 specs/ 和 logs/。 |
| 测试驱动 | 每次 /review 都生成并运行测试。 |
| 上下文延续 | 维护好 CLAUDE.md，让 AI 始终理解全局。 |
遵循以上流程，你将把 AI 从“随机生成器”转变为“可靠的协作者”，实现高效、高质量的项目交付。
本指南为项目启动和日常开发的标准参考，如有变更请及时更新 specs/ 相关文档。