### **AI协同开发规范 (AICP) – V.final**
#### **文档目的**
本规范定义了一套基于“规范驱动开发”（Spec-driven Development）的完整工作流程，旨在最大限度地发挥AI助手（如Gemini, Claude, GitHub Copilot等）的效能，确保软件项目的可预测性、高质量和可维护性。它将开发过程分为四个明确的阶段，并为每个阶段定义了核心任务、协作模式和产出物。
—
### **核心原则**
1. **意图是最终的真相来源 (Intent is the Source of Truth)**: 项目的“意图”通过一系列结构化的“规范”文档来捕合与传递。
2. **分阶段协作 (Phased Collaboration)**: 每个开发阶段都有特定的目标，并与特定角色的AI进行交互。
3. **规范即接口 (Spec as an Interface)**: 规范文档是人与AI之间沟通的标准化接口。
4. **架构决策显式化 (Explicit Architecture Decisions)**: 所有的关键架构决策都必须记录在案，并作为AI编码的核心上下文。
5. **人是领航员，AI是执行者 (Human as Navigator, AI as Implementer)**: 人的核心职责是定义目标、设定约束、审查产出和做出决策。AI的核心职责是在明确的指导下高效地生成、分解和实现。
—
### **项目结构初始化**
在项目开始时，创建以下目录结构：
“`
/project-root
|– /plan
| |– spec.md
| |– plan.md
| |– TASKS.md
|– /changelog
|– /docs
| |– /architecture
| | |– 01-frontend.md
| | |– 02-backend-api.md
| | |– 03-database.md
| | |– 04-dependencies.md
|– claude.md <– 本地文件，在.gitignore中
… (其他项目文件)
“`
—
### **第一阶段: 规范 (Specify) – 定义“是什么”与“为什么”**
* **协作模式**: 与高级AI（如Gemini）进行**产品战略对话**。
* **核心任务**: 探讨并明确项目的核心价值、用户旅程和成功标准。
* **产出物**: 一份**高级规格说明书**，保存于 `plan/spec.md`。
—
### **第二阶段: 规划 (Plan) – 定义“如何做”**
* **协作模式**: 与AI进行**系统架构设计对话**。
* **输入**: `plan/spec.md` 和你的技术约束。
* **核心任务**: 设计系统的整体架构、技术栈、数据模型和API契约。
* **产出物**:
1. 一份**技术规划文档**，保存于 `plan/plan.md`。
2. **架构决策记录 (ADRs)**: 将讨论中确定的关键架构决策，分别记录到 `/docs/architecture/` 目录下的对应文件中。
* **`01-frontend.md`**: 记录前端框架、状态管理、组件库、构建工具等决策。
* **`02-backend-api.md`**: 记录API设计风格（RESTful/GraphQL）、认证机制（JWT/OAuth）、核心路由结构等。
* **`03-database.md`**: 记录数据库选型（SQL/NoSQL）、核心数据表/集合的设计、索引策略等。
* **`04-dependencies.md`**: 记录非代码类的关键依赖，如Redis的用途、Docker的配置、消息队列的选择等。
—
### **第三阶段: 任务 (Tasks) – 分解工作**
* **协作模式**: 指示AI进行**工作分解**。
* **输入**: `plan/spec.md` และ `plan/plan.md`。
* **核心任务**: 将技术规划分解为一系列独立的、可测试的、小颗粒度的开发任务。
* **产出物**: 一份**任务清单**，保存于 `plan/TASKS.md`。
—
### **第四阶段: 实现 (Implement) – 编码、验证、提交**
* **协作模式**: 与**CLI代码助手**进行原子化的、任务驱动的编码会话。
* **核心实践**:
1. **独立会话**: 为`plan/TASKS.md`中的**每一个任务**，开启一个**全新的、独立的**对话。
2. **提供上下文**: 在每个新会话开始时，你的初始提示词必须引导AI读取并理解以下内容：
* **A. 行为规范**: `claude.md`（见下文附录）。
* **B. 项目环境**: `package.json`, `lock`文件等。
* **C. 架构蓝图**: `claude.md`中引用的所有架构决策文件。
* **D. 当前任务**: 从`plan/TASKS.md`中复制出的、当前要完成的**那一个**具体任务的描述。
3. **开发循环**:
* AI根据任务和架构约束生成代码。
* 你进行小范围、高聚焦的代码审查。
* 你集成代码并运行测试进行验证。
* 验证通过后，立即执行**原子化提交**。
4. **收尾**: 完成一个任务后，如果该任务对某个架构决策有更新，**及时去修改 `/docs/architecture/` 中的对应文件**。然后关闭当前会话，开始下一个任务。
—
### **附录: `claude.md` – AI 行为规范模板 (最终版)**
**说明**: 此文件应存在于项目本地，并被添加到`.gitignore`。它是第四阶段（实现）中提供给CLI代码助手的“个人行为准出则”。
“`markdown
# AI 助手行为规范 (Claude Protocol)
你好。你是一名遵循最高软件工程标准的资深程序员。在本次会话中，你必须首先理解本项目的核心架构决策，然后严格遵守以下所有规则。
### 0. 核心架构上下文 (Core Architecture Context)
在开始任何工作之前，你必须首先阅读并完全理解以下架构决策文档。你生成的所有代码都必须严格遵守这些文档中定义的规范和模式。
* **前端架构**: `/docs/architecture/01-frontend.md`
* **后端API设计**: `/docs/architecture/02-backend-api.md`
* **数据库规范**: `/docs/architecture/03-database.md`
* **外部依赖与服务**: `/docs/architecture/04-dependencies.md`
### 1. 核心原则
* **遵循架构**: 你不得偏离上述架构文档中定义的任何决策。
* **单一职责**: 你生成的每个代码单元都应只解决一个明确的问题。
* **禁止猜测**: 你的工作范围严格限定于我提供的“当前任务”。如果任务描述与架构文档有冲突或不清晰，你必须提问而不是做出假设。
### 2. 环境与依赖
* **严格遵循版本**: 本项目的所有环境和依赖都已锁定。你不得提出任何与已定义版本不符的代码或建议。
* **不引入新依赖**: 未经我的明确许可，你不得引入任何新的第三方库。
### 3. 工作流程
* **任务驱动**: 你的唯一目标是完成我本次会话提供的那个独立任务。
* **先检查后编码**: 如我要求，你的第一步是提供环境检查命令，等待我确认环境就绪。
### 4. 代码质量
* **遵循规范**: 你产出的所有代码都必须遵循项目已配置的Linter和Formatter规则。
* **健壮性**: 在适当的地方添加错误处理和边界条件检查。
* **可读性**: 对复杂逻辑添加简洁的注释，并使用清晰的命名。
“`