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简明手册v0.2.md
+++ b/AI工程/团队级AI_Coding简明手册v0.2.md
@@ -0,0 +1,323 @@
+# 团队级 AI Coding 简明手册 v0.2
+
+> 来源：系统设计研讨会分享 PPT（2026.06.18），版权归分享人所有
+> 归档日期：2026-06-20
+
+---
+
+## 一、AI 编程思想发展过程
+
+| 阶段 | 特征 | 模式 |
+|------|------|------|
+| **原始阶段** | 基于本能的 AI 编程，手动复制代码或通过问答交互 | 半自动，有人值守 |
+| **Rule 约束** | 经验规则显化（如 RIPER-5），通过持续对话输入需求 | 半自动 |
+| **规格驱动** | 需求结构化表达，基于规格流转（如 OpenSpec），文件进文件出 | 全自动过渡 |
+| **Loop Engineering** | 可反馈闭环：AI 根据验收规则自动循环 + 测试套件 | 全自动 |
+| **Harness 驾驭工程** | 纳入工程治理体系，提供约束体系 + 外部接口 | 全自动，Plan 后无人值守 |
+
+> 每一次思想的变更是对前者的重新表述而非推翻
+
+---
+
+## 二、AI 赋能软件开发实现地图
+
+```
+需求分析 → 需求文档/原型图 → 技术方案设计 → 代码框架+打样工程
+    ↓            ↓                ↓                ↓
+  人+AI        人+AI             人+AI            人+AI
+    ↓            ↓                ↓                ↓
+AI代码编写 → 单元测试/调试 → E2E测试 → Code Review → 提测部署
+    ↓            ↓              ↓           ↓           ↓
+  机           机+人           机+人        机+人        机+人
+```
+
+**核心 Loop**：研发自测阶段，AI 自治运行
+**全流程超级 Loop**：从需求到部署的完整闭环
+
+---
+
+## 三、四大核心问题
+
+### 01 需求衔接
+- 如何编写 AI 能理解的需求？
+- 使用什么格式？如何组织需求规格？
+- 如何传递原型图？需求模版长什么样？
+
+### 02 开发实现
+- 如何让 AI 理解上下文且按要求执行？
+- 如何调用外部工具？生成一致的代码？
+- 如何多任务同步开发？
+
+### 03 测试验收
+- AI 编程需要什么测试策略？
+- 如何让 AI 操作浏览器？
+- 如何管理测试用例？
+
+### 04 Agent as Code
+- 如何把和 AI 协作的文件在代码仓库中合理组织？
+- 构建 AI 更友好的环境
+
+---
+
+## 四、需求规格编写
+
+### 关键要素
+- **模块切分**（增量/存量）
+- **字段清单**
+- **原型链接**
+- **业务规则**
+
+### 编写原则
+1. 先写业务背景，再切模块。**一个模块 = 一个文档**
+2. 分解为增量需求和存量需求：
+   - **增量需求** — 全新功能，需新建模块
+   - **存量修改** — 对已有功能做变更
+3. 字段定义需完整：类型、必填、默认值、描述、校验规则、UI展示、数据来源
+4. 业务规则条目化 + 正交分解，每条规则独立可测
+
+> **Tips**: BA 也应该工作在代码仓库中，让 AI 基于当前系统事实构建新需求
+
+### 原型图设计
+- **设计工具输出**：Figma/Stitch URL 嵌入需求文档
+- **HTML+CSS 输出**：可交互原型提交到代码仓库
+- **Design.md**：约束 AI 生成的前端风格，确保与项目组件库一致
+
+---
+
+## 五、开发实现
+
+### 让 AI 听话的三要素
+
+| 要素 | 说明 | 示例 |
+|------|------|------|
+| **规则 Rules** | 约束 AI 行为边界 | Java 代码风格、命名规范 |
+| **规格 Specification** | 结构化需求，甚至用 DSL 描述 | 用户故事 + 验收标准 |
+| **技能 Skill** | 打包提示词/脚本/模版扩展能力 | Commit & Push Skill |
+
+### 构建 AI 上下文体系（详见下方重点章节）
+
+### 让 AI 调用外部工具的三种方式
+1. **CLI Commands** — 最直接，AI 生成命令并执行
+2. **MCP** — 标准协议，统一接入数据库/API/文件系统
+3. **Skills** — 脚本封装，触发词驱动
+
+### AI 编程工具选择
+- **命令行类**：Claude Code、Codex CLI、OpenCode
+- **AI IDE**：Cursor、Kiro、Trae
+- **增强插件**：Superpower、oh-my-opencode、oh-my-codex
+
+### SDD 框架对比
+
+| 维度 | BMAD | Spec Kit | OpenSpec | Kiro |
+|------|------|----------|----------|------|
+| 定位 | 企业级 SDD 操作系统 | 工程化 Spec 工作流 | 轻量 Spec 层 | IDE 原生 SDD |
+| Spec 粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
+| 自动验证 | 无 | 无 | 弱 | 强（内建） |
+| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |
+
+### 技术规格编写（DSL 驱动）
+
+| 模块 | 标准 | 格式 | 约束 |
+|------|------|------|------|
+| 领域模型 | PlantUML/Smart Domain | .puml | 必须表达实体关系 |
+| 数据库 | SQL DDL/DBML | .sql | 必须可执行 |
+| API | OpenAPI 3.x | .yaml/.json | 必须定义 schema |
+| 时序图 | PlantUML | .puml | 必须反映真实调用链 |
+| 专题设计 | Markdown | .md | 只写策略与规则 |
+
+### 打样工程：让 AI 抄作业
+- 原则：约定大于配置、编排逻辑和原子能力分离、操作者和被操作对象分离
+- 简单 CRUD：Controller + Command → AppService → Repository → Response
+- 复杂 CRUD：Controller + Command → AppService → DomainService → Repository → Response
+- 复杂查询：Controller + Query → AppService → QueryPO → Response
+
+### 多任务同步开发
+使用 `git worktree` 同时把多个分支映射到不同文件夹：
+```bash
+git worktree add -b feature-payment ../feature-payment
+```
+
+---
+
+## 六、⭐ 过程方案 vs 事实方案（重点）
+
+### 核心理念
+
+> 使用完整的文档来描述上下文和约束体系，**区分过程方案和事实方案，减少维护成本**。
+
+### 文档分层体系
+
+```
+AGENTS.md          ← 宪法级约束
+docs/
+├── standards/     ← 标准规格（架构/命名/API/安全规范）
+├── features/      ← 需求规格（产品/BA维护）
+├── designs/       ← 设计规格（DB/表等 Source of Truth）  ⬅ 事实方案
+├── plans/         ← 计划规格（每轮任务实现方案）          ⬅ 过程方案
+└── others/        ← 架构决策、Release、测试用例等
+```
+
+### 过程方案（Plans）
+
+**定义**：每一轮任务的实现方案、Tasking、工作状态。
+
+**特征**：
+- **临时性**：每次创建新文件，用完即弃
+- **不维护**：细微修改不再更新旧文件
+- **可追溯**：保留历史决策轨迹，方便复盘
+- **增量追加**：`追加: 每次创建一个新的文件`
+
+**示例**：
+```
+docs/plans/
+├── plan-2026-06-01-user-auth.md      # 第1轮
+├── plan-2026-06-05-user-auth-v2.md   # 第2轮迭代
+├── plan-2026-06-10-payment-flow.md   # 新任务
+└── plan-2026-06-15-order-module.md   # 新任务
+```
+
+**为什么这样设计**：
+1. 避免反复修改同一文件导致的 Git 冲突
+2. 保留完整决策轨迹，AI 和人都能回溯
+3. AI 执行完可以"丢弃"，不污染长期文档
+4. 降低维护成本——过程方案不需要维护
+
+**在 Plan/Go 模式中的角色**：
+- Plan 阶段产出 → 锁定上下文到 Plan 中
+- 记录实现状态，让任务可以分批完成或重试
+- 关闭所有开放性问题后再进入执行
+
+### 事实方案（Designs / Standards / Features）
+
+**定义**：反映系统**当前真实状态**的文档，是 Source of Truth。
+
+**特征**：
+- **长期有效**：稳定的、持续维护的
+- **最终态更新**：`变更: 每次以最终态更新`
+- **事实依据**：作为下一次 Plan 的起点
+- **必须一致**：与实际代码/系统保持同步
+
+**示例**：
+```
+docs/designs/
+├── database-schema.md      # 当前数据库表结构（最终态）
+├── api-endpoints.md        # 当前 API 定义（最终态）
+└── architecture.md         # 当前架构图（最终态）
+
+docs/standards/
+├── coding-style.md         # 编码规范
+└── security-guidelines.md  # 安全规范
+
+docs/features/
+├── user-management.md      # 用户管理需求（当前版本）
+└── order-system.md         # 订单系统需求（当前版本）
+```
+
+**为什么这样设计**：
+1. AI 每次 Plan 前读取这些文档，获得"当前真相"
+2. 避免 AI 基于过时信息做决策
+3. 只维护一份最终态，减少维护成本
+4. 是团队共识的载体
+
+### 规格流转图
+
+```
+起点 Features（需求规格）
+    ↓
+Standards（约束规范）
+    ↓
+TDD 驱动 → 测试 + 代码
+    ↓
+事实方案 Designs（更新最终态）  ← 变更：覆盖更新
+    ↓
+过程方案 Plans（执行记录）      ← 追加：新建文件
+    ↓
+回到起点 Features（验收）
+```
+
+### 实践建议
+
+1. **AGENTS.md 作为宪法**：定义 AI 行为边界和基本原则
+2. **区分"打算做"和"已做完"**：Plans 是意图，Designs 是事实
+3. **Plan 阶段尽可能锁定上下文**：关闭所有开放性问题
+4. **Plan 中记录实现状态**：让任务可以分批完成或重试
+5. **给出确定性验收方式**：如通过所有 API 测试，让 AI 建立自我修复标准
+
+---
+
+## 七、测试验收
+
+### AI 辅助测试策略
+
+| 测试类型 | 工具 | 负责人 |
+|----------|------|--------|
+| Lint 代码扫描 | TS Lint/SonarQube | 程序 |
+| Code Review | Copilot/Claude Code/CodeRabbit | 开发者 + AI |
+| 单元测试 | JUnit/pytest/Jest | 开发者 + AI |
+| API 测试 | Karate/RestAssured | QA + 后端 + AI |
+| E2E 测试 | Playwright | QA + 自动化 + AI |
+
+### AI 操作浏览器方案对比
+
+| 方案 | 原理 | 速度 | Token 消耗 | 跨应用 |
+|------|------|------|-----------|--------|
+| OpenWright (Playwright MCP) | Accessibility Tree | 快 ~0.9s | 高 | 仅浏览器 |
+| Chrome DevTools MCP | CDP 协议 | 中 ~1.2s | 中 | 仅浏览器 |
+| Browser Use | DOM + 截图双模 | 中 ~1.5s | 极低 | 仅浏览器 |
+| Computer Use | 视觉识别+坐标 | 慢 0.8-2s | 高 | 全桌面 |
+
+### E2E 测试生成策略
+1. **Browser Use 探索**：AI 自主遍历页面，记录操作轨迹（消耗 Token）
+2. **Playwright 固化**：转为测试脚本加入 CI（零 Token 可重复运行）
+3. **截图视觉兜底**：覆盖布局偏移、动效、Canvas 等场景
+
+### 核心 Loop（研发自测）
+```
+Plan 模式装载需求规格 → Plan 确认 → 编写 API 测试 → 编写实现
+    → 运行测试 → 通过？→ 退出循环
+                 ↓ 否
+              修复重试
+```
+
+### 超级 Loop（E2E Loop）
+在核心 Loop 基础上增加：
+- 编写测试用例（docs/test-cases）
+- 浏览器调试（Playwright 确认视觉效果）
+- 编写 E2E 测试覆盖本轮需求
+
+---
+
+## 八、Agent as Code
+
+### AI 工程文件管理
+```
+AGENTS.md          ← 宪法，构建引用关系
+docs/
+├── .ai/           ← AI 配置
+├── standards/     ← 标准规格
+├── features/      ← 需求规格
+├── designs/       ← 设计规格
+├── plans/         ← 计划规格
+├── skills/        ← AI 技能
+└── mcp/           ← MCP 配置
+
+.claude / .opencode / .cursor  → 软链到 AGENTS.md
+```
+
+---
+
+## 九、实践心得
+
+> - 放弃"开箱即用"的框架，每个项目需要构建自己的 Harness 工具和文档
+> - "少量取用，大量实践"是更好的策略
+
+---
+
+## 参考资料
+
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
+- [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
+- [Harness Design for Long-running Apps - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [从 Rule、Spec 到 Harness 的渐进式建设路径](https://mp.weixin.qq.com/s/UCh2bPzMZjNBMBCCJysuNw)
+- [Understanding SDD: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
+- [harness-engineering-in-ai-coding](https://github.com/2361485765/harness-engineering-in-ai-coding)