Update from Sync Service

2026-06-22 11:30:51 +08:00
parent eb80b7a8c1
commit 682e3e52df
52 changed files with 10099 additions and 191 deletions
--- a/AI工程/团队级AI_Coding简明手册_逐页研究/00_索引.md
+++ b/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页内容已详细研究并归档，包含：
+- 原文内容提取
+- 深入解读和背景知识
+- 实践建议和工具推荐
+- 代码示例和配置示例
+- 最佳实践清单
+- 学习路径指南