乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > AI Assistant 编码协作作业指导书

AI Assistant 编码协作作业指导书

当前时间： 2026-04-19 00:52:04 更新时间： 2026-04-19 分类：软件教程 评论(0)

AI Assistant 编码协作作业指导书

AI Assistant 编码协作作业指导书

版本: v1.0适用场景: IDE + AI Assistant（Claude / Cursor / CodyBuddy / Gemini / Codex / Copilot 等）协同开发核心目标: 建立一套”AI 可读、人可控、跨工具无缝切换”的开发协作规范

一、核心理念

  1. 文档驱动开发（DDD）：所有开发动作以文档为依据，AI 每次介入前必须读文档。
  2. 进度可追溯：每一次功能开发、修复、变更都落入进度表。
  3. AI 无状态假设：默认 AI 没有记忆，每次 session 通过”读文档 + 读进度”恢复上下文。
  4. 工具无关：无论更换哪个 AI 工具，只要遵循本作业书即可无缝衔接。

二、项目目录结构规范

项目根目录下必须建立 /docs 文件夹，结构如下：

project-root/├── docs/│   ├── 00_AI_WORKBOOK.md          # 本作业指导书（AI 必读入口）│   ├── 01_PRODUCT_SPEC.md         # 产品说明书│   ├── 02_REQUIREMENTS.md         # 产品需求文档（PRD）│   ├── 03_TECH_DESIGN.md          # 技术方案 / 架构设计│   ├── 04_API_SPEC.md             # 接口文档│   ├── 05_DATA_MODEL.md           # 数据模型 / 数据库设计│   ├── 06_PROGRESS.md             # 开发进度表 ⭐核心│   ├── 07_CHANGELOG.md            # 变更日志 / 功能修复记录│   ├── 08_TECH_NOTES.md           # 关键技术决策与问题解决记录│   ├── 09_DEPLOY_GUIDE.md         # 部署与上线指南│   └── 10_GIT_WORKFLOW.md         # Git 分支与版本管理规范├── src/├── README.md└── .ai-context                    # AI 快速上下文入口（可选，软链接或简介）

三、AI 每次 Session 启动流程（强制）

每次开启新对话或切换 AI 工具时，第一条指令必须是以下模板：

【项目启动指令】你现在作为本项目的 AI 编码助手。请严格按以下顺序执行：1. 阅读 docs/00_AI_WORKBOOK.md（本作业书），了解协作规范。2. 阅读 docs/01_PRODUCT_SPEC.md 和 docs/02_REQUIREMENTS.md，掌握产品定位与需求。3. 阅读 docs/03_TECH_DESIGN.md 和 docs/05_DATA_MODEL.md，了解技术架构。4. 阅读 docs/06_PROGRESS.md，确认当前开发进度、已完成项、待办项、阻塞项。5. 阅读 docs/07_CHANGELOG.md 最近 5 条，了解近期变更。6. 阅读 docs/08_TECH_NOTES.md，了解已有技术决策（避免推翻重来）。读完后，请用一段话向我汇报：- 项目当前阶段- 上一次完成的功能- 下一步应该做的任务- 是否存在未解决的阻塞确认无误后，我会下达本次开发任务。

四、核心文档模板

4.1 06_PROGRESS.md 开发进度表模板

# 开发进度表> 更新规则：每完成一个功能/修复，必须更新本表。AI 每次 session 开始必读。## 项目信息- 项目名称:- 启动日期:- 当前版本: v0.x.x- 当前阶段: [需求分析 / 开发中 / 测试 / 上线]## 总体进度- [x] 需求确认- [x] 技术选型- [ ] MVP 开发（进度 60%）- [ ] 测试- [ ] 上线## 功能清单（Feature Checklist）| 编号 | 功能名称 | 状态 | 负责AI | 开始日期 | 完成日期 | 关联Commit | 备注 ||------|---------|------|--------|---------|---------|-----------|------|| F001 | 用户登录 | ✅完成 | Claude | 2025-01-10 | 2025-01-11 | a1b2c3d | - || F002 | 商品列表 | 🚧进行中 | Cursor | 2025-01-12 | - | - | 待联调接口 || F003 | 订单支付 | ⏳待开始 | - | - | - | - | 依赖F002 |状态说明: ⏳待开始 / 🚧进行中 / ✅完成 / ❌阻塞 / 🔧修复中## 当前 Sprint 任务- [ ] 完成商品列表分页- [ ] 对接支付 SDK## 阻塞与风险- [ ] 第三方支付资质未下来（影响 F003）## 下一步计划1. 2. 

4.2 07_CHANGELOG.md 变更日志模板

# 变更日志> 格式：[日期] [类型] [AI工具] 描述 | Commit## 2025-01-12- [FEAT][Claude] 新增商品列表分页功能 | commit: a1b2c3d- [FIX][Cursor] 修复登录 token 过期无跳转 | commit: e4f5g6h- [REFACTOR][Gemini] 抽离 API 请求公共层 | commit: i7j8k9l## 类型说明- FEAT: 新功能- FIX: Bug修复- REFACTOR: 重构- DOCS: 文档更新- TEST: 测试相关- CHORE: 构建/配置

4.3 08_TECH_NOTES.md 技术决策记录模板

# 技术决策与问题解决记录> 记录重要技术选择、踩坑方案，避免 AI 切换后推翻重做。## [2025-01-10] 状态管理方案选型**决策**: 采用 Zustand 而非 Redux**原因**: 项目规模中等，Zustand 样板代码少**AI**: Claude 提议 → 人工确认## [2025-01-11] 图片上传性能问题**问题**: 大图上传阻塞 UI**解决**: 引入 Web Worker + 分片上传**关键代码位置**: `src/utils/uploader.ts`**AI**: Cursor 实现

4.4 10_GIT_WORKFLOW.md Git 规范模板

# Git 版本管理规范## 分支策略- `main`: 生产分支，仅接受 release 合并- `develop`: 开发主分支- `feature/F00X-功能名`: 功能分支（对应进度表编号）- `fix/问题描述`: 修复分支- `release/vX.X.X`: 发布分支## Commit 规范（Conventional Commits）

():

[optional body]

[AI: 工具名]  ← 标注本次代码由哪个 AI 协助

示例:

feat(order): 新增订单支付功能

  • 集成微信支付 SDK
  • 增加支付状态回调 [AI: Claude Opus]
## 版本号规则（SemVer）- 主版本.次版本.修订号 (1.2.3)- 上线前打 tag: `git tag -a v1.2.3 -m "xxx"`

五、AI 开发任务执行流程（SOP）

每次开发任务遵循以下流程：

Step 1 – 确认上下文

AI 执行”第三节启动流程”，汇报理解。

Step 2 – 任务拆解

人给出需求后，AI 必须先输出：

  • 任务理解
  • 涉及文件
  • 实现步骤
  • 潜在风险待人工确认后再写代码。

Step 3 – 编码实施

按步骤编码，遵循已有技术决策（见 08_TECH_NOTES）。

Step 4 – 自测

AI 输出测试点清单，本地自测通过。

Step 5 – 更新文档（强制）

完成后，AI 必须主动更新：

  • ✅ 06_PROGRESS.md（功能状态 / 完成日期 / Commit）
  • ✅ 07_CHANGELOG.md（变更记录）
  • ✅ 08_TECH_NOTES.md（如有新决策/踩坑）
  • ✅ 04_API_SPEC.md / 05_DATA_MODEL.md（如有接口或数据变动）

Step 6 – 提交代码

按 Git 规范提交，备注使用的 AI 工具。

六、AI 切换交接检查清单

当从一个 AI 工具切换到另一个时，人工确认：

  • [ ] 上一个 AI 已完成当前任务并更新文档
  • [ ] 所有变更已 commit 到 git
  • [ ] 06_PROGRESS.md 状态准确
  • [ ] 无未记录的本地临时改动
  • [ ] 新 AI 已执行”启动流程”并汇报正确

七、上线指导流程

参考 09_DEPLOY_GUIDE.md，标准步骤：

  1. 上线前检查
    • 所有功能在进度表中标记 ✅
    • 测试用例通过
    • 代码合并到 release/vX.X.X
  2. 构建打包: AI 协助执行构建脚本
  3. 环境变量核对: 检查 .env.production
  4. 部署: CI/CD 或手动部署步骤
  5. 回归验证: AI 生成验证 checklist
  6. 打 Tag: git tag 并推送
  7. 更新文档: 06_PROGRESS.md 记录上线版本与日期

八、禁忌事项（AI 必须遵守）

❌ 不得在未读文档的情况下直接写代码 ❌ 不得推翻 08_TECH_NOTES.md 中已确认的技术决策（除非人工同意） ❌ 不得遗忘更新 06_PROGRESS.md 和 07_CHANGELOG.md❌ 不得在未经确认的情况下删除或重构大段已有代码 ❌ 不得跳过 Git 提交规范 ❌ 不得在一次 commit 中混合多个无关功能

九、项目启动首次执行清单

Day 0 – 项目启动日：

  1. [ ] 创建 /docs 目录
  2. [ ] 填写 01_PRODUCT_SPEC.md（产品说明书）
  3. [ ] 填写 02_REQUIREMENTS.md（PRD）
  4. [ ] 填写 03_TECH_DESIGN.md（技术方案）
  5. [ ] 初始化 06_PROGRESS.md，列出所有功能点 F001~F00N
  6. [ ] 建立 Git 仓库，配置分支
  7. [ ] 将本作业书放入 00_AI_WORKBOOK.md
  8. [ ] 首次开启 AI session，使用第三节启动模板

此后每个开发日：从”AI 启动流程”开始，无例外。

十、备注

  • 本作业书本身也是可迭代的，若协作中发现问题，更新本书并通知所有参与的 AI。
  • 建议在项目 README 显著位置标注：”本项目采用 AI 协作作业书 v1.0，AI 请先阅读 docs/00_AI_WORKBOOK.md“。

— END —执行此作业书，即可让任何 AI 工具在任何时刻，快速接管你的项目。