核心哲学
简单展示型项目，先页面；业务系统型项目，先业务、先数据、先流转，再页面。 不要让 AI 替你“脑补”系统长什么样，而是让它在既定规格里执行。
一、项目分类逻辑：在动手前选对路径
不是所有项目都走同一条路。项目应先分型，再决定流程的权重。
A 类：展示表达为主的轻项目
- 描述：核心目标是信息传达，几乎没有复杂状态和持久化。
- 推荐顺序：
背景澄清→页面结构→视觉规则→前端生成→补齐少量 Mock 数据。
B 类：业务数据为主的系统型项目
- 描述：包含 CRUD、多角色、权限、状态流转或历史记录。
- 推荐顺序：
背景澄清→需求挖掘→场景梳理→领域建模→Schema 设计→反验与流转→Spec Pack→AGENT.md→分轮代码生成。
二、Discovery：消灭需求模糊性
阶段目标
先把项目想明白，而不是急着写页面。在这个阶段，你应该像 PM 和架构师一样思考。
Step 1：背景澄清
- 目标：搞清楚“为什么做”以及“做成什么样”。
- 产出：
00-background-and-goals.md：项目背景、用户目标、成功标准。- MVP 边界：明确这期只做什么，哪些内容“本期绝对不做”。
Step 2：AI 采访式需求发现
- 做法：让 AI 作为采访者，连续追问你需求中的空白。
- 追问重点：
- 是否有多角色权限？
- 高频场景与异常场景分别是什么？
- 哪些操作需要记录历史？哪些状态必须持久化？
- 是否需要通知、搜索、筛选、导入导出？
Step 3：业务场景梳理 (Scenarios)
- 注意：这一步定义的是 业务流，不是 UI 流程。
- 要素：
动作发起者->动作对象->状态变化结果->可见性与撤销逻辑。
三、Domain：建立稳定的系统结构
阶段目标
完成从“用户语言”到“系统语言”的转变，锁定核心实体与数据流向。
Step 4：领域对象识别 (Domain Objects)
- 动作：识别系统中的主体对象 (User, Project, Task) 和附属对象，区分什么是“表”，什么是“字段”。
- 产出：
10-domain-model.md。
Step 5：Schema 设计
- 职责：定义实体名、字段类型、必填项、默认值、外键约束、唯一索引及删除策略。
- 产出：
11-schema.md。
Step 6：场景反验 (Stress Test)
- 方法：把 Step 3 的业务场景逐条代入 Schema 推演。
- 关键问题：这个状态变化有地方记吗？这个查询路径顺吗？删掉主体后历史流水会断吗？
- 原则：在 Schema 层改设计比改代码便宜 100 倍。
Step 7：数据流与状态流 (Data Flow)
- 职责：明确写入触发者、持久化位置、前端 UI 状态与后端持久态的同步关系、乐观/悲观更新策略。
- 产出：
12-data-flow.md。
四、Delivery：拆解可执行分层规格 (Spec Pack)
将上述思考过程整理为 Spec Pack。AI 处理高密度、职责单一的细密文档效果更好。
| 编号 | 文档名称 | 核心职责 | 关联依赖 |
|---|---|---|---|
| 00 | product-spec |
总控。定义目标、MVP 范围、技术栈边界。 | Discovery |
| 01 | user-flows |
交互。页面结构、跳转关系、行为路径及结果。 | Scenarios |
| 02 | data-model |
结构。核心实体、关系、字段规范、约束策略。 | Schema |
| 03 | rules-cases |
边界。报错处理、空状态、权限边界、输入校验。 | Data Flow |
| 04 | ui-guidelines |
视觉。主题、配色、圆角、间距、组件选择偏好。 | UI Spec |
| 05 | runbook |
运行。环境、Build 命令、部署说明、验收标准。 | Acceptance |
| 06 | change-log |
演进。基线变更索引，记录各版本的重大调整。 | History |
五、Implementation：Agent 编排与分轮投喂
警告：不要一次性喂全量上下文
上下文越集中，代码生成质量越高。建议分 5 个轮次推进。
Round 1: 打骨架 (Skeleton)
- 输入：
AGENT.md+00+02+05的技术部分。 - 目标：初始化项目、建立目录结构、生成 Schema 和模块边界。
Round 2: 通主流程 (Main Flow)
- 输入：
AGENT.md+00+01+02。 - 目标：实现页面、路由、CRUD 主路径，打通数据读写。
Round 3: 补边界 (Edge Cases)
- 输入：
AGENT.md+03+05。 - 目标：补全空状态、错误提示、表单校验、删除确认。
Round 4: 收敛 UI (Visual Polish)
- 输入：
AGENT.md+04+01。 - 目标：修正视觉偏差，保证组件使用的一致性。
Round 5: 验收与部署 (Delivery)
- 输入：
AGENT.md+05+06。 - 目标：自查验收标准，跑通环境，上线部署。
六、维护规范：连接规格与代码
1. 根目录 AGENT.md：AI 的“宪法”
必须在根目录保留一份英文的 AGENT.md，作为 AI 的高密度入口。
- 它定义 Source of Truth 的优先级。
- 它规定修改代码前必须先同步更新哪个规格文档。
- 它规定工程规范（如：禁止修改
spec_config.py中的正则表达式）。
2. 文件头注释：建立索引连接
每个核心页面、服务、Repository 的开头，必须包含如下注释：
TS
/**
* Baseline refs:
* - specs/delivery/01-user-flows.md
* - specs/delivery/02-data-model.md
*
* Business flow:
* - 用户从 Home 进入详情页 -> 点击编辑 -> 更新实体 -> 返回列表并刷新。
*
* Included features: [核心功能清单]
* Data source: [数据来源说明]
*/
3. 轻量化演进体系
不要扩写旧 PRD，而是采用：Baseline (基线) + Changes (变更提案) + Features (功能包) + Releases (发布增量)。
- Baseline (
00-05)：始终保持为“当前系统的有效真相”。 - Changes (
/changes)：记录具体的变更决策（RFC）。 - Features (
/features)：新功能的独立设计包。 - Log (
06)：记录上述所有变动对基线的影响。
七、标准目录结构分布图
TEXT
/AGENT.md # AI 执行总入口
/specs
/discovery # 阶段 1：背景、Q&A、场景梳理
/domain # 阶段 2：领域模型、Schema、数据流图
/delivery (Baseline) # 阶段 3：00-05 基线文档 + 06 演进索引
/changes # 阶段 4：单个需求变更提案
/features # 阶段 4：新功能设计包
/releases # 阶段 4：版本增量记录
/scripts
/validate-project.py # 基线追溯性与一致性检查脚本
结语
真正稳定的 AI 辅助开发，不是靠“更强的模型”，而是靠 更清楚的事实源。通过这套 Spec-First 手册，你可以将 AI 从“决定者”拉回到“执行者”的角色，确保代码永远服务于你的意图。