Update from Sync Service

AI工程/团队级AI_Coding简明手册_逐页研究/00_概述与前言.md

@@ -0,0 +1,522 @@
+# 团队级 AI Coding 简明手册 - 逐页详细研究
+
+> 原文：系统设计研讨会分享 PPT v0.2（2026年6月18日）
+> 研究日期：2026-06-20
+> 研究目标：逐页深入分析，补充背景知识、工具推荐、实践建议
+
+---
+
+## 第1页：封面
+
+### 原文内容
+- 标题：团队级 AI Coding 简明手册 v0.2
+- 日期：2026年6月18日
+- 来源：系统设计研讨会分享
+- 版权声明：版权归分享人所有
+
+### 研究要点
+- 这是 v0.2 版本，说明经过了迭代完善
+- "团队级"强调这不是个人技巧，而是组织层面的工程实践
+- "简明手册"定位：实用导向，非学术理论
+
+---
+
+## 第2页：AI 编程思想发展过程
+
+### 原文内容
+AI 编程经历5个阶段演进：
+
+| 阶段 | 特征 | 自动化程度 |
+|------|------|------------|
+| **原始阶段** | 基于本能，手动复制代码或通过问答交互 | 半自动，有人值守 |
+| **Rule 约束** | 经验规则显化，如 RIPER-5 定义工作模式 | 半自动，持续对话 |
+| **规格驱动** | 需求结构化表达，如 OpenSpec 框架 | 过渡阶段 |
+| **Loop Engineering** | 可反馈闭环，AI 根据验收规则自动循环 | 接近全自动 |
+| **Harness 驾驭工程** | 纳入工程治理体系，提供约束+外部接口 | 全自动，Plan 后无人值守 |
+
+### 深入解读
+
+**1. 原始阶段**
+- **现状**：大多数开发者仍在这个阶段
+- **典型场景**：复制 ChatGPT 生成的代码到 IDE，手动调整
+- **问题**：上下文断裂，每次对话都要重新解释背景
+- **工具**：ChatGPT 网页版、早期 Copilot
+
+**2. Rule 约束阶段**
+- **RIPER-5 模式**（Research-Investigate-Plan-Execute-Review）：
+  - 由 AI 编程社区提出的结构化工作流
+  - 将复杂任务分解为5个明确阶段
+  - 每个阶段有不同的提示词策略
+- **其他 Rule 框架**：
+  - Cursor Rules：在 `.cursor/rules` 定义项目规范
+  - Claude Code 的 `CLAUDE.md`：项目级指令
+  - OpenCode 的 `.opencode/config.json`
+
+**3. 规格驱动阶段**
+- **OpenSpec 框架**：
+  - 将需求写成结构化的 Spec 文件
+  - AI 读取 Spec 生成代码，文件进文件出
+  - Spec 可以作为版本控制的产物
+- **优势**：需求可追溯，AI 行为可预测
+
+**4. Loop Engineering**
+- **核心理念**：AI 不是执行一次就结束，而是进入循环
+- **循环机制**：
+  - 定义验收标准（测试用例）
+  - AI 执行 → 运行测试 → 失败则修复 → 再次运行
+  - 直到所有测试通过才退出循环
+- **代表工具**：Claude Code 的 `/loop` 命令
+
+**5. Harness 驾驭工程**
+- **概念来源**：OpenAI、Anthropic 等公司提出的工程理念
+- **Harness（驾驭工具）**：
+  - 为 AI 提供约束体系（Rules、Specs）
+  - 为 AI 提供外部接口（MCP、Skills、CLI）
+  - 让 AI 在受控环境中自主工作
+- **关键特征**：
+  - Plan 阶段人机协作
+  - 执行阶段无人值守
+  - 可审计、可回溯
+
+### 实践建议
+- **评估你所在团队的位置**：大多数团队在阶段1-2之间
+- **渐进式升级**：不要跳级，先建立 Rule，再引入 Spec
+- **关键指标**：AI 代码采纳率、人均代码产出、缺陷率
+
+### 相关资源
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
+- [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
+- [Anthropic: Harness Design for Long-running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+
+---
+
+## 第3页：四大核心问题
+
+### 原文内容
+团队级 AI Coding 面临4个核心问题：
+
+1. **需求衔接**：如何用 AI 整理需求？
+2. **开发实现**：如何获得高质量的代码？
+3. **测试验收**：如何根据规格自动化测试？
+4. **Agent as Code**：如何组织协作文件，构建 AI 友好环境？
+
+### 深入解读
+
+**问题1：需求衔接**
+- **痛点**：AI 无法理解模糊需求，需要结构化输入
+- **关键问题**：
+  - 格式：Markdown vs YAML vs JSON
+  - 组织：按功能模块 vs 按用户故事
+  - 原型图传递：Figma 链接 vs HTML 原型
+  - 模版设计：新建需求 vs 变更需求
+- **解决方案**：使用 `docs/features/` 目录管理需求规格
+
+**问题2：开发实现**
+- **痛点**：AI 生成的代码质量不稳定，缺乏上下文
+- **关键问题**：
+  - 上下文管理：如何让 AI 理解项目结构
+  - 外部工具：如何调用数据库、API、文件系统
+  - 代码一致性：如何保证风格统一
+  - 多任务并发：如何同时开发多个功能
+  - 调试能力：如何让 AI 自主排查问题
+- **解决方案**：
+  - AGENTS.md 定义项目约束
+  - MCP 协议接入外部工具
+  - 打样工程提供代码模版
+
+**问题3：测试验收**
+- **痛点**：AI 生成的代码缺乏测试，难以验证
+- **关键问题**：
+  - 测试策略：单元测试 vs 集成测试 vs E2E 测试
+  - 浏览器操作：如何让 AI 操作浏览器进行 E2E 测试
+  - 测试用例管理：如何组织、版本控制
+- **解决方案**：
+  - TDD 驱动：先写测试再写代码
+  - Playwright MCP：AI 操作浏览器
+  - 测试用例生成：Browser Use 探索 → Playwright 固化
+
+**问题4：Agent as Code**
+- **痛点**：AI 协作文件散乱，缺乏组织
+- **关键问题**：
+  - 文件结构：如何组织 docs、skills、mcp 等目录
+  - 工具支持：如何让 Claude、Cursor、OpenCode 都识别
+  - 版本控制：如何将 AI 配置纳入 Git 管理
+- **解决方案**：
+  - AGENTS.md 作为宪法级文件
+  - 软链接到各工具的配置文件
+  - 统一目录结构：`docs/`, `skills/`, `mcp/`
+
+### 实践建议
+- **优先级排序**：先解决问题4（Agent as Code），建立基础
+- **逐步引入**：需求衔接 → 开发实现 → 测试验收
+- **度量指标**：AI 代码采纳率、测试覆盖率、缺陷逃逸率
+
+---
+
+## 第4页：AI 赋能软件开发实现地图
+
+### 原文内容
+完整的软件开发生命周期中，人与 AI 的分工：
+
+```
+需求分析 → 需求文档/原型图 → 技术方案 → 代码框架+打样
+   ↓              ↓              ↓              ↓
+  人+AI          人+AI          人+AI          人+AI
+   ↓              ↓              ↓              ↓
+AI代码编写 → 单元/API测试 → E2E测试 → Code Review → 提测部署
+   ↓              ↓            ↓           ↓           ↓
+  机             机+人         机+人        机+人        机+人
+```
+
+**核心 Loop**：研发自测阶段（AI 自治运行）
+**全流程超级 Loop**：从需求到部署（人机协作）
+
+### 深入解读
+
+**阶段1：需求分析（人+AI）**
+- **人的角色**：用户访谈、竞品分析、业务理解
+- **AI 的角色**：整理访谈记录、生成用户故事、绘制流程图
+- **工具推荐**：
+  - ChatGPT/Claude：整理访谈笔记
+  - Miro AI：自动生成流程图
+  - Whimsical AI：生成用户旅程图
+
+**阶段2：需求文档+原型图（人+AI）**
+- **人的角色**：定义业务规则、审核原型
+- **AI 的角色**：生成需求文档草稿、生成 HTML 原型
+- **工具推荐**：
+  - Cursor/Claude Code：生成 Markdown 需求文档
+  - v0.dev：生成 React 原型
+  - Galileo AI：生成 UI 设计稿
+
+**阶段3：技术方案（人+AI）**
+- **人的角色**：架构决策、技术选型
+- **AI 的角色**：生成技术规格文档、绘制架构图
+- **工具推荐**：
+  - PlantUML + AI：生成领域模型、时序图
+  - Claude Code：生成 API 设计文档
+
+**阶段4：代码框架+打样（人+AI）**
+- **人的角色**：定义目录结构、编写核心接口
+- **AI 的角色**：生成 CRUD 代码、填充模版
+- **工具推荐**：
+  - Claude Code + 打样工程：生成符合项目规范的代码
+  - Cursor Composer：批量生成代码
+
+**阶段5：AI 代码编写（机）**
+- **AI 的角色**：根据 Spec 自动生成代码
+- **人的角色**：审核关键逻辑
+- **工具推荐**：
+  - Claude Code Loop 模式：自动循环直到测试通过
+  - OpenCode：根据 OpenSpec 生成代码
+
+**阶段6：单元/API 测试（机+人）**
+- **AI 的角色**：生成测试代码、运行测试
+- **人的角色**：审核测试用例、补充边界条件
+- **工具推荐**：
+  - Jest + AI：生成单元测试
+  - Karate：生成 API 测试
+
+**阶段7：E2E 测试（机+人）**
+- **AI 的角色**：操作浏览器、生成测试脚本
+- **人的角色**：定义关键路径、审核测试
+- **工具推荐**：
+  - Playwright MCP：AI 操作浏览器
+  - Browser Use：探索式测试生成
+
+**阶段8：Code Review（机+人）**
+- **AI 的角色**：自动审查代码、发现问题
+- **人的角色**：审核 AI 的审查结果
+- **工具推荐**：
+  - GitHub Copilot Code Review
+  - Claude Code：PR Review
+  - CodeRabbit：AI 代码审查
+
+**阶段9：提测部署（机+人）**
+- **AI 的角色**：生成部署脚本、执行部署
+- **人的角色**：审核部署配置、处理异常
+- **工具推荐**：
+  - GitHub Actions + AI：自动生成 CI/CD
+  - Vercel/Netlify：一键部署
+
+### 实践建议
+- **从核心 Loop 开始**：先在研发自测阶段引入 AI
+- **逐步扩展到超级 Loop**：覆盖需求、测试、部署
+- **关键指标**：AI 参与率、自动化程度、交付周期
+
+---
+
+## 第5页：AI 赋能软件开发工具体系
+
+### 原文内容
+展示了各阶段使用的工具和产出物：
+
+| 阶段 | 工具 | 产出 |
+|------|------|------|
+| 原型图 | Stitch/Figma/HTML | Design.md |
+| 需求规格 | AI IDE + 模版 | Markdown |
+| 技术规格 | AI IDE + 模版 | Markdown |
+| 代码编写 | AI IDE + 规范 | TS/Java |
+| 测试规格 | AI IDE + 模版 | Markdown |
+| E2E 测试 | Playwright MCP | TS 代码 |
+| Bug 修复 | AI IDE + 模版 | 代码修复 |
+| 部署 | AI IDE + Yaml | 环境部署 |
+
+### 深入解读
+
+**工具链核心：AI IDE**
+- **定义**：集成 AI 能力的开发环境
+- **代表工具**：
+  - **Cursor**：基于 VS Code，AI 优先设计
+  - **Claude Code**：命令行 AI 编程工具
+  - **OpenCode**：开源的 AI 编程终端
+  - **Kiro**：AWS 推出的 AI IDE
+  - **Trae**：字节跳动推出的 AI IDE
+
+**模版体系**
+- **需求规格模版**：定义需求文档结构
+- **技术规格模版**：定义技术设计文档结构
+- **测试规格模版**：定义测试用例结构
+- **代码模版**：定义代码风格、目录结构
+
+**关键工具详解**
+
+1. **Design.md**
+   - 作用：约束 AI 生成的前端风格
+   - 内容：颜色、字体、间距、组件库
+   - 来源：从设计稿提炼或从现有代码反推
+
+2. **Playwright MCP**
+   - 作用：让 AI 操作浏览器
+   - 场景：E2E 测试、UI 调试
+   - 优势：标准化接口，支持 Accessibility Tree
+
+3. **MCP（Model Context Protocol）**
+   - 作用：AI 与外部系统通信的标准协议
+   - 场景：数据库、API、文件系统接入
+   - 优势：标准化、双向通信、即插即用
+
+### 实践建议
+- **建立模版库**：将常用的文档结构模版化
+- **统一工具链**：团队使用相同的 AI IDE
+- **维护 Design.md**：确保 AI 生成的 UI 风格一致
+
+---
+
+## 第6页：分隔页（01 需求衔接）
+
+### 原文内容
+章节分隔页，标志进入"需求衔接"部分
+
+### 研究要点
+- 这是第4个核心问题的展开
+- 需求衔接是整个开发流程的起点
+- 良好的需求衔接能大幅提升 AI 代码质量
+
+---
+
+## 第7页：需求规格编写
+
+### 原文内容
+**AI 能理解的需求格式**：Markdown/Excel 表格
+
+**关键要素**：
+1. **模块切分**（增量/存量）
+2. **字段清单**
+3. **原型链接**
+4. **业务规则**
+
+**编写原则**：
+- 先写业务背景，再切模块
+- 一个模块 = 一个文档
+- 分解为增量需求和存量需求：
+  - **增量需求**：全新功能，需新建模块
+  - **存量修改**：对已有功能做变更
+- Tips：增量建模块，存量标改动
+
+**字段清单示例**：
+```markdown
+| 字段名    | 类型    | 必填 | 默认值 | 描述         |
+|-----------|---------|------|--------|--------------|
+| username  | string  | 是   | —      | 登录用户名   |
+| email     | string  | 是   | —      | 电子邮箱     |
+| role      | enum    | 否   | user   | 用户角色     |
+| status    | boolean | 否   | true   | 是否启用     |
+```
+
+**字段定义要求**：
+- 定义完整字段
+- 标注校验规则
+- 标注 UI 展示
+- 标注数据来源
+
+**原型图传递**：
+- Figma：选中 Frame → Share → Copy link
+- Stitch：选中设计稿 → 获取分享链接
+- HTML 版本：用 HTML/CSS 做可交互原型，提交到代码仓库
+
+**业务规则示例**：
+```markdown
+R1 用户名唯一不可重复
+R2 邮箱格式正则校验
+R3 密码 ≥ 8 位含大小写
+R4 删除需二次确认
+R5 超时自动登出
+R6 管理员不可降级
+```
+
+**编写原则**：
+- 条目化 + 正交分解
+- 每条规则独立可测
+
+**重要 Tip**：BA 也应该工作在代码仓库中，让 AI 基于当前系统事实构建新需求
+
+### 深入解读
+
+**为什么用 Markdown？**
+- **版本控制友好**：可以纳入 Git 管理
+- **AI 友好**：LLM 对 Markdown 理解能力强
+- **可读性好**：人和 AI 都能轻松阅读
+- **工具支持**：所有 AI IDE 都支持
+
+**为什么区分增量/存量？**
+- **增量需求**：AI 从零生成，需要完整上下文
+- **存量修改**：AI 需要理解现有代码，才能安全修改
+- **影响 AI 策略**：增量可以用生成式 AI，存量需要理解现有代码
+
+**字段清单的价值**
+- **明确数据模型**：AI 可以根据字段生成数据库表、API 接口
+- **减少歧义**：类型、必填、默认值都明确定义
+- **自动生成代码**：可以根据字段清单生成前端表单、后端 DTO
+
+**业务规则条目化**
+- **独立可测**：每条规则可以单独写测试用例
+- **正交分解**：规则之间不重叠、不冲突
+- **可追溯**：每条规则可以追溯到代码实现
+
+**BA 在代码仓库中工作**
+- **优势**：
+  - BA 可以看到现有需求、代码结构
+  - AI 可以基于现有需求生成新需求
+  - 需求变更可以追溯历史
+- **实践**：
+  - BA 使用 Git 管理需求文档
+  - 需求变更通过 PR 审核
+  - AI 参与需求文档的生成和审核
+
+### 实践建议
+- **建立需求模版**：统一需求文档结构
+- **使用字段清单**：明确数据模型
+- **业务规则条目化**：方便测试和追溯
+- **BA 使用 Git**：将需求管理纳入版本控制
+
+### 工具推荐
+- **需求管理**：Git + Markdown
+- **原型设计**：Figma、Stitch、HTML
+- **字段清单**：Excel、Markdown 表格
+- **业务规则**：Markdown 列表
+
+---
+
+## 第8页：原型图设计
+
+### 原文内容
+**原型图设计的3种方式**：
+
+**1. AI 设计软件输出**
+- 在设计工具中完成原型，通过 URL 链接嵌入需求文档
+- 标注映射：在需求中注明对应模块和页面
+- **Figma**：选中 Frame → Share → Copy link
+- **Stitch**：选中设计稿 → 获取分享链接
+
+**2. HTML + CSS 输出**
+- 用 HTML/CSS 做可交互原型，提交到代码仓库
+- **优势**：
+  - 真实代码：直接使用项目组件库拼装
+  - 可交互：点击、跳转、表单输入均可演示
+  - 版本管理：随代码仓库一起管理和 Review
+
+**3. Design.md 生成统一的视觉风格**
+- **Design.md**：用 Markdown 约束 AI 生成的前端风格，确保输出与项目组件库一致
+- **两种产生方式**：
+  - 从设计稿提炼规则
+  - 从现有代码反推样式
+
+**Design.md 示例**：
+```markdown
+# Design System
+
+## Colors
+- primary: #1a1a1a
+- background: #ffffff
+- text: #333333
+
+## Typography
+- font: -apple-system, sans-serif
+- h1: 1.5rem / 700
+- body: 0.875rem / 400
+
+## Spacing
+- unit: 8px (base)
+```
+
+**参考资源**：https://getdesign.md
+
+### 深入解读
+
+**为什么需要原型图？**
+- **减少歧义**：文字描述容易产生误解，原型图直观展示
+- **AI 理解**：AI 可以通过原型图理解 UI 结构
+- **用户确认**：用户可以提前看到效果，减少返工
+
+**Figma vs Stitch vs HTML**
+
+| 维度 | Figma | Stitch | HTML |
+|------|-------|--------|------|
+| **学习成本** | 中 | 低 | 高 |
+| **AI 友好度** | 中 | 高 | 极高 |
+| **版本控制** | 差 | 中 | 极好 |
+| **交互能力** | 中 | 中 | 极强 |
+| **协作能力** | 极强 | 强 | 中 |
+
+**Figma**
+- **优势**：设计师常用，生态丰富
+- **劣势**：AI 无法直接读取 Figma 文件，需要通过链接
+- **适用场景**：专业设计师参与的项目
+
+**Stitch**
+- **优势**：AI 友好，可以直接生成设计稿
+- **劣势**：生态较小
+- **适用场景**：AI 优先的项目
+
+**HTML**
+- **优势**：AI 可以直接生成，版本控制友好
+- **劣势**：需要前端开发能力
+- **适用场景**：技术团队主导的项目
+
+**Design.md 的价值**
+- **统一风格**：确保 AI 生成的 UI 风格一致
+- **可维护**：Markdown 格式，易于修改和版本控制
+- **可复用**：可以在多个项目中复用
+
+**Design.md 的内容**
+- **Colors**：主色、背景色、文字色
+- **Typography**：字体、字号、字重
+- **Spacing**：间距、边距
+- **Components**：按钮、表单、卡片等组件样式
+- **Layout**：布局规则
+
+### 实践建议
+- **选择适合的原型工具**：根据团队能力选择 Figma/Stitch/HTML
+- **维护 Design.md**：确保 AI 生成的 UI 风格一致
+- **原型与代码同步**：原型变更时同步更新代码
+- **使用 getdesign.md**：参考现成的 Design.md 模版
+
+### 工具推荐
+- **设计工具**：Figma、Stitch
+- **原型工具**：HTML/CSS、v0.dev
+- **Design.md 生成**：从设计稿提炼、从代码反推
+
+---
+
+（由于篇幅较长，我将继续为剩余页面创建详细研究文档。需要我继续吗？）

AI工程/团队级AI_Coding简明手册_逐页研究/00_索引.md

@@ -0,0 +1,354 @@
+# 团队级 AI Coding 简明手册 v0.2 - 逐页研究索引
+
+> 原文：系统设计研讨会分享 PPT（2026年6月18日）
+> 研究日期：2026-06-20
+> 研究范围：第1-30页（全文）
+> 归档位置：/obsidian/AI工程/团队级AI_Coding简明手册_逐页研究/
+
+---
+
+## 文档结构
+
+### 00_概述与前言.md
+**覆盖页码**：第1-8页
+
+**核心内容**：
+- 第1页：封面信息
+- 第2页：AI 编程思想发展过程（5个阶段）
+- 第3页：四大核心问题概述
+- 第4页：AI 赋能软件开发实现地图
+- 第5页：AI 赋能软件开发工具体系
+- 第6页：分隔页（01 需求衔接）
+- 第7页：需求规格编写
+- 第8页：原型图设计
+
+**关键概念**：
+- AI 编程5阶段：原始 → Rule约束 → 规格驱动 → Loop工程 → Harness驾驭
+- 4个核心问题：需求衔接、开发实现、测试验收、Agent as Code
+- 需求规格：Markdown格式、字段清单、业务规则条目化
+- 原型图：Figma/Stitch/HTML + Design.md
+
+---
+
+### 01_开发实现_第9-15页.md
+**覆盖页码**：第9-15页
+
+**核心内容**：
+- 第9页：分隔页（02 开发实现）
+- 第10页：如何让 AI 听话 - 规则、规格、技能
+- 第11页：构建 AI 上下文体系
+- 第12页：如何让 AI 调用外部工具
+- 第13页：用什么 AI 编程工具
+- 第14页：用什么 SDD 框架比较好
+- 第15页：一个新星：Superpower
+
+**关键概念**：
+- 三要素：Rules（规则）、Specification（规格）、Skill（技能）
+- 上下文体系：AGENTS.md + docs/（standards/features/plans/designs/others）
+- 过程方案 vs 事实方案：Plans（追加新文件）vs Designs（覆盖更新）
+- 外部工具：MCP、Skills、CLI
+- AI 工具：Claude Code、Cursor、Kiro、Trae、OpenCode、Codex CLI
+- SDD 框架：BMAD、Spec Kit、OpenSpec、Kiro
+
+---
+
+### 02_开发实现续_第16-19页.md
+**覆盖页码**：第16-19页
+
+**核心内容**：
+- 第16页：技术规格如何编写
+- 第17页：打样工程：如何让 AI 抄作业
+- 第18页：如何多任务同步开发
+- 第19页：完整的核心 Loop 过程（研发自测）
+
+**关键概念**：
+- 技术规格 DSL：领域模型（PlantUML）、数据库（SQL DDL）、API（OpenAPI）、时序图、专题设计
+- 打样工程：提供代码模版，让 AI "抄作业"
+- 三层架构：Controller → Service → Repository
+- Git Worktree：多任务并行开发
+- 核心 Loop：Plan → TDD → 验证
+
+---
+
+### 03_测试验收_第20-25页.md
+**覆盖页码**：第20-25页
+
+**核心内容**：
+- 第20页：分隔页（03 测试验收）
+- 第21页：AI 辅助下的测试策略
+- 第22页：AI 如何操作浏览器
+- 第23页：如何用测试用例生成 E2E 测试
+- 第24页：Playwright E2E 示例
+- 第25页：超级 Loop（E2E Loop）
+
+**关键概念**：
+- 测试策略：Lint → Code Review → 单元测试 → API 测试 → E2E 测试
+- AI 操作浏览器：Playwright MCP、Chrome DevTools MCP、Browser Use、Computer Use
+- E2E 测试生成：Browser Use 探索 → Playwright 固化 → 截图视觉兜底
+- Playwright 最佳实践：稳定选择器、API 登录、测试数据管理
+- 超级 Loop：在核心 Loop 基础上增加 E2E 测试验证
+
+---
+
+### 04_Agent_as_Code_第26-30页.md
+**覆盖页码**：第26-30页
+
+**核心内容**：
+- 第26页：分隔页（04 Agent as Code）
+- 第27页：AI 工程文件管理
+- 第28页：分隔页（附录&参考资料）
+- 第29页：关于 AI 编程实践的心得
+- 第30页：参考资料
+
+**关键概念**：
+- Agent as Code：将 AI 协作文件以代码方式管理
+- AGENTS.md 作为宪法级配置
+- 软链接实现多工具共享配置
+- Skills 目录：可复用的 AI 能力单元
+- MCP 配置：让 AI 访问外部工具
+- 实践心得：放弃"开箱即用"，"少量取用，大量实践"
+
+---
+
+## 核心框架总结
+
+### 团队级 AI Coding 的4个核心问题
+
+| 问题 | 核心挑战 | 解决方案 |
+|------|---------|---------|
+| **需求衔接** | 如何编写 AI 能理解的需求？ | Markdown 格式、字段清单、业务规则条目化、原型图传递 |
+| **开发实现** | 如何让 AI 生成高质量代码？ | 规则/规格/技能、上下文体系、MCP/Skills/CLI、SDD 框架、打样工程、核心 Loop |
+| **测试验收** | 如何自动化测试 AI 生成的代码？ | 分层测试、AI 操作浏览器、E2E 测试生成、超级 Loop |
+| **Agent as Code** | 如何组织 AI 协作文件？ | AGENTS.md、文档体系、Skills 库、MCP 配置、软链接 |
+
+### AI 编程5阶段演进
+
+```
+原始阶段 → Rule 约束 → 规格驱动 → Loop Engineering → Harness 驾驭工程
+   ↓           ↓           ↓            ↓                  ↓
+手动复制   RIPER-5    OpenSpec     自动循环           工程治理
+半自动     持续对话   文件进出     测试驱动           无人值守
+```
+
+### 文档分层体系
+
+```
+AGENTS.md          ← 宪法（所有 AI 工具读取）
+docs/
+├── standards/     ← 标准规格（架构/命名/API/安全规范）
+├── features/      ← 需求规格（产品/BA维护）
+├── designs/       ← 设计规格（事实方案，Source of Truth）
+├── plans/         ← 计划规格（过程方案，追加不修改）
+└── others/        ← 架构决策、Release、测试用例等
+skills/            ← AI 技能（可复用能力单元）
+mcp/               ← MCP 配置（外部工具接入）
+```
+
+### 核心 Loop 流程
+
+```
+Plan 阶段（人机协作）
+    ↓
+装载需求规格 → 创建 Plan → 确认 Plan
+    ↓
+执行阶段（AI 自治）
+    ↓
+编写 API 测试 → 编写实现 → 运行测试
+    ↓                              ↓
+    ↓ 失败                        ↓ 成功
+    ↓                              ↓
+修复重试 ←──────────────────── 退出循环
+```
+
+### 测试策略金字塔
+
+```
+        E2E 测试（Playwright）
+       /                      \
+      /    API 测试（Karate）    \
+     /                          \
+    /    单元测试（JUnit/Jest）    \
+   /                              \
+  /    Code Review（AI + 人工）     \
+ /                                  \
+/    Lint 代码扫描（ESLint/SonarQube）\
+/____________________________________\
+```
+
+---
+
+## 关键工具清单
+
+### AI 编程工具
+- **Claude Code**：Anthropic 出品，强大的推理能力
+- **Cursor**：基于 VS Code，AI 优先设计
+- **Kiro**：AWS 出品，深度集成 AWS 服务
+- **Trae**：字节跳动出品，中文支持好
+- **OpenCode**：开源，支持多种 AI 模型
+- **Codex CLI**：OpenAI 出品，基于 GPT-4
+
+### SDD 框架
+- **BMAD**：企业级，强治理，多 Agent 编排
+- **Spec Kit**：工程化，Git 集成，适合新项目
+- **OpenSpec**：轻量级，灵活，适合存量项目
+- **Kiro**：IDE 原生，可执行 Spec，自动验证
+
+### 测试工具
+- **Playwright**：最流行的 E2E 测试框架
+- **Browser Use**：AI 操作浏览器，Token 消耗低
+- **Karate**：BDD 风格的 API 测试框架
+- **RestAssured**：Java API 测试库
+- **SonarQube**：代码质量分析工具
+- **ESLint**：JavaScript 代码检查工具
+
+### 文档工具
+- **PlantUML**：文本化的 UML 图
+- **OpenAPI**：API 规范定义
+- **Markdown**：通用文档格式
+- **Mermaid**：Markdown 中的图表
+
+### 协作工具
+- **Git**：版本控制
+- **GitHub/GitLab**：代码托管和协作
+- **Git Worktree**：多工作区并行开发
+
+---
+
+## 最佳实践清单
+
+### 需求阶段
+- [ ] 使用 Markdown 编写需求规格
+- [ ] 区分增量需求和存量需求
+- [ ] 使用字段清单定义数据模型
+- [ ] 业务规则条目化，每条规则独立可测
+- [ ] 通过原型图传递 UI 设计（Figma/Stitch/HTML）
+- [ ] 维护 Design.md 约束前端风格
+
+### 开发阶段
+- [ ] 建立 AGENTS.md 作为宪法级配置
+- [ ] 区分过程方案（Plans）和事实方案（Designs）
+- [ ] 使用 DSL 编写技术规格（PlantUML/SQL/OpenAPI）
+- [ ] 建立打样工程，提供代码模版
+- [ ] 使用 TDD 驱动开发
+- [ ] 使用 Git Worktree 并行开发
+- [ ] Plan 阶段充分沟通，关闭所有开放性问题
+
+### 测试阶段
+- [ ] 分层测试：单元测试 → API 测试 → E2E 测试
+- [ ] 先用 Browser Use 探索，再固化到 Playwright
+- [ ] 使用稳定的选择器（data-testid、角色、标签）
+- [ ] 关键页面截图验证（视觉回归测试）
+- [ ] 所有测试集成到 CI/CD 流程
+
+### 协作阶段
+- [ ] 使用 AGENTS.md 作为统一入口
+- [ ] 使用软链接让多个工具共享配置
+- [ ] 所有配置纳入 Git 管理
+- [ ] 建立 Skills 库，沉淀常用 AI 能力
+- [ ] 配置 MCP 让 AI 访问外部工具
+
+---
+
+## 学习路径
+
+### 入门（1-2周）
+1. 理解 AI 编程的5个发展阶段
+2. 建立 AGENTS.md
+3. 使用一个 AI 工具（如 Claude Code）
+4. 实践核心 Loop（Plan → TDD → 验证）
+
+### 进阶（1-2月）
+1. 学习 SDD 框架（BMAD/SpecKit/OpenSpec/Kiro）
+2. 使用 DSL 编写技术规格
+3. 建立打样工程
+4. 实践分层测试
+5. 使用 Playwright 进行 E2E 测试
+
+### 高级（持续）
+1. 构建完整的 Harness 体系
+2. 开发自定义 Skills
+3. 配置 MCP 访问外部工具
+4. 优化 AI 工作流
+5. 分享实践经验
+
+---
+
+## 关键洞察
+
+1. **AI 编程不是银弹**：需要工程化的方法来驾驭
+2. **上下文是关键**：AI 需要清晰的上下文才能生成高质量代码
+3. **测试是保障**：自动化测试是 AI 生成代码质量的保障
+4. **实践出真知**：没有放之四海而皆准的方案，需要根据项目特点定制
+5. **持续演进**：AI 能力在快速提升，方法也需要持续演进
+6. **区分过程和事实**：Plans 是过程记录（追加不修改），Designs 是事实描述（覆盖更新）
+7. **少量取用，大量实践**：不要一开始就引入所有概念，先实践核心，再逐步扩展
+
+---
+
+## 术语表
+
+| 术语 | 英文 | 定义 |
+|------|------|------|
+| AI 编程 | AI Coding | 使用 AI 辅助或自动化进行软件开发 |
+| Harness | Harness | 为 AI 提供约束和工具的工程实践 |
+| SDD | Spec-Driven Development | 以规格文档为核心的开发方法 |
+| MCP | Model Context Protocol | AI 与外部系统通信的标准协议 |
+| AGENTS.md | AGENTS.md | AI 协作的宪法级配置文件 |
+| Plan | Plan | AI 执行任务的规划文档 |
+| Spec | Specification | 结构化的需求描述 |
+| Rule | Rule | 约束 AI 行为的规则 |
+| Skill | Skill | 可复用的 AI 能力单元 |
+| Loop | Loop | AI 自治运行的开发循环 |
+| TDD | Test-Driven Development | 测试驱动开发 |
+| E2E | End-to-End | 端到端测试 |
+| DSL | Domain Specific Language | 领域特定语言 |
+| Worktree | Git Worktree | Git 的多工作区功能 |
+| Browser Use | Browser Use | AI 操作浏览器的框架 |
+| Playwright | Playwright | 浏览器自动化测试框架 |
+| BMAD | Business Model Architecture Design | 企业级 SDD 框架 |
+| OpenSpec | OpenSpec | 轻量级 SDD 框架 |
+| Kiro | Kiro | AWS 推出的 AI IDE 和 SDD 框架 |
+
+---
+
+## 参考资料
+
+1. [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
+2. [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
+3. [Anthropic: Harness Design for Long-running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+4. [从 Rule、Spec 到 Harness：AI Coding 的渐进式建设路径](https://mp.weixin.qq.com/s/UCh2bPzMZjNBMBCCJysuNw)
+5. [让 AI 乖乖听话的几个 Rules](https://mp.weixin.qq.com/s/FXNzk_y2Z2h8BVe62uEn_A)
+6. [Understanding SDD: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
+7. [harness-engineering-in-ai-coding](https://github.com/2361485765/harness-engineering-in-ai-coding)
+8. [attractor-guided-engineering-template](https://github.com/entropy-cloud/attractor-guided-engineering-template)
+9. [OpenAI: Tools Computer Use](https://developers.openai.com/api/docs/guides/tools-computer-use)
+
+---
+
+## 文档信息
+
+- **原文**：团队级 AI Coding 简明手册 v0.2
+- **作者**：系统设计研讨会分享人
+- **日期**：2026年6月18日
+- **研究日期**：2026-06-20
+- **研究范围**：第1-30页（全文）
+- **归档位置**：/obsidian/AI工程/团队级AI_Coding简明手册_逐页研究/
+- **文件列表**：
+  - 00_概述与前言.md（第1-8页）
+  - 01_开发实现_第9-15页.md（第9-15页）
+  - 02_开发实现续_第16-19页.md（第16-19页）
+  - 03_测试验收_第20-25页.md（第20-25页）
+  - 04_Agent_as_Code_第26-30页.md（第26-30页）
+  - 00_索引.md（本文档）
+
+---
+
+**研究完成** ✅
+
+所有30页内容已详细研究并归档，包含：
+- 原文内容提取
+- 深入解读和背景知识
+- 实践建议和工具推荐
+- 代码示例和配置示例
+- 最佳实践清单
+- 学习路径指南

AI工程/团队级AI_Coding简明手册_逐页研究/01_开发实现_第9-15页.md

@@ -0,0 +1,315 @@
+# 第9-15页：开发实现篇
+
+> 章节：02 开发实现
+> 核心问题：如何让 AI 听话？如何构建 AI 上下文体系？如何调用外部工具？
+
+---
+
+## 第9页：分隔页（02 开发实现）
+
+### 原文内容
+章节分隔页，标志进入"开发实现"部分
+
+### 研究要点
+- 这是4个核心问题中的第2个
+- 开发实现是整个流程中最关键的环节
+- 核心目标：让 AI 生成高质量、符合规范的代码
+
+---
+
+## 第10页：如何让 AI 听话 - 规则、规格、技能
+
+### 原文内容
+**三要素模型**：
+
+| 要素 | 定义 | 示例 |
+|------|------|------|
+| **规则 Rules** | 约束 AI 行为的边界，定义能做什么、不能做什么 | "请做一个登录注册页面，需要能实现邮箱验证" |
+| **规格 Specification** | 把模糊的需求收敛为结构化的内容，甚至通过 DSL 描述 | 用户故事 + 验收标准 |
+| **技能 Skill** | 通过打包提示词、脚本、模版，进一步精确拓展 AI 的能力 | 提示词 + 规格文档 |
+
+**规则示例（Java 代码风格）**：
+```markdown
+# Java 代码风格 Rules
+1. 使用 Java 17 语法，不使用已废弃 API
+2. 类名使用大驼峰（PascalCase），方法名和变量名使用小驼峰（camelCase）
+3. 常量使用全大写下划线分隔（UPPER_SNAKE_CASE）
+4. 单行代码不超过 120 字符，超过则换行
+5. 大括号采用 Egyptian 风格（左括号不换行）
+6. 禁止使用 @Autowired 字段注入，改用构造器注入
+```
+
+**规格示例（用户故事 + 验收标准）**：
+```markdown
+作为一个新用户或现有用户，我想要一个同时支持注册和登录的页面，
+并且在注册时能通过邮箱完成身份验证，以便安全地创建账户并登录系统。
+
+验收标准（AC）：
+1. 用户可以输入邮箱、密码等必要信息进行注册。注册提交后，
+   系统向用户邮箱发送验证链接（或验证码）。用户点击链接
+  （或输入验证码）后，账户状态变为"已验证"。
+2. 已验证用户可使用邮箱和密码登录系统。未验证邮箱的用户
+   尝试登录时，系统提示"请先完成邮箱验证"。
+3. 邮箱格式不正确或已被注册时，系统给出明确提示。验证链
+   接过期或无效时，支持重新发送验证邮件。
+```
+
+### 深入解读
+
+**规则 Rules 的本质**
+- 作用：约束 AI 的行为边界
+- 载体：
+  - Cursor：`.cursor/rules/` 目录
+  - Claude Code：`CLAUDE.md` 文件
+  - OpenCode：`.opencode/config.json`
+  - 通用：`AGENTS.md` 文件
+
+**规则的分类**：
+1. 代码风格规则：命名规范、格式规范
+2. 架构规则：分层架构、依赖方向
+3. 安全规则：敏感数据处理、权限控制
+4. 性能规则：数据库查询优化、缓存策略
+
+**规格 Specification 的价值**
+- 消除歧义：将模糊需求转化为明确定义
+- 可验证性：验收标准可以直接转化为测试用例
+- 可追溯性：需求变更有历史记录
+
+**规格的格式**：
+1. 用户故事格式：As a... I want... So that...
+2. Given-When-Then 格式：行为驱动开发（BDD）
+3. 表格格式：字段清单、业务规则
+4. DSL 格式：领域特定语言
+
+**技能 Skill 的概念**
+- 定义：打包的可复用能力单元
+- 组成：提示词模版、脚本工具、文档模版、配置文件
+- 复用性：可以在多个项目中使用
+
+### 实践建议
+- 建立规则库：将常用的规则沉淀下来
+- 使用规格模版：统一需求文档格式
+- 开发技能包：将常用的能力封装成技能
+
+---
+
+## 第11页：构建 AI 上下文体系
+
+### 原文内容
+**核心理念**：使用完整的文档来描述上下文和约束体系，区分过程方案和事实方案，减少维护成本。
+
+**文档分层结构**：
+```
+AGENTS.md          ← 宪法
+docs/
+├── standards/     ← 标准规格（架构/命名/API/安全规范）
+├── features/      ← 需求规格（产品/BA维护）
+├── plans/         ← 计划规格（过程方案）
+├── designs/       ← 设计规格（事实方案，Source of Truth）
+└── others/        ← 架构决策、Release、测试用例等
+```
+
+**规格流转**：
+- 追加（Plans）：每次创建新文件，细微修改不再更新
+- 变更（Designs）：每次以最终态更新，作为下一次 Plan 的事实依据
+
+### 深入解读
+
+**AGENTS.md 的内容**：
+```markdown
+# 项目基本信息
+- 项目名称：示例项目
+- 技术栈：Java 17, Spring Boot 3.x, MySQL 8.0
+- 代码规范：阿里巴巴 Java 开发手册
+
+# AI 行为规则
+1. 生成代码必须符合代码规范
+2. 数据库表必须包含 created_at, updated_at 字段
+3. API 接口必须使用 RESTful 风格
+4. 敏感数据必须加密存储
+```
+
+**过程方案 vs 事实方案详细对比**
+
+| 维度 | 过程方案（Plans） | 事实方案（Designs） |
+|------|------------------|-------------------|
+| 目的 | 记录实现过程 | 记录当前状态 |
+| 更新方式 | 追加新文件 | 覆盖更新 |
+| 生命周期 | 短期（任务完成后归档） | 长期（持续维护） |
+| 维护成本 | 低（不修改旧文件） | 高（必须保持最新） |
+| 使用场景 | 任务执行、问题排查 | 新功能开发、架构决策 |
+| 示例 | plan-2026-06-20-feature-x.md | database-schema.md |
+
+**Plans 最佳实践**：
+- 命名规范：`plan-YYYY-MM-DD-feature-name.md`
+- 内容结构：目标、方案、任务列表、状态、问题记录
+- 归档策略：任务完成后移动到 `archive/` 目录
+
+**Designs 最佳实践**：
+- 命名规范：使用功能名称，如 `database-schema.md`
+- 内容结构：概述、详细设计、变更历史
+- 更新策略：每次变更必须更新文档，保持最新
+
+---
+
+## 第12页：如何让 AI 调用外部工具？
+
+### 原文内容
+**三种方式**：
+
+**1. MCP（Model Context Protocol）**
+- AI 与外部系统通信的标准协议
+- 标准化接口、双向通信、即插即用
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "node",
+      "args": ["mcp-server-sqlite"]
+    }
+  }
+}
+```
+
+**2. Skills**
+- 将开源工具用脚本封装成 AI 可直接调用的能力单元
+- 脚本封装、触发词驱动、可复用
+```markdown
+# Commit & Push Skill
+## 触发词: commit, push
+## 执行
+git add -A
+git commit -m "{message}"
+git push
+## 规则
+- 提交前检查 lint
+- 信息遵循 conventional commit
+```
+
+**3. Commands（CLI）**
+- 通过 CLI 命令让 AI 直接调用外部工具
+- 即时执行、管道组合、权限可控
+```bash
+# AI 通过 CLI 调用工具
+> 部署到生产环境
+npm run build
+npx vercel --prod
+```
+
+### 深入解读
+
+**MCP 详解**
+- Anthropic 提出的开放标准协议
+- Client-Server 架构
+- 常用 MCP Server：
+  - 数据库：mcp-server-sqlite、mcp-server-postgres
+  - 文件系统：mcp-server-filesystem
+  - Web 搜索：mcp-server-brave-search
+  - GitHub：mcp-server-github
+  - 浏览器：mcp-server-playwright
+
+**Skills 详解**
+- 可复用的能力单元
+- 组成：触发词、执行逻辑、参数、规则
+- 开发流程：需求分析 → 脚本开发 → 触发词定义 → 测试验证 → 文档编写
+
+**CLI 安全考虑**：
+- 白名单机制：只允许执行特定的命令
+- 沙箱环境：在隔离环境中执行
+- 审计日志：记录所有执行的命令
+
+---
+
+## 第13页：用什么 AI 编程工具？
+
+### 原文内容
+**三类工具**：
+
+**1. 命令行类**（AI 优先，人辅助）
+- Claude Code、Codex CLI、OpenCode
+
+**2. AI IDE**（人掌控感更强）
+- Cursor、Kiro、Trae
+
+**3. 增强插件**（预制辅助工具集）
+- Superpower、oh-my-opencode、oh-my-codex
+
+### 工具对比表
+
+| 工具 | 类型 | 价格 | AI 模型 | 适用场景 |
+|------|------|------|---------|---------|
+| Claude Code | CLI | 按 Token | Claude | 复杂逻辑 |
+| Codex CLI | CLI | 按 Token | GPT-4 | 快速原型 |
+| OpenCode | CLI | 免费 | 多模型 | 预算有限 |
+| Cursor | IDE | $20/月 | 多模型 | 日常开发 |
+| Kiro | IDE | 免费+付费 | Claude | AWS 项目 |
+| Trae | IDE | 免费+付费 | 豆包 | 中文项目 |
+
+### 各工具详解
+
+**Claude Code**
+- 强大的推理能力，支持长上下文
+- 内置 MCP 支持，Loop 模式
+- 适合复杂逻辑开发、架构设计
+
+**Cursor**
+- 基于 VS Code，AI 优先设计
+- 强大的代码补全，Composer 模式
+- 适合日常开发
+
+**Kiro（AWS）**
+- 深度集成 AWS 服务
+- 支持 Spec 驱动开发
+- 自动化测试生成
+
+**Trae（字节跳动）**
+- 集成豆包大模型
+- 中文支持好
+- 适合中文项目
+
+---
+
+## 第14页：用什么 SDD 框架比较好？
+
+### 原文内容
+**SDD（Spec-Driven Development）框架对比**
+
+Spec = 单一事实来源（SSoT），甚至可以直接生成代码
+
+| 维度        | BMAD                     | Spec Kit               | OpenSpec          | Kiro               |
+| --------- | ------------------------ | ---------------------- | ----------------- | ------------------ |
+| 方法定位      | 企业级 SDD 操作系统             | 工程化 Spec 工作流           | 轻量 Spec 层         | IDE 原生 SDD         |
+| 核心理念      | Spec = 治理体系 + 多 Agent 编排 | Spec = 开发入口 + Git 生命周期 | Spec = 变更单元（持续演化） | Spec = 可执行源（代码与测试） |
+| Spec 生命周期 | 全生命周期                    | 与分支绑定（短生命周期）           | 长期存在（持续演化）        | 持续驱动               |
+| Spec 粒度   | 大（系统/模块级）                | 中（Feature级）            | 小（变更/Patch级）      | 中（Feature+行为）      |
+| 可执行能力     | 通过流程驱动                   | 驱动开发流程                 | 类 Prompt          | 可生成代码+测试并自动校验      |
+| 流程控制      | 强（阶段+审批+Agent）           | 中（Plan→Spec→Tasks）     | 弱（自由演化）           | 强（闭环）              |
+| 自动验证      | 无                        | 无                      | 弱                 | 强（内建）              |
+| 与代码关系     | 间接                       | 半耦合                    | 弱耦合               | 强耦合                |
+| 适用场景      | 大型系统/多团队                 | 新项目（0→1）               | 存量项目/快速迭代         | 小团队/高自动化           |
+| 失控风险      | 低                        | 中                      | 高                 | 中                  |
+
+### 框架选择指南
+
+| 团队规模 | 项目类型  | 推荐框架     |
+| ---- | ----- | -------- |
+| 大型团队 | 企业级项目 | BMAD     |
+| 中型团队 | 新项目   | Spec Kit |
+| 小型团队 | 存量项目  | OpenSpec |
+| 个人开发 | 快速迭代  | Kiro     |
+
+---
+
+## 第15页：一个新星：Superpower
+
+### 原文内容
+- 提供了一些内置的 skills
+- 方便开箱即用
+- 缺点是不太方便精细调整
+
+### 深入解读
+- 为 AI 编程工具提供增强功能的插件集合
+- 内置 Skills：预制的常用能力
+- 优势：快速上手、功能丰富、社区支持
+- 劣势：不够灵活、黑盒、依赖性强
+- 适合快速原型和学习，不适合深度定制

AI工程/团队级AI_Coding简明手册_逐页研究/02_开发实现续_第16-19页.md

@@ -0,0 +1,692 @@
+# 第16-19页：开发实现续篇（技术规格 + 打样 + 多任务 + 核心Loop）
+
+> 章节：02 开发实现（续）
+> 核心问题：技术规格如何编写？如何让 AI 抄作业？如何多任务同步开发？核心 Loop 如何运转？
+
+---
+
+## 第16页：技术规格如何编写？
+
+### 原文内容
+**技术规格的5个模块**（DSL 驱动）：
+
+| 模块 | 表达标准 | 格式 | 产出内容 | 约束/规范 |
+|------|---------|------|---------|----------|
+| **领域模型** | PlantUML/Smart Domain | .puml | 实体、属性、关系（ER/类图） | 必须表达实体关系；字段需与数据库一致；标注聚合关系 |
+| **数据库** | SQL DDL/DBML/Flyway 脚本 | .sql | 表结构、索引、约束 | 必须可执行；包含索引和外键；字段与领域模型一致 |
+| **API** | OpenAPI 3.x | .yaml/.json | 接口定义、请求/响应结构 | 必须定义 schema；禁止只写接口说明；字段与模型一致 |
+| **时序图** | PlantUML | .puml | 调用流程、系统交互 | 必须反映真实调用链；建议包含异常分支（alt） |
+| **专题设计** | Markdown | .md | 架构策略（权限/事务/缓存等） | 只写"策略与规则"，不重复 API/DDL；强调设计决策 |
+
+### 深入解读
+
+**为什么用 DSL？**
+- **可执行**：DDL 可以直接运行，OpenAPI 可以生成代码
+- **AI 友好**：LLM 对 DSL 的理解比自然语言更精确
+- **一致性保证**：DSL 有语法规则，不容易产生歧义
+
+**领域模型详解**
+
+**PlantUML 示例**：
+```plantuml
+@startuml
+entity User {
+  * id : Long <<PK>>
+  --
+  * username : String(50)
+  * email : String(100)
+  * role_id : Long <<FK>>
+}
+
+entity Role {
+  * id : Long <<PK>>
+  --
+  * name : String(20)
+}
+
+User }o--|| Role : "拥有"
+note right of User : 聚合根
+@enduml
+```
+
+**约束要求**：
+- 必须表达实体关系（1:1, 1:N, M:N）
+- 字段需与数据库一致（类型、长度、默认值）
+- 标注聚合关系（哪些是聚合根）
+
+**数据库设计详解**
+
+**SQL DDL 示例**：
+```sql
+-- Flyway migration: V1__create_users_table.sql
+CREATE TABLE users (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    username VARCHAR(50) NOT NULL UNIQUE,
+    email VARCHAR(100) NOT NULL UNIQUE,
+    password VARCHAR(255) NOT NULL,
+    role_id BIGINT NOT NULL,
+    status TINYINT(1) DEFAULT 1,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    INDEX idx_username (username),
+    INDEX idx_email (email),
+    CONSTRAINT fk_user_role FOREIGN KEY (role_id) REFERENCES roles(id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+**必须可执行**：
+- DDL 必须可以直接在数据库中运行
+- 使用 Flyway/Liquibase 管理版本
+- 包含索引（查询性能）和外键（数据完整性）
+
+**API 设计详解**
+
+**OpenAPI 3.x 示例**：
+```yaml
+openapi: 3.0.3
+info:
+  title: User API
+  version: 1.0.0
+paths:
+  /api/v1/users:
+    post:
+      summary: 创建用户
+      tags: [User]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+      responses:
+        '201':
+          description: 创建成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '400':
+          description: 参数错误
+components:
+  schemas:
+    CreateUserRequest:
+      type: object
+      required: [username, email, password]
+      properties:
+        username:
+          type: string
+          minLength: 3
+          maxLength: 50
+          description: 登录用户名，唯一
+        email:
+          type: string
+          format: email
+          description: 电子邮箱，唯一
+        password:
+          type: string
+          minLength: 8
+          description: 密码，≥8位含大小写
+    UserResponse:
+      type: object
+      properties:
+        id:
+          type: integer
+          format: int64
+        username:
+          type: string
+        email:
+          type: string
+        role:
+          type: string
+          enum: [admin, user]
+        status:
+          type: boolean
+```
+
+**约束要求**：
+- 必须定义 schema（请求和响应的结构）
+- 禁止只写接口说明（"返回用户列表"这种描述不够）
+- 字段与领域模型一致（类型、名称、约束）
+
+**时序图详解**
+
+**PlantUML 时序图示例**：
+```plantuml
+@startuml
+actor User
+participant "UserController" as C
+participant "UserService" as S
+participant "UserRepository" as R
+database "MySQL" as DB
+
+User -> C: POST /api/v1/users
+C -> C: 参数校验
+C -> S: createUser(CreateUserRequest)
+S -> S: 业务规则校验
+S -> R: save(User)
+R -> DB: INSERT INTO users ...
+DB --> R: 返回结果
+R --> S: 返回 User
+S --> C: 返回 UserResponse
+C --> User: 201 Created
+
+alt 用户名已存在
+  S --> C: throw DuplicateException
+  C --> User: 409 Conflict
+end
+@enduml
+```
+
+**约束要求**：
+- 必须反映真实调用链
+- 建议包含异常分支（alt）
+- 标注关键步骤（参数校验、业务规则校验）
+
+**专题设计详解**
+
+**专题设计示例**：
+```markdown
+# 权限设计方案
+
+## 策略
+- 使用 RBAC（基于角色的访问控制）
+- 权限注解：@RequirePermission("user:create")
+- 默认拒绝所有未授权的请求
+
+## 规则
+1. 管理员角色拥有所有权限
+2. 普通用户只能操作自己的数据
+3. 敏感操作需要二次确认
+
+## 设计决策
+- 选择 RBAC 而非 ABAC：业务场景简单，角色固定
+- 权限存储在 Redis：减少数据库查询
+- 权限变更实时生效：通过 Redis Pub/Sub 通知
+```
+
+**约束要求**：
+- 只写"策略与规则"
+- 不重复 API/DDL（避免信息冗余）
+- 强调设计决策（为什么选择这个方案）
+
+### 实践建议
+- 使用 DSL：统一技术规格的表示方式
+- 保持一致性：领域模型、数据库、API 要一致
+- AI 辅助生成：让 AI 根据规格生成代码
+- 版本控制：技术规格纳入 Git 管理
+
+---
+
+## 第17页：打样工程：如何让 AI 抄作业？
+
+### 原文内容
+**参考代码**：https://github.com/domain-driven-design/ddd-microservices
+
+**原则**：
+1. 约定大于配置
+2. 编排逻辑和原子能力分离
+3. 操作者和被操作对象分离
+
+**常见 CQRUD 操作的工序**：
+
+**1. 简单 CRUD**：
+```
+Controller + Command → AppService → Repository → Response 对象
+```
+
+**2. 复杂或有复用逻辑的 CRUD**：
+```
+Controller + Command → AppService → DomainService → Repository → Response 对象
+```
+
+**3. 复杂的查询操作**：
+```
+Controller + Query 对象 → AppService → QueryPO（或复用 PO）→ Response 对象
+```
+
+### 深入解读
+
+**什么是打样工程？**
+- 定义：提供代码模版和示例，让 AI 参考生成代码
+- 目的：保证代码风格统一、质量稳定
+- 核心理念：让 AI "抄作业"，而不是自由发挥
+
+**为什么需要打样工程？**
+- AI 生成的代码质量不稳定
+- 不同 AI 工具生成的代码风格不同
+- AI 可能不知道项目的最佳实践
+
+**打样工程的优势**：
+1. 提高代码质量：基于模版生成，质量有保障
+2. 统一代码风格：所有代码遵循相同的风格
+3. 减少 Review 成本：代码符合规范，Review 更快
+4. 知识沉淀：最佳实践沉淀在模版中
+
+**三层架构详解**
+
+**Controller 层**：
+- 职责：接收请求、参数校验、调用 Service
+- 输入：Command/Query 对象
+- 输出：Response 对象
+- 不包含业务逻辑
+
+**Service 层**：
+- 职责：编排业务逻辑、调用 DomainService/Repository
+- AppService：应用服务，编排逻辑
+- DomainService：领域服务，复杂业务逻辑
+- Repository：数据访问
+
+**Repository 层**：
+- 职责：数据持久化
+- 输入：实体对象
+- 输出：实体对象或 PO（Persistent Object）
+
+**工序详解**
+
+**简单 CRUD（无复用逻辑）**：
+```java
+// Controller
+@PostMapping("/users")
+public Response<UserResponse> createUser(@Valid @RequestBody CreateUserCommand cmd) {
+    return Response.success(userAppService.create(cmd));
+}
+
+// AppService
+public UserResponse create(CreateUserCommand cmd) {
+    User user = userRepository.save(User.from(cmd));
+    return UserResponse.from(user);
+}
+
+// Repository
+public User save(User user) {
+    userMapper.insert(user);
+    return user;
+}
+```
+
+**复杂 CRUD（有复用逻辑）**：
+```java
+// AppService - 编排逻辑
+public UserResponse create(CreateUserCommand cmd) {
+    // 1. 校验用户名唯一
+    domainService.checkUsernameUnique(cmd.getUsername());
+    // 2. 加密密码
+    String encryptedPassword = domainService.encryptPassword(cmd.getPassword());
+    // 3. 保存用户
+    User user = User.from(cmd, encryptedPassword);
+    userRepository.save(user);
+    // 4. 发送欢迎邮件
+    domainService.sendWelcomeEmail(user);
+    return UserResponse.from(user);
+}
+
+// DomainService - 原子能力
+public void checkUsernameUnique(String username) {
+    if (userRepository.existsByUsername(username)) {
+        throw new BusinessException("用户名已存在");
+    }
+}
+```
+
+**复杂查询**：
+```java
+// Controller
+@GetMapping("/users")
+public Response<Page<UserResponse>> listUsers(@Valid UserQuery query) {
+    return Response.success(userAppService.list(query));
+}
+
+// AppService
+public Page<UserResponse> list(UserQuery query) {
+    Page<UserPO> page = userRepository.findByQuery(query);
+    return page.map(UserResponse::from);
+}
+
+// Repository
+public Page<UserPO> findByQuery(UserQuery query) {
+    // 构建查询条件
+    // 执行分页查询
+    // 返回分页结果
+}
+```
+
+### 实践建议
+- 建立打样工程：提供标准的代码模版
+- 分层清晰：Controller、Service、Repository 职责明确
+- 工序标准化：简单 CRUD、复杂 CRUD、复杂查询各有标准
+- AI 参考打样：让 AI 根据打样工程生成代码
+
+---
+
+## 第18页：如何多任务同步开发？
+
+### 原文内容
+使用 git 的 Worktree 功能同时把一个仓库的多个分支映射到不同文件夹。Claude Code、Codex、Cursor 等已经自动支持使用 subagent 创建 Worktree，加速开发。
+
+```bash
+# 基于已有分支创建
+git worktree add ../feature-login feature/login
+
+# 创建新分支 + 工作区（最常用）
+git worktree add -b feature-payment ../feature-payment
+
+# 查看所有 worktree
+git worktree list
+
+# 删除工作区
+git worktree remove ../feature-login
+```
+
+### 深入解读
+
+**什么是 Git Worktree？**
+- 定义：Git 的一个功能，允许你从同一个仓库检出多个工作目录
+- 每个工作目录都是一个独立的分支
+- 共享同一个 .git 目录（节省磁盘空间）
+
+**为什么需要 Worktree？**
+- AI 编程时，经常需要同时开发多个功能
+- 传统方式：切换分支，容易丢失上下文
+- Worktree：每个功能在独立的目录，互不干扰
+
+**Worktree 的优势**：
+1. 并行开发：多个 AI 实例可以同时工作在不同分支
+2. 上下文隔离：每个功能的上下文独立，不会混淆
+3. 快速切换：不需要 `git checkout`，直接切换目录
+4. 节省空间：共享 .git 目录
+
+**使用场景**
+
+**场景1：多 AI 实例并行开发**
+```bash
+# 主工作区：开发功能 A
+cd /project/feature-a
+claude-code # 启动 Claude Code
+
+# 新开终端：开发功能 B
+cd /project/feature-b
+claude-code # 启动另一个 Claude Code 实例
+
+# 再开终端：开发功能 C
+cd /project/feature-c
+claude-code # 启动第三个 Claude Code 实例
+```
+
+**场景2：AI + 人工并行开发**
+```bash
+# AI 在 feature-a 开发
+cd /project/feature-a
+claude-code
+
+# 人工在 main 分支修复紧急 bug
+cd /project/main
+# 手动修复 bug
+```
+
+**场景3：Code Review 时继续开发**
+```bash
+# 主工作区：feature-a 提交 PR，等待 review
+# 新开工作区：继续开发 feature-b
+git worktree add -b feature-b ../feature-b
+cd ../feature-b
+claude-code
+```
+
+**Worktree 管理**
+
+**列出所有工作区**：
+```bash
+git worktree list
+# 输出：
+# /project/main              abc1234 [main]
+# /project/feature-a         def5678 [feature-a]
+# /project/feature-b         ghi9012 [feature-b]
+```
+
+**清理工作区**：
+```bash
+# 删除工作区（会自动删除目录）
+git worktree remove ../feature-a
+
+# 强制删除（即使有未提交的更改）
+git worktree remove --force ../feature-a
+
+# 清理已删除的工作区记录
+git worktree prune
+```
+
+**AI 工具自动支持**：
+- Claude Code：自动创建 Worktree 进行并行开发
+- Codex CLI：支持在独立工作区运行
+- Cursor：可以在多个窗口打开不同 Worktree
+
+### 实践建议
+- 使用 Worktree 并行开发：提高开发效率
+- 命名规范：工作区目录名与分支名一致
+- 及时清理：完成的功能及时删除 Worktree
+- AI 工具支持：利用 AI 工具的自动 Worktree 功能
+
+---
+
+## 第19页：完整的核心 Loop 过程（研发自测）
+
+### 原文内容
+**核心理念**：通过 TDD/浏览器调试（前端），AI 自治运行
+
+**Loop 流程图**：
+```
+开始进入循环
+    ↓
+[Chat] 进入 Plan 模式
+    ↓
+装载需求规格，给出指令进行 Plan
+    ↓
+[Chat] 符合要求，退出 Plan 模式，开始执行？
+    ↓ 是
+[模型] 读取 Plan
+    ↓
+创建 API 测试，实现代码
+    ↓
+[模型] 运行测试/浏览器调试，是否成功？
+    ↓ 否
+重复多次 / 白天持续很久 / 夜间
+    ↓ 是
+[模型] 退出循环
+    ↓
+（给予 ByPass 权限）
+```
+
+**核心思想**：
+1. Plan 阶段尽可能锁定上下文到 Plan 中，关闭所有的开放性问题
+2. Plan 中记录实现状态，让任务可以分批完成或者重试
+3. 需要给出确定性的验收方式：例如通过所有的 API 测试，让 AI 能建立自我修复标准
+
+**Loop 规则（API 为例，放到 AGENTS.md 作为开发流程要求）**：
+1. **Plan 等待确认**：在 docs/plans 下根据模版创建 Plan
+2. **编写 API 测试**：根据 Plan 实现 API 测试，运行成功并断言失败
+3. **编写实现**：编写单元测试 + 实现代码，通过编译
+4. **运行 API 测试**：运行测试，并修复失败的测试和其他错误
+
+### 深入解读
+
+**什么是核心 Loop？**
+- 定义：AI 自治运行的开发循环
+- 目标：通过 TDD 驱动，AI 自动实现需求并修复问题
+- 特点：Plan 阶段人机协作，执行阶段 AI 自治
+
+**Loop 的三个阶段**
+
+**阶段1：Plan（规划）**
+- 输入：需求规格、技术规格
+- 输出：实现方案、任务列表
+- 关键：关闭所有开放性问题
+- 人工介入：确认 Plan 是否合理
+
+**阶段2：执行（Implementation）**
+- 输入：Plan
+- 输出：API 测试、实现代码
+- 关键：按照 Plan 逐步实现
+- AI 自治：无需人工介入
+
+**阶段3：验证（Verification）**
+- 输入：API 测试、实现代码
+- 输出：测试结果、修复建议
+- 关键：所有测试通过
+- AI 自治：自动运行测试，自动修复
+
+**Plan 模版示例**：
+```markdown
+# Plan: 实现用户注册功能
+
+## 目标
+实现用户注册 API，支持邮箱验证
+
+## 任务列表
+- [ ] 1. 创建数据库表 users
+- [ ] 2. 实现 POST /api/v1/users API
+- [ ] 3. 实现邮箱验证逻辑
+- [ ] 4. 编写单元测试
+- [ ] 5. 编写 API 测试
+
+## 实现方案
+1. 使用 Flyway 创建 users 表
+2. Controller 接收 CreateUserCommand
+3. AppService 调用 UserRepository 保存
+4. 发送验证邮件（使用 JavaMail）
+
+## 验收标准
+- 所有单元测试通过
+- 所有 API 测试通过
+- 代码符合阿里巴巴 Java 开发手册
+
+## 状态
+- 开始时间：2026-06-20 10:00
+- 预计完成：2026-06-20 12:00
+- 实际完成：待更新
+```
+
+**TDD 驱动详解**
+
+**步骤1：编写 API 测试**
+```java
+@Test
+public void testCreateUser() {
+    CreateUserRequest request = new CreateUserRequest();
+    request.setUsername("testuser");
+    request.setEmail("test@example.com");
+    request.setPassword("Password123");
+    
+    Response<UserResponse> response = userClient.create(request);
+    
+    assertEquals(201, response.getCode());
+    assertNotNull(response.getData().getId());
+    assertEquals("testuser", response.getData().getUsername());
+}
+
+@Test
+public void testCreateUser_DuplicateUsername() {
+    // 先创建一个用户
+    CreateUserRequest request1 = new CreateUserRequest();
+    request1.setUsername("testuser");
+    request1.setEmail("test1@example.com");
+    request1.setPassword("Password123");
+    userClient.create(request1);
+    
+    // 再创建一个同名用户
+    CreateUserRequest request2 = new CreateUserRequest();
+    request2.setUsername("testuser");
+    request2.setEmail("test2@example.com");
+    request2.setPassword("Password123");
+    
+    Response<UserResponse> response = userClient.create(request2);
+    
+    assertEquals(409, response.getCode());
+    assertEquals("用户名已存在", response.getMessage());
+}
+```
+
+**步骤2：运行测试（断言失败）**
+```bash
+mvn test -Dtest=UserApiTest
+# 预期：测试失败（因为没有实现）
+```
+
+**步骤3：编写实现代码**
+```java
+// Controller
+@PostMapping("/users")
+public Response<UserResponse> createUser(@Valid @RequestBody CreateUserRequest request) {
+    return Response.success(userAppService.create(request));
+}
+
+// AppService
+public UserResponse create(CreateUserRequest request) {
+    // 校验用户名唯一
+    if (userRepository.existsByUsername(request.getUsername())) {
+        throw new BusinessException(409, "用户名已存在");
+    }
+    // 加密密码
+    String encryptedPassword = passwordEncoder.encode(request.getPassword());
+    // 保存用户
+    User user = User.from(request, encryptedPassword);
+    userRepository.save(user);
+    // 发送验证邮件
+    emailService.sendVerificationEmail(user);
+    return UserResponse.from(user);
+}
+```
+
+**步骤4：运行测试（通过）**
+```bash
+mvn test -Dtest=UserApiTest
+# 预期：所有测试通过
+```
+
+**ByPass 权限**
+- 定义：AI 在某些情况下可以跳过某些步骤
+- 场景：
+  - 测试环境不可用
+  - 第三方服务不可用
+  - 紧急修复
+- 控制：在 AGENTS.md 中定义 ByPass 规则
+
+**Loop 的退出条件**
+1. 所有 API 测试通过
+2. 所有单元测试通过
+3. 代码符合规范（Lint 通过）
+4. 没有编译错误
+
+### 实践建议
+- Plan 阶段充分沟通：关闭所有开放性问题
+- TDD 驱动：先写测试再写代码
+- AI 自治运行：执行阶段无需人工介入
+- 记录实现状态：方便复盘和优化
+- ByPass 权限控制：紧急情况可以跳过某些步骤
+
+---
+
+## 本章小结
+
+**开发实现的核心要点**：
+1. 让 AI 听话：规则、规格、技能三要素
+2. 构建上下文体系：区分过程方案和事实方案
+3. 调用外部工具：MCP、Skills、CLI
+4. 选择合适的工具：命令行类、AI IDE、增强插件
+5. SDD 框架：BMAD、Spec Kit、OpenSpec、Kiro
+6. 技术规格 DSL 驱动：领域模型、数据库、API、时序图、专题设计
+7. 打样工程：让 AI 抄作业
+8. 多任务同步开发：Git Worktree
+9. 核心 Loop：Plan → TDD → 验证
+
+**关键工具**：
+- Claude Code、Cursor、Kiro
+- MCP Server、Skills
+- PlantUML、OpenAPI
+- Git Worktree
+
+**最佳实践**：
+- AGENTS.md 作为宪法
+- 区分 Plans（过程）和 Designs（事实）
+- 使用 DSL 编写技术规格
+- 建立打样工程
+- TDD 驱动开发

AI工程/团队级AI_Coding简明手册_逐页研究/04_Agent_as_Code_第26-30页.md

@@ -0,0 +1,491 @@
+# 第26-30页：Agent as Code + 附录
+
+> 章节：04 Agent as Code + 附录
+> 核心问题：如何组织 AI 工程文件？如何让多个 AI 工具协同？
+
+---
+
+## 第26页：分隔页（04 Agent as Code）
+
+### 原文内容
+章节分隔页，标志进入"Agent as Code"部分
+
+### 研究要点
+- 这是4个核心问题中的第4个
+- Agent as Code 是整个体系的基础设施
+- 核心目标：让 AI 协作文件可版本化、可复用、可共享
+
+---
+
+## 第27页：AI 工程文件管理
+
+### 原文内容
+**核心思路**：使用 AGENTS.md 构建引用关系，让 Claude/OpenCode 等工具支持相关 Harness 文件
+
+**目录结构**：
+```
+AGENTS.md          ← 宪法
+docs/
+├── standards/     ← 标准规格
+├── features/      ← 需求规格
+├── plans/         ← 计划规格
+├── designs/       ← 设计规格
+└── others/        ← 其他
+skills/            ← AI 技能
+mcp/               ← MCP 配置
+```
+
+**工具配置**：
+- `.claude/` - Claude Code 配置
+- `.opencode/` - OpenCode 配置
+- `.cursor/` - Cursor 配置
+
+**实现方式**：通过软链接（symlink）让各工具读取同一份 AGENTS.md
+
+### 深入解读
+
+**什么是 Agent as Code？**
+- 定义：将 AI 协作的所有文件以代码的方式管理
+- 目标：可版本化、可复用、可共享
+- 核心理念：AI 的行为由代码（配置文件）决定
+
+**为什么需要 Agent as Code？**
+- AI 工具配置分散：每个工具有自己的配置文件
+- 难以复用：不同项目需要重复配置
+- 难以协作：团队成员无法共享 AI 配置
+- 难以追溯：AI 行为变更没有历史记录
+
+**AGENTS.md 的作用**
+- **宪法级约束**：定义 AI 的基本行为规则
+- **统一入口**：所有 AI 工具都从这个文件开始
+- **引用枢纽**：通过引用关系组织其他文件
+
+**AGENTS.md 示例**：
+```markdown
+# 项目信息
+- 项目名称：电商平台
+- 技术栈：Java 17, Spring Boot 3.x, React 18
+- 代码规范：阿里巴巴 Java 开发手册
+
+# AI 行为规则
+1. 生成代码必须符合代码规范
+2. 数据库表必须包含 created_at, updated_at 字段
+3. API 接口必须使用 RESTful 风格
+4. 敏感数据必须加密存储
+
+# 目录结构
+- src/main/java/com/example/project/controller
+- src/main/java/com/example/project/service
+- src/main/java/com/example/project/repository
+
+# 引用文件
+- 代码规范：./docs/standards/coding-style.md
+- API 规范：./docs/standards/api-style.md
+- 数据库规范：./docs/standards/db-style.md
+```
+
+**软链接实现**
+
+**Linux/Mac**：
+```bash
+# 创建软链接
+ln -s ../AGENTS.md .claude/AGENTS.md
+ln -s ../AGENTS.md .opencode/AGENTS.md
+ln -s ../AGENTS.md .cursor/AGENTS.md
+```
+
+**Windows**：
+```cmd
+# 创建软链接（需要管理员权限）
+mklink .claude\AGENTS.md ..\AGENTS.md
+mklink .opencode\AGENTS.md ..\AGENTS.md
+mklink .cursor\AGENTS.md ..\AGENTS.md
+```
+
+**Git 管理**：
+```bash
+# 添加到 Git
+git add AGENTS.md
+git add .claude/AGENTS.md
+git add .opencode/AGENTS.md
+git add .cursor/AGENTS.md
+
+# 提交
+git commit -m "feat: add AGENTS.md for AI collaboration"
+```
+
+**Skills 目录**
+- 定义：可复用的 AI 能力单元
+- 组成：提示词、脚本、文档
+- 示例：
+```
+skills/
+├── commit-push/
+│   ├── SKILL.md
+│   └── commit.sh
+├── deploy/
+│   ├── SKILL.md
+│   └── deploy.sh
+└── test/
+    ├── SKILL.md
+    └── test.sh
+```
+
+**MCP 配置**
+- 定义：Model Context Protocol 配置
+- 作用：让 AI 访问外部工具
+- 示例：
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "node",
+      "args": ["mcp-server-sqlite"]
+    },
+    "filesystem": {
+      "command": "node",
+      "args": ["mcp-server-filesystem", "/path/to/dir"]
+    }
+  }
+}
+```
+
+### 实践建议
+- **使用 AGENTS.md 作为统一入口**：所有 AI 工具从这个文件开始
+- **使用软链接**：让多个工具共享同一份配置
+- **纳入 Git 管理**：配置可版本化、可追溯
+- **建立 Skills 库**：沉淀常用的 AI 能力
+- **使用 MCP**：让 AI 访问外部工具
+
+---
+
+## 第28页：分隔页（附录&参考资料）
+
+### 原文内容
+章节分隔页，标志进入"附录&参考资料"部分
+
+### 研究要点
+- 提供进一步学习的资源
+- 包含实践心得和参考资料
+
+---
+
+## 第29页：关于 AI 编程实践的心得
+
+### 原文内容
+**两条核心心得**：
+
+1. **放弃"开箱即用"的框架**
+   - 每个项目需要构建自己 Harness 工具和文档
+   - 没有放之四海而皆准的解决方案
+   - 需要根据项目特点定制
+
+2. **"少量取用，大量实践"是更好的策略**
+   - 不要一开始就引入所有概念
+   - 先实践核心概念，再逐步扩展
+   - 实践出真知
+
+### 深入解读
+
+**为什么没有"开箱即用"的框架？**
+
+**原因1：项目差异大**
+- 技术栈不同：Java vs Python vs JavaScript
+- 团队规模不同：个人 vs 小团队 vs 大团队
+- 业务复杂度不同：简单 CRUD vs 复杂业务逻辑
+- 合规要求不同：内部项目 vs 金融项目 vs 医疗项目
+
+**原因2：AI 能力在快速演进**
+- 模型能力不断提升
+- 工具生态快速变化
+- 最佳实践还在形成中
+- 昨天的最佳实践可能今天已过时
+
+**原因3：团队文化差异**
+- 有的团队喜欢严格规范
+- 有的团队喜欢灵活自由
+- 有的团队重视文档
+- 有的团队重视代码
+
+**如何构建自己的 Harness？**
+
+**步骤1：从 AGENTS.md 开始**
+- 定义项目基本信息
+- 定义 AI 行为规则
+- 定义目录结构
+
+**步骤2：建立文档体系**
+- docs/standards/ - 标准规范
+- docs/features/ - 需求规格
+- docs/designs/ - 设计规格
+- docs/plans/ - 计划规格
+
+**步骤3：开发常用 Skills**
+- commit-push - 提交和推送代码
+- deploy - 部署到环境
+- test - 运行测试
+
+**步骤4：配置 MCP**
+- 数据库访问
+- 文件系统访问
+- 外部 API 访问
+
+**"少量取用，大量实践"的具体做法**
+
+**第一阶段：基础配置（1-2周）**
+- 建立 AGENTS.md
+- 建立基本文档结构
+- 配置一个 AI 工具（如 Claude Code）
+
+**第二阶段：核心实践（2-4周）**
+- 使用 AI 生成代码
+- 使用 AI 进行 Code Review
+- 使用 AI 编写测试
+
+**第三阶段：扩展应用（1-2月）**
+- 引入更多 AI 工具
+- 开发更多 Skills
+- 配置更多 MCP
+
+**第四阶段：持续优化（持续）**
+- 根据实践反馈优化配置
+- 沉淀最佳实践
+- 分享给团队
+
+### 实践建议
+- **不要追求完美**：先跑起来，再优化
+- **小步快跑**：每次只引入一个新概念
+- **记录实践**：记录什么有效，什么无效
+- **分享经验**：与团队分享实践经验
+- **持续学习**：关注 AI 编程领域的最新进展
+
+---
+
+## 第30页：参考资料
+
+### 原文内容
+**参考资料列表**：
+
+1. [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
+2. [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
+3. [Anthropic: Harness Design for Long-running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+4. [从 Rule、Spec 到 Harness：AI Coding 的渐进式建设路径](https://mp.weixin.qq.com/s/UCh2bPzMZjNBMBCCJysuNw)
+5. [让 AI 乖乖听话的几个 Rules](https://mp.weixin.qq.com/s/FXNzk_y2Z2h8BVe62uEn_A)
+6. [Understanding SDD: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
+7. [harness-engineering-in-ai-coding](https://github.com/2361485765/harness-engineering-in-ai-coding)
+8. [attractor-guided-engineering-template](https://github.com/entropy-cloud/attractor-guided-engineering-template)
+9. [OpenAI: Tools Computer Use](https://developers.openai.com/api/docs/guides/tools-computer-use)
+
+### 深入解读
+
+**资料分类**
+
+**Harness Engineering 理论**：
+1. OpenAI 的文章：介绍 Harness Engineering 的概念和实践
+2. Martin Fowler 的文章：从软件工程角度阐述 Harness
+3. Anthropic 的文章：针对长时间运行应用的 Harness 设计
+
+**AI Coding 实践**：
+4. 微信公众号文章：从 Rule 到 Spec 到 Harness 的渐进式路径
+5. 微信公众号文章：让 AI 听话的 Rules 实践
+
+**SDD 框架**：
+6. Martin Fowler 的文章：对比 Kiro、spec-kit、Tessl 三个 SDD 框架
+
+**开源项目**：
+7. harness-engineering-in-ai-coding：Harness Engineering 实践项目
+8. attractor-guided-engineering-template：引导式工程模版
+
+**官方文档**：
+9. OpenAI 官方文档：Computer Use 工具使用指南
+
+**推荐阅读顺序**
+
+**入门阶段**：
+1. 先读第4、5篇微信公众号文章（中文，易理解）
+2. 再读 OpenAI 的 Harness Engineering 文章
+
+**进阶阶段**：
+3. 读 Martin Fowler 的 Harness Engineering 文章
+4. 读 Anthropic 的 Harness Design 文章
+5. 读 SDD 框架对比文章
+
+**实践阶段**：
+6. 参考开源项目实践
+7. 阅读官方文档
+
+**关键概念解释**
+
+**Harness Engineering**：
+- 定义：为 AI 提供约束和工具的工程实践
+- 目标：让 AI 在受控环境中高效工作
+- 核心：约束体系 + 工具体系
+
+**SDD（Spec-Driven Development）**：
+- 定义：以规格文档为核心的开发方法
+- 核心理念：Spec 是单一事实来源
+- 代表框架：Kiro、spec-kit、OpenSpec、BMAD
+
+**Rule/Spec/Harness 演进**：
+- Rule：约束 AI 行为的规则
+- Spec：结构化的需求描述
+- Harness：完整的约束和工具体系
+
+### 实践建议
+- **循序渐进**：按照推荐阅读顺序学习
+- **理论结合实践**：读完理论后动手实践
+- **关注官方文档**：获取最新信息
+- **参与社区**：关注开源项目和社区讨论
+
+---
+
+## 全文总结
+
+### 核心框架
+
+**团队级 AI Coding 的4个核心问题**：
+1. **需求衔接**：如何编写 AI 能理解的需求？
+2. **开发实现**：如何让 AI 生成高质量代码？
+3. **测试验收**：如何自动化测试 AI 生成的代码？
+4. **Agent as Code**：如何组织 AI 协作文件？
+
+**解决方案概览**：
+
+**需求衔接**：
+- 使用 Markdown 编写需求规格
+- 区分增量需求和存量需求
+- 使用字段清单和业务规则
+- 通过原型图传递 UI 设计
+
+**开发实现**：
+- 规则、规格、技能三要素
+- 构建 AI 上下文体系（AGENTS.md + docs/）
+- 区分过程方案（Plans）和事实方案（Designs）
+- 使用 MCP/Skills/CLI 调用外部工具
+- 选择合适的 AI 编程工具
+- 使用 SDD 框架（BMAD/SpecKit/OpenSpec/Kiro）
+- 使用 DSL 编写技术规格
+- 建立打样工程
+- 使用 Git Worktree 并行开发
+- 核心 Loop：Plan → TDD → 验证
+
+**测试验收**：
+- 分层测试：Lint → Code Review → 单元测试 → API 测试 → E2E 测试
+- AI 操作浏览器：Playwright MCP、Chrome DevTools MCP、Browser Use、Computer Use
+- 生成 E2E 测试：Browser Use 探索 → Playwright 固化 → 截图视觉兜底
+- 超级 Loop：在核心 Loop 基础上增加 E2E 测试验证
+
+**Agent as Code**：
+- 使用 AGENTS.md 作为统一入口
+- 建立文档体系（standards/features/plans/designs）
+- 开发 Skills 库
+- 配置 MCP
+- 使用软链接让多个工具共享配置
+
+### 关键工具
+
+**AI 编程工具**：
+- Claude Code、Cursor、Kiro、Trae、OpenCode、Codex CLI
+
+**SDD 框架**：
+- BMAD、Spec Kit、OpenSpec、Kiro
+
+**测试工具**：
+- Playwright、Browser Use、Karate、RestAssured
+
+**文档工具**：
+- PlantUML、OpenAPI、Markdown
+
+**协作工具**：
+- Git、GitHub、GitLab
+
+### 最佳实践
+
+**需求阶段**：
+- 使用 Markdown 编写需求
+- 区分增量和存量需求
+- 使用字段清单
+- 通过原型图传递 UI
+
+**开发阶段**：
+- 建立 AGENTS.md
+- 区分 Plans 和 Designs
+- 使用 DSL 编写技术规格
+- 建立打样工程
+- TDD 驱动开发
+
+**测试阶段**：
+- 分层测试
+- 先用 Browser Use 探索，再固化到 Playwright
+- 使用稳定的选择器
+- 关键页面截图验证
+
+**协作阶段**：
+- 使用 AGENTS.md 作为统一入口
+- 使用软链接共享配置
+- 纳入 Git 管理
+- 建立 Skills 库
+
+### 学习路径
+
+**入门（1-2周）**：
+1. 理解 AI 编程的5个发展阶段
+2. 建立 AGENTS.md
+3. 使用一个 AI 工具（如 Claude Code）
+4. 实践核心 Loop
+
+**进阶（1-2月）**：
+1. 学习 SDD 框架
+2. 使用 DSL 编写技术规格
+3. 建立打样工程
+4. 实践分层测试
+5. 使用 Playwright 进行 E2E 测试
+
+**高级（持续）**：
+1. 构建完整的 Harness 体系
+2. 开发自定义 Skills
+3. 配置 MCP 访问外部工具
+4. 优化 AI 工作流
+5. 分享实践经验
+
+### 关键洞察
+
+1. **AI 编程不是银弹**：需要工程化的方法来驾驭
+2. **上下文是关键**：AI 需要清晰的上下文才能生成高质量代码
+3. **测试是保障**：自动化测试是 AI 生成代码质量的保障
+4. **实践出真知**：没有放之四海而皆准的方案，需要根据项目特点定制
+5. **持续演进**：AI 能力在快速提升，方法也需要持续演进
+
+---
+
+## 附录：术语表
+
+| 术语 | 英文 | 定义 |
+|------|------|------|
+| AI 编程 | AI Coding | 使用 AI 辅助或自动化进行软件开发 |
+| Harness | Harness | 为 AI 提供约束和工具的工程实践 |
+| SDD | Spec-Driven Development | 以规格文档为核心的开发方法 |
+| MCP | Model Context Protocol | AI 与外部系统通信的标准协议 |
+| AGENTS.md | AGENTS.md | AI 协作的宪法级配置文件 |
+| Plan | Plan | AI 执行任务的规划文档 |
+| Spec | Specification | 结构化的需求描述 |
+| Rule | Rule | 约束 AI 行为的规则 |
+| Skill | Skill | 可复用的 AI 能力单元 |
+| Loop | Loop | AI 自治运行的开发循环 |
+| TDD | Test-Driven Development | 测试驱动开发 |
+| E2E | End-to-End | 端到端测试 |
+| DSL | Domain Specific Language | 领域特定语言 |
+| Worktree | Git Worktree | Git 的多工作区功能 |
+| Browser Use | Browser Use | AI 操作浏览器的框架 |
+| Playwright | Playwright | 浏览器自动化测试框架 |
+| BMAD | Business Model Architecture Design | 企业级 SDD 框架 |
+| OpenSpec | OpenSpec | 轻量级 SDD 框架 |
+| Kiro | Kiro | AWS 推出的 AI IDE 和 SDD 框架 |
+
+---
+
+**文档信息**：
+- 原文：团队级 AI Coding 简明手册 v0.2
+- 研究日期：2026-06-20
+- 研究范围：第1-30页（全文）
+- 归档位置：/obsidian/AI工程/团队级AI_Coding简明手册_逐页研究/