chill/chill_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update from Sync Service

Browse Source
This commit is contained in:
FNS Service
2026-06-22 11:30:51 +08:00
parent eb80b7a8c1
commit 682e3e52df
52 changed files with 10099 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
AI工程/概念/AGENTS.md.md Executable file
View File

@@ -0,0 +1,174 @@
# AGENTS.md
> 相关：[[Agent_as_Code]]、[[上下文体系]]、[[Harness工程]]
## 定义
**AGENTS.md**是AI协作的宪法级配置文件，定义AI的基本行为规则，所有AI工具都从这个文件开始。
**核心思想**：AGENTS.md是AI的"宪法"，约束AI的行为边界。
## 核心特征
### 1. 宪法级
- 最高优先级
- 所有AI工具都读取
- 定义基本行为规则
### 2. 统一入口
- AI从这个文件开始
- 引用其他文档
- 形成完整的上下文
### 3. 可版本化
- 纳入Git管理
- 变更有历史记录
- 可回滚
## 内容结构
### 基本信息
```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x, React 18
- 代码规范：阿里巴巴Java开发手册
```
### AI行为规则
```markdown
# AI行为规则
1. 生成代码必须符合代码规范
2. 数据库表必须包含created_at, updated_at字段
3. API接口必须使用RESTful风格
4. 敏感数据必须加密存储
```
### 目录结构
```markdown
# 目录结构
- src/main/java/com/example/project/controller
- src/main/java/com/example/project/service
- src/main/java/com/example/project/repository
```
### 引用文件
```markdown
# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
```
## 完整示例
```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x, React 18
- 代码规范：阿里巴巴Java开发手册
# AI行为规则
1. 生成代码必须符合代码规范
2. 数据库表必须包含created_at, updated_at字段
3. API接口必须使用RESTful风格
4. 敏感数据必须加密存储
5. 所有方法必须有注释
6. 所有API必须有单元测试
# 目录结构
- src/main/java/com/example/project/controller
- src/main/java/com/example/project/service
- src/main/java/com/example/project/repository
- src/main/java/com/example/project/domain
- src/main/java/com/example/project/infrastructure
# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
- 安全规范：./docs/standards/security.md
# 开发流程
1. Plan阶段：创建Plan文档，等待确认
2. 执行阶段：按照Plan实现代码
3. 验证阶段：运行测试，确保通过
# 测试要求
- 单元测试覆盖率 > 80%
- 所有API必须有集成测试
- 关键流程必须有E2E测试
```
## 配置位置
### 项目根目录
```
项目根目录/
├── AGENTS.md # 宪法级配置
├── .claude/
│ └── AGENTS.md -> ../AGENTS.md # 软链接
├── .opencode/
│ └── AGENTS.md -> ../AGENTS.md # 软链接
└── .cursor/
└── AGENTS.md -> ../AGENTS.md # 软链接
```
### 软链接实现
```bash
# Linux/Mac
ln -s ../AGENTS.md .claude/AGENTS.md
ln -s ../AGENTS.md .opencode/AGENTS.md
ln -s ../AGENTS.md .cursor/AGENTS.md
# Windows
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"
```
## 适用场景
- **团队协作**：多个开发者共享AI配置
- **多项目**：在多个项目间复用配置
- **持续迭代**：配置需要持续演进
- **知识沉淀**：最佳实践需要沉淀
## 优势
- **统一入口**：所有AI工具从这个文件开始
- **一致性**：所有AI工具行为一致
- **可追溯**：配置变更有历史记录
- **易维护**：修改一处，多处生效
## 挑战
- **初始成本**：需要建立完整的配置
- **维护成本**：需要持续维护配置
- **学习曲线**：团队需要理解配置
## 最佳实践
1. **从核心规则开始**：先定义最重要的规则
2. **逐步扩展**：根据实践逐步添加配置
3. **定期Review**：定期审查和优化配置
4. **团队共享**：将配置纳入团队知识管理
## 相关概念
- [[Agent_as_Code]]：AGENTS.md是Agent as Code的核心文件
- [[上下文体系]]：AGENTS.md是上下文体系的宪法级文件
- [[Harness工程]]：AGENTS.md是Harness的组成部分

67
AI工程/概念/AI编程演进阶段.md Executable file
View File

@@ -0,0 +1,67 @@
# AI 编程演进阶段
> 相关：[[团队级AI_Coding简明手册v0.2]]、[[Harness工程]]、[[Rule约束]]、[[规格驱动开发]]、[[Loop工程]]
## 概述
AI 编程从简单的手动复制粘贴，逐步演进到工程化的自动化开发体系。
## 5 个阶段
### 阶段1：原始阶段（本能驱动）
- **特征**：手动从浏览器中复制 AI 的代码，通过问答和 AI IDE 交互
- **方式**：人工复制粘贴，逐行审查
- **效率**：低，依赖人工
- **适用**：个人学习、简单脚本
### 阶段2：Rule 约束（经验规则显化）
- **特征**：定义 AI 在不同工作模式下的处理方式，如 RIPER-5
- **方式**：通过 Rules 文件约束 AI 行为
- **效率**：中等，需要持续对话输入需求
- **适用**：个人项目、小团队
### 阶段3：规格驱动（需求结构化表达）
- **特征**：基于规格流转的开发方式，如 OpenSpec 框架
- **方式**：文件进、文件出，结构化需求文档
- **效率**：较高，AI 可理解完整上下文
- **适用**：中型项目、团队协作
### 阶段4：Loop 工程（闭环自动化）
- **特征**：让 AI 能根据验收规则自动循环，构建测试套件
- **方式**：TDD 驱动，AI 自治运行，自动修复
- **效率**：高，半自动有人值守
- **适用**：复杂项目、持续集成
### 阶段5：Harness 驾驭工程（工程治理）
- **特征**：把 AI 纳入工程治理体系，提供约束体系和外部接口
- **方式**：完整的 Harness 体系，全自动 Plan 后无人值守
- **效率**：最高，全自动无人值守
- **适用**：企业级项目、大规模团队
## 演进路径
```
原始 → Rule → 规格驱动 → Loop → Harness
手动 规则 文档 自动 治理
低效 中效 高效 自动 全自动
```
## 关键转变
1. **从人工到自动**：减少人工干预
2. **从对话到文档**：从口头需求到结构化规格
3. **从单次到循环**：从一次性生成到持续迭代
4. **从自由到约束**：从无约束到工程化治理
## 实践建议
- **小团队**：从 Rule 约束开始，逐步引入规格驱动
- **中型团队**：采用规格驱动 + Loop 工程
- **大型团队**：构建完整的 Harness 体系
## 相关概念
- [[Harness工程]]
- [[核心Loop]]
- [[规格驱动开发]]
- [[Agent_as_Code]]

131
AI工程/概念/Agent_as_Code.md Executable file
View File

@@ -0,0 +1,131 @@
# Agent as Code
> 相关：[[Harness工程]]、[[AGENTS.md]]、[[上下文体系]]、[[Skills]]
## 定义
**Agent as Code**是将AI协作的所有文件以代码的方式管理的理念，实现可版本化、可复用、可共享。
**核心思想**：AI的行为由代码（配置文件）决定，而不是由人的临时提示决定。
## 核心特征
### 1. 可版本化
- 所有配置纳入Git管理
- 变更有历史记录
- 可回滚到历史版本
### 2. 可复用
- 配置可在项目间复用
- Skills可在团队间共享
- 最佳实践可沉淀
### 3. 可共享
- 团队成员共享AI配置
- 新成员快速上手
- 统一团队AI行为
## 核心文件
### AGENTS.md（宪法级）
```markdown
# 项目信息
- 项目名称：XXX
- 技术栈：Java 17, Spring Boot 3.x
# AI行为规则
1. 代码必须符合规范
2. 数据库表必须包含时间戳字段
3. API必须使用RESTful风格
```
### Skills目录
```
skills/
├── commit-push/
│ ├── SKILL.md
│ └── commit.sh
├── deploy/
│ ├── SKILL.md
│ └── deploy.sh
```
### MCP配置
```json
{
"mcpServers": {
"database": {
"command": "node",
"args": ["mcp-server-sqlite"]
}
}
}
```
## 实现方式
### 软链接共享配置
```bash
# 让多个AI工具共享AGENTS.md
ln -s ../AGENTS.md .claude/AGENTS.md
ln -s ../AGENTS.md .opencode/AGENTS.md
ln -s ../AGENTS.md .cursor/AGENTS.md
```
### Git管理
```bash
git add AGENTS.md
git add .claude/AGENTS.md
git commit -m "feat: add AGENTS.md for AI collaboration"
```
## 目录结构
```
项目根目录/
├── AGENTS.md # 宪法级配置
├── docs/
│ ├── standards/ # 标准规范
│ ├── features/ # 需求规格
│ ├── designs/ # 设计规格
│ └── plans/ # 计划规格
├── skills/ # AI技能
├── mcp/ # MCP配置
├── .claude/ # Claude Code配置
├── .opencode/ # OpenCode配置
└── .cursor/ # Cursor配置
```
## 适用场景
- **团队协作**：多个开发者共享AI配置
- **多项目**：在多个项目间复用配置
- **持续迭代**：配置需要持续演进
- **知识沉淀**：最佳实践需要沉淀
## 优势
- **一致性**：所有AI工具行为一致
- **可追溯**：配置变更有历史记录
- **可复用**：Skills和配置可复用
- **易维护**：修改一处，多处生效
## 挑战
- **初始成本**：需要建立完整的文档体系
- **维护成本**：需要持续维护配置
- **学习曲线**：团队需要理解Agent as Code理念
## 最佳实践
1. **从AGENTS.md开始**：先定义最基本的规则
2. **逐步扩展**：根据实践逐步添加配置
3. **定期Review**：定期审查和优化配置
4. **团队共享**：将配置纳入团队知识管理
## 相关概念
- [[Harness工程]]：Agent as Code是Harness的技术实现
- [[AGENTS.md]]：Agent as Code的核心文件
- [[上下文体系]]：Agent as Code的文档组织
- [[Skills]]：Agent as Code的能力单元

74
AI工程/概念/BMAD.md Executable file
View File

@@ -0,0 +1,74 @@
# BMAD
> 相关：[[规格驱动开发]]、[[Spec_Kit]]、[[OpenSpec]]、[[Kiro]]
## 定义
**BMAD**（Business Model Architecture Design）是企业级SDD框架，提供强治理和多Agent编排能力。
**核心思想**：Spec = 治理体系 + 多Agent编排，适合大型系统和多团队协作。
## 核心特征
### 1. 企业级定位
- 强治理体系
- 多Agent编排
- 全生命周期管理
### 2. 大粒度Spec
- 系统级/模块级规格
- 完整的架构设计
- 详细的实现方案
### 3. 强流程控制
- 阶段+审批+Agent
- 严格的变更控制
- 完整的审计轨迹
## 与其他SDD框架对比
| 维度 | 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） | 存量项目/快速迭代 | 小团队/高自动化 |
| 失控风险 | 低 | 中 | 高 | 中 |
## 适用场景
- **大型系统**：需要完整的架构设计
- **多团队协作**：需要强治理体系
- **企业级项目**：需要严格的变更控制
- **合规要求高**：需要完整的审计轨迹
## 优势
- **强治理**：完整的治理体系
- **多Agent编排**：支持多个AI Agent协同
- **全生命周期**：覆盖从需求到交付的全流程
- **失控风险低**：严格的流程控制
## 挑战
- **学习曲线陡峭**：需要理解完整的框架
- **初始成本高**：需要建立完整的治理体系
- **灵活性低**：流程严格，不够灵活
- **维护成本高**：需要持续维护治理体系
## 最佳实践
1. **适合大型团队**：小型团队不建议使用
2. **逐步引入**：不要一开始就引入所有概念
3. **培训团队**：团队成员需要充分培训
4. **持续优化**：根据实践持续优化流程
## 相关概念
- [[规格驱动开发]]：BMAD是SDD框架之一
- [[Spec_Kit]]、[[OpenSpec]]、[[Kiro]]：其他SDD框架

144
AI工程/概念/Browser_Use.md Executable file
View File

@@ -0,0 +1,144 @@
# Browser Use
> 相关：[[测试策略金字塔]]、[[Playwright]]、[[Computer_Use]]、[[MCP]]
## 定义
**Browser Use**是一个Python框架，让AI可以自主操作浏览器，支持DOM和截图双模式。
**核心思想**：AI自主决策循环，支持DOM和截图双模，Token消耗极低。
## 核心特征
### 1. Python框架
- 基于Playwright
- AI自主决策循环
- 易于集成到Python项目
### 2. 双模式支持
- DOM模式：结构化DOM快照
- 截图模式：视觉理解
- 可以混合使用
### 3. 极低Token消耗
- CLI模式~75 tok/步
- 比其他方案低很多
- 成本敏感项目首选
## 原理
```
AI决策
↓
Browser Use框架
↓
Playwright操作浏览器
↓
获取DOM/截图
↓
AI分析结果
↓
下一步操作
```
## 与其他方案对比
| 维度 | Browser Use | Playwright MCP | Chrome DevTools MCP | Computer Use |
|------|-------------|----------------|---------------------|--------------|
| 原理 | Python框架 + Playwright，AI自主决策循环 | 通过Playwright访问浏览器Accessibility Tree | 通过Chrome DevTools Protocol直接与浏览器引擎通信 | AI截取屏幕截图 → 视觉识别元素 → 输出坐标/按键操作 |
| 抽象层 | DOM + 截图 视觉 + 结构化混合 | Accessibility Tree 结构化DOM快照 | CDP Protocol DevTools协议原生 | 截图 + 坐标 OS级视觉理解 |
| 速度 | 中 ~1.5s/步 | 快 ~0.9s/步 | 中 ~1.2s/步 | 慢 0.8-2s/步 |
| Token消耗 | 极低 CLI模式 ~75 tok/步 | 高 截图+结构全传 | 中 按需取数据 | 高 截图编码开销大 |
| JS重页面 | 中 — 视觉兜底 | 中 — DOM可读 | 中 — CDP可取 | 高 — 视觉理解 |
| 跨应用操作 | 仅浏览器 | 仅浏览器 | 仅浏览器 | 全桌面 |
## 使用示例
### 基本使用
```python
from browser_use import Agent
agent = Agent(
task="Go to Reddit, search for 'r/LocalLLaMA' and click on the first post",
llm=llm
)
result = await agent.run()
print(result)
```
### 原始指令
```python
agent = Agent(
task="""
1. 打开 /login 页面
2. 输入用户名 test@example.com
3. 输入密码 123456
4. 点击登录按钮
5. 验证跳转到 /dashboard
6. 验证页面显示 "Welcome"
""",
llm=llm
)
```
### AI探索后生成的Playwright脚本雏形
```typescript
test('login flow', async ({ page }) => {
await page.goto('/login');
await page.fill('[name="email"]', 'test@example.com');
await page.fill('[name="password"]', '123456');
await page.click('button[type="submit"]');
await expect(page).toHaveURL('/dashboard');
await expect(page.locator('text=Welcome')).toBeVisible();
});
```
## E2E测试生成三步法
### Step 1: Browser Use探索
- AI自主遍历页面，记录操作轨迹、选择器、页面状态
- 输出Playwright脚本雏形
- 消耗Token
### Step 2: Playwright E2E固化
- 将探索结果转为Playwright测试脚本
- 加入CI，零Token可重复运行
### Step 3: 截图视觉兜底
- Playwright覆盖不到的视觉场景（布局、动效、图表）
- 重回截图判断
## 适用场景
- **Token成本敏感**：极低Token消耗
- **复杂网页自动化**：需要视觉理解
- **E2E测试探索**：快速生成测试脚本雏形
- **网页数据抓取**：自动化数据提取
## 优势
- **Token消耗极低**：CLI模式~75 tok/步
- **AI自主决策**：无需手动编写脚本
- **支持视觉理解**：可以处理复杂视觉场景
- **易于集成**：Python框架，易于集成到项目
## 挑战
- **仅限浏览器**：不能操作其他应用
- **依赖Python**：需要Python生态
- **学习成本**：需要了解框架使用
## 最佳实践
1. **Token成本敏感首选**：极低Token消耗
2. **先用Browser Use探索**：快速生成测试脚本雏形
3. **人工审查后固化**：优化选择器，加入CI/CD
4. **关键页面截图验证**：视觉回归测试
## 相关概念
- [[测试策略金字塔]]：Browser Use是E2E测试的工具
- [[Playwright]]：Browser Use基于Playwright
- [[Computer_Use]]：Browser Use和Computer Use的对比
- [[MCP]]：Browser Use和MCP的对比

73
AI工程/概念/Claude_Code.md Executable file
View File

@@ -0,0 +1,73 @@
# Claude Code
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[Cursor]]、[[Kiro]]、[[Trae]]
## 定义
**Claude Code**是Anthropic推出的AI编程工具，基于Claude模型，提供强大的推理能力和长上下文支持。
**核心思想**：强大的推理能力，支持长上下文，内置MCP支持，Loop模式。
## 核心特征
### 1. 强大的推理能力
- 基于Claude模型
- 强大的逻辑推理
- 适合复杂逻辑
### 2. 长上下文支持
- 支持超长上下文
- 可以理解完整项目
- 适合大型项目
### 3. 内置MCP支持
- 原生支持MCP协议
- 可以访问外部工具
- 即插即用
### 4. Loop模式
- 支持自治运行
- 自动修复问题
- 持续迭代
## 与其他AI工具对比
| 工具 | 类型 | 价格 | AI模型 | 适用场景 |
|------|------|------|--------|---------|
| Claude Code | CLI | 按Token | Claude | 复杂逻辑 |
| [[Cursor]] | IDE | $20/月 | 多模型 | 日常开发 |
| [[Kiro]] | IDE | 免费+付费 | Claude | AWS项目 |
| [[Trae]] | IDE | 免费+付费 | 豆包 | 中文项目 |
## 适用场景
- **复杂逻辑**：需要强大的推理能力
- **大型项目**：需要长上下文支持
- **架构设计**：需要理解完整架构
- **问题排查**：需要深入分析问题
## 优势
- **推理能力强**：适合复杂逻辑
- **长上下文**：可以理解完整项目
- **MCP支持**：可以访问外部工具
- **Loop模式**：支持自治运行
## 挑战
- **按Token计费**：成本可能较高
- **CLI界面**：不如IDE直观
- **学习曲线**：需要了解CLI使用
## 最佳实践
1. **复杂逻辑首选**：推理能力最强
2. **长上下文利用**：充分利用长上下文能力
3. **MCP配置**：配置必要的MCP Server
4. **Loop模式**：充分利用Loop模式
## 相关概念
- [[Harness工程]]：Claude Code是Harness的工具之一
- [[Agent_as_Code]]：Claude Code支持Agent as Code
- [[Cursor]]、[[Kiro]]、[[Trae]]：其他AI编程工具

120
AI工程/概念/Computer_Use.md Executable file
View File

@@ -0,0 +1,120 @@
# Computer Use
> 相关：[[测试策略金字塔]]、[[Browser_Use]]、[[Playwright]]、[[MCP]]
## 定义
**Computer Use**是Anthropic推出的OS级视觉操作方案，让AI可以操作任何桌面应用。
**核心思想**：AI截取屏幕截图 → 视觉识别元素 → 输出坐标/按键操作 → 沙箱执行。
## 核心特征
### 1. OS级通用
- 可以操作任何应用
- 不限于浏览器
- 桌面级操作
### 2. 视觉理解
- 基于截图识别元素
- 输出坐标和按键
- 强大的视觉理解能力
### 3. 沙箱执行
- 在沙箱环境中执行
- 安全性高
- 可控制
## 原理
```
AI截取屏幕截图
↓
视觉识别元素
↓
输出坐标/按键操作
↓
沙箱执行
↓
返回结果
```
## 与其他方案对比
| 维度 | Computer Use | Playwright MCP | Chrome DevTools MCP | Browser Use |
|------|--------------|----------------|---------------------|-------------|
| 原理 | AI截取屏幕截图 → 视觉识别元素 → 输出坐标/按键操作 | 通过Playwright访问浏览器Accessibility Tree | 通过Chrome DevTools Protocol直接与浏览器引擎通信 | Python框架 + Playwright，AI自主决策循环 |
| 抽象层 | 截图 + 坐标 OS级视觉理解 | Accessibility Tree 结构化DOM快照 | CDP Protocol DevTools协议原生 | DOM + 截图 视觉 + 结构化混合 |
| 速度 | 慢 0.8-2s/步 | 快 ~0.9s/步 | 中 ~1.2s/步 | 中 ~1.5s/步 |
| Token消耗 | 高 截图编码开销大 | 高 截图+结构全传 | 中 按需取数据 | 极低 CLI模式 ~75 tok/步 |
| JS重页面 | 高 — 视觉理解 | 中 — DOM可读 | 中 — CDP可取 | 中 — 视觉兜底 |
| 跨应用操作 | 全桌面 | 仅浏览器 | 仅浏览器 | 仅浏览器 |
## 使用示例
### 基本使用
```python
from anthropic import Anthropic
client = Anthropic()
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
tools=[{
"type": "computer_20241022",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768,
}],
messages=[{
"role": "user",
"content": "Open Chrome and go to google.com"
}]
)
```
## 适用场景
- **桌面应用自动化**：操作任何桌面应用
- **需要跨应用操作**：多个应用协同
- **复杂视觉场景**：需要视觉理解
- **无法使用API的场景**：没有API的应用
## 优势
- **可以操作任何应用**：不限于浏览器
- **可以处理复杂的视觉场景**：视觉理解能力强
- **OS级通用**：桌面级操作
## 挑战
- **速度慢**：0.8-2s/步
- **Token消耗高**：截图编码开销大
- **依赖视觉识别准确性**：可能误识别
- **成本高**：Token消耗大
## 最佳实践
1. **需要跨应用选Computer Use**：OS级通用
2. **复杂视觉场景选Computer Use**：视觉理解能力强
3. **成本敏感不选Computer Use**：Token消耗高
4. **速度要求高不选Computer Use**：速度慢
## 方案选择指南
| 场景 | 推荐方案 | 理由 |
|------|---------|------|
| E2E测试 | Playwright MCP | 速度快，结构化信息丰富 |
| 性能分析 | Chrome DevTools MCP | 可以监控网络和性能 |
| 网页自动化 | Browser Use | Token消耗低，AI自主决策 |
| 桌面应用 | Computer Use | 可以操作任何应用 |
| Token成本敏感 | Browser Use | 极低Token消耗 |
| 复杂视觉场景 | Computer Use | 视觉理解能力强 |
## 相关概念
- [[测试策略金字塔]]：Computer Use是测试的工具
- [[Browser_Use]]：Computer Use和Browser Use的对比
- [[Playwright]]：Computer Use和Playwright的对比
- [[MCP]]：Computer Use和MCP的对比

73
AI工程/概念/Cursor.md Executable file
View File

@@ -0,0 +1,73 @@
# Cursor
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[Claude_Code]]、[[Kiro]]、[[Trae]]
## 定义
**Cursor**是基于VS Code的AI IDE，提供AI优先的开发体验。
**核心思想**：基于VS Code，AI优先设计，强大的代码补全，Composer模式。
## 核心特征
### 1. 基于VS Code
- 熟悉的IDE界面
- 丰富的插件生态
- 易于上手
### 2. AI优先设计
- AI深度集成
- 智能代码补全
- 上下文感知
### 3. Composer模式
- 多文件编辑
- 智能重构
- 批量修改
### 4. 多模型支持
- 支持多种AI模型
- 可以切换模型
- 灵活选择
## 与其他AI工具对比
| 工具 | 类型 | 价格 | AI模型 | 适用场景 |
|------|------|------|--------|---------|
| [[Claude_Code]] | CLI | 按Token | Claude | 复杂逻辑 |
| Cursor | IDE | $20/月 | 多模型 | 日常开发 |
| [[Kiro]] | IDE | 免费+付费 | Claude | AWS项目 |
| [[Trae]] | IDE | 免费+付费 | 豆包 | 中文项目 |
## 适用场景
- **日常开发**：最常用的开发工具
- **代码补全**：需要智能代码补全
- **多文件编辑**：需要批量修改
- **团队协作**：需要熟悉的IDE环境
## 优势
- **熟悉界面**：基于VS Code，易于上手
- **AI集成**：AI深度集成
- **代码补全**：强大的代码补全
- **多模型**：支持多种AI模型
## 挑战
- **付费**：需要$20/月
- **资源消耗**：可能消耗较多资源
- **依赖网络**：需要网络连接
## 最佳实践
1. **日常开发首选**：最适合作为日常开发工具
2. **代码补全利用**：充分利用智能代码补全
3. **Composer模式**：充分利用多文件编辑能力
4. **模型选择**：根据需求选择合适的模型
## 相关概念
- [[Harness工程]]：Cursor是Harness的工具之一
- [[Agent_as_Code]]：Cursor支持Agent as Code
- [[Claude_Code]]、[[Kiro]]、[[Trae]]：其他AI编程工具

125
AI工程/概念/Git_Worktree.md Executable file
View File

@@ -0,0 +1,125 @@
# Git Worktree
> 相关：[[Harness工程]]、[[核心Loop]]、[[超级Loop]]
## 定义
**Git Worktree**是Git的一个功能，允许从同一个仓库检出多个工作目录，每个工作目录都是一个独立的分支。
**核心思想**：共享同一个.git目录，节省磁盘空间，实现多任务并行开发。
## 核心特征
### 1. 多工作区
- 一个仓库，多个工作目录
- 每个工作目录是一个独立分支
- 共享同一个.git目录
### 2. 并行开发
- 多个AI实例可以同时工作
- 互不干扰
- 快速切换
### 3. 节省空间
- 共享.git目录
- 不需要克隆多个仓库
- 节省磁盘空间
## 基本命令
### 创建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
```
### 管理Worktree
```bash
# 列出所有工作区
git worktree list
# 输出：
# /project/main abc1234 [main]
# /project/feature-a def5678 [feature-a]
# /project/feature-b ghi9012 [feature-b]
# 删除工作区
git worktree remove ../feature-a
# 强制删除（即使有未提交的更改）
git worktree remove --force ../feature-a
# 清理已删除的工作区记录
git worktree prune
```
## 使用场景
### 场景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
```
## 优势
1. **并行开发**：多个AI实例可以同时工作在不同分支
2. **上下文隔离**：每个功能的上下文独立，不会混淆
3. **快速切换**：不需要`git checkout`，直接切换目录
4. **节省空间**：共享.git目录
## 挑战
- **分支管理**：需要管理多个分支
- **冲突处理**：可能需要处理分支冲突
- **学习成本**：需要了解Git Worktree概念
## 最佳实践
1. **命名规范**：工作区目录名与分支名一致
2. **及时清理**：完成的功能及时删除Worktree
3. **AI工具支持**：利用AI工具的自动Worktree功能
4. **定期Prune**：定期清理无效的工作区记录
## 相关概念
- [[Harness工程]]：Git Worktree是Harness的组成部分
- [[核心Loop]]：Git Worktree支持并行执行多个Loop
- [[超级Loop]]：Git Worktree支持并行执行多个超级Loop

114
AI工程/概念/Harness工程.md Executable file
View File

@@ -0,0 +1,114 @@
# Harness工程（驾驭工程）
> 相关：[[AI编程演进阶段]]、[[Agent_as_Code]]、[[核心Loop]]、[[上下文体系]]
## 定义
**Harness工程**是AI编程的第5阶段，将AI纳入工程治理体系，为其提供约束体系和外部接口，实现全自动无人值守的开发。
**核心思想**：不是让AI更聪明，而是让AI在受控环境中工作。
## 核心特征
### 1. 约束体系
- **规则约束**：Rules定义AI能做什么、不能做什么
- **规格约束**：Spec定义需求和设计的边界
- **测试约束**：自动化测试验证AI输出质量
### 2. 外部接口
- **MCP**：让AI访问数据库、文件系统等外部工具
- **Skills**：可复用的能力单元
- **CLI**：命令行工具集成
### 3. 自动化流程
- **Plan阶段**：人机协作，锁定需求
- **执行阶段**：AI自治，无需人工介入
- **验证阶段**：自动化测试，自动修复
## 关键原则
### 约束大于提示
- 不要依赖AI的"聪明"
- 通过约束体系保证质量
- 规则 > 提示词
### 文档即代码
- AGENTS.md作为宪法
- 规格文档可版本化
- 所有配置纳入Git
### 持续验证
- TDD驱动开发
- 自动化测试覆盖
- 持续集成持续交付
## 组成部分
```
Harness = 约束体系 + 工具体系 + 验证体系
约束体系：
- Rules（规则）
- Specs（规格）
- Standards（标准）
工具体系：
- MCP（外部工具）
- Skills（能力单元）
- CLI（命令行）
验证体系：
- 单元测试
- API测试
- E2E测试
- Code Review
```
## 适用场景
- **企业级项目**：需要严格的质量控制
- **多团队协作**：需要统一的开发规范
- **长期维护**：需要持续的代码质量保证
- **合规要求**：金融、医疗等需要审计的场景
## 实践要点
### 1. 建立文档体系
```
AGENTS.md ← 宪法
docs/
├── standards/ ← 标准规格
├── features/ ← 需求规格
├── designs/ ← 设计规格（事实方案）
└── plans/ ← 计划规格（过程方案）
```
### 2. 配置工具链
- 选择合适的AI工具（Claude Code/Cursor/Kiro）
- 配置MCP访问外部工具
- 开发Skills封装常用能力
### 3. 建立验证流程
- 定义测试策略
- 配置CI/CD流程
- 建立Code Review规范
## 优势
- **质量可控**：通过约束体系保证代码质量
- **可追溯**：所有配置和变更有历史记录
- **可复用**：Skills和配置可在项目间复用
- **可扩展**：易于引入新的工具和流程
## 挑战
- **学习曲线**：需要理解完整的工程体系
- **维护成本**：需要持续维护文档和配置
- **工具依赖**：依赖多个AI工具和协议
## 相关概念
- [[Agent_as_Code]]：Harness的技术实现方式
- [[核心Loop]]：Harness中的开发循环
- [[上下文体系]]：Harness的文档组织
- [[AI编程演进阶段]]：Harness是第5阶段

73
AI工程/概念/Kiro.md Executable file
View File

@@ -0,0 +1,73 @@
# Kiro
> 相关：[[规格驱动开发]]、[[BMAD]]、[[Spec_Kit]]、[[OpenSpec]]
## 定义
**Kiro**是AWS推出的AI IDE和SDD框架，提供IDE原生的SDD能力。
**核心思想**：Spec = 可执行源（代码与测试），可以生成代码+测试并自动校验。
## 核心特征
### 1. IDE原生
- 深度集成IDE
- 原生SDD支持
- 无缝开发体验
### 2. 可执行Spec
- Spec可以直接生成代码
- Spec可以直接生成测试
- 自动校验
### 3. 强流程控制
- 闭环流程
- 自动验证
- 高度自动化
## 与其他SDD框架对比
| 维度 | [[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） | 存量项目/快速迭代 | 小团队/高自动化 |
| 失控风险 | 低 | 中 | 高 | 中 |
## 适用场景
- **小团队**：不需要强治理
- **高自动化需求**：需要自动验证
- **AWS项目**：深度集成AWS服务
- **新项目**：从零开始的项目
## 优势
- **IDE原生**：无缝开发体验
- **可执行Spec**：Spec可以直接生成代码和测试
- **自动验证**：内建自动验证
- **高度自动化**：减少人工干预
## 挑战
- **IDE绑定**：依赖特定IDE
- **学习成本**：需要了解Kiro的工作流
- **灵活性低**：不如OpenSpec灵活
## 最佳实践
1. **适合小团队**：小型团队最适合
2. **高自动化**：充分利用自动验证能力
3. **AWS集成**：充分利用AWS集成能力
4. **持续学习**：持续学习Kiro的最佳实践
## 相关概念
- [[规格驱动开发]]：Kiro是SDD框架之一
- [[BMAD]]、[[Spec_Kit]]、[[OpenSpec]]：其他SDD框架

98
AI工程/概念/Loop工程.md Executable file
View File

@@ -0,0 +1,98 @@
# Loop工程
> 相关：[[核心Loop]]、[[超级Loop]]、[[Harness工程]]、[[测试策略金字塔]]
## 定义
**Loop工程**是AI编程的第4阶段，通过构建测试套件和验收规则，让AI能够根据验收规则自动循环，实现半自动有人值守的开发。
**核心思想**：让AI能根据验收规则自动循环，构建测试套件，定义输出结果。
## 核心特征
### 1. 自动循环
- AI根据验收规则自动运行
- 失败时自动修复并重试
- 直到满足退出条件
### 2. 测试驱动
- TDD驱动开发
- 先写测试再写代码
- 测试作为验收标准
### 3. 有人值守
- Plan阶段需要人工确认
- 执行阶段AI自治
- 异常时需要人工介入
## Loop类型
### [[核心Loop]]
- 范围：API测试
- 验证：后端逻辑
- 复杂度：中等
- 适用：后端开发
### [[超级Loop]]
- 范围：API测试 + E2E测试
- 验证：前后端联动
- 复杂度：高
- 适用：全栈开发
## Loop流程
```
Plan阶段（人机协作）
↓
装载需求规格 → 创建Plan → 确认Plan
↓
执行阶段（AI自治）
↓
编写测试 → 编写实现 → 运行测试
↓ ↓
↓ 失败 ↓ 成功
↓ ↓
修复重试 ←──────────────────── 退出循环
```
## 退出条件
1. 所有测试通过
2. 代码符合规范（Lint通过）
3. 没有编译错误
4. 满足验收标准
## 适用场景
- **复杂项目**：需要自动化开发流程
- **持续集成**：需要持续交付
- **团队协作**：需要统一的开发流程
- **质量保证**：需要严格的测试覆盖
## 优势
- **自动化**：减少人工干预
- **质量保证**：TDD驱动，代码质量有保障
- **可追溯**：Plan记录了实现过程
- **持续迭代**：可以快速修复问题
## 挑战
- **Plan质量**：Plan阶段需要充分沟通
- **测试覆盖**：需要编写全面的测试
- **运行时间**：Loop可能需要较长时间
- **调试复杂**：失败时需要调试
## 最佳实践
1. **Plan阶段充分沟通**：关闭所有开放性问题
2. **TDD驱动**：先写测试再写代码
3. **记录状态**：方便复盘和优化
4. **逐步扩展**：从核心Loop开始，逐步引入超级Loop
## 相关概念
- [[核心Loop]]：Loop工程的具体实现
- [[超级Loop]]：Loop工程的扩展实现
- [[Harness工程]]：Loop工程是Harness的组成部分
- [[测试策略金字塔]]：Loop工程使用的测试策略

157
AI工程/概念/MCP.md Executable file
View File

@@ -0,0 +1,157 @@
# MCP（Model Context Protocol）
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[Skills]]
## 定义
**MCP**（Model Context Protocol）是AI与外部系统通信的标准协议，由Anthropic提出。
**核心思想**：标准化接口、双向通信、即插即用，让AI可以访问外部工具。
## 核心特征
### 1. 标准化接口
- 统一的协议规范
- 跨工具兼容
- 易于扩展
### 2. 双向通信
- AI可以调用外部工具
- 外部工具可以返回结果
- 支持流式通信
### 3. 即插即用
- 配置即可使用
- 无需修改AI代码
- 支持热插拔
## 架构
### Client-Server架构
```
AI工具（Client）
↓
MCP协议
↓
MCP Server（外部工具）
↓
数据库/文件系统/API等
```
### 常用MCP Server
| 类型 | Server | 用途 |
|------|--------|------|
| 数据库 | mcp-server-sqlite | SQLite数据库访问 |
| 数据库 | mcp-server-postgres | PostgreSQL数据库访问 |
| 文件系统 | mcp-server-filesystem | 文件系统访问 |
| Web搜索 | mcp-server-brave-search | Brave搜索 |
| GitHub | mcp-server-github | GitHub API访问 |
| 浏览器 | mcp-server-playwright | 浏览器自动化 |
## 配置示例
### Claude Code配置
```json
{
"mcpServers": {
"database": {
"command": "node",
"args": ["mcp-server-sqlite"]
},
"filesystem": {
"command": "node",
"args": ["mcp-server-filesystem", "/path/to/dir"]
},
"brave-search": {
"command": "node",
"args": ["mcp-server-brave-search"],
"env": {
"BRAVE_API_KEY": "your-api-key"
}
}
}
}
```
### 配置文件位置
- Claude Code：`.claude/mcp.json`
- Cursor：`.cursor/mcp.json`
- OpenCode：`.opencode/mcp.json`
## 使用场景
### 1. 数据库访问
```json
{
"mcpServers": {
"database": {
"command": "node",
"args": ["mcp-server-postgres"],
"env": {
"DATABASE_URL": "postgresql://user:pass@localhost:5432/db"
}
}
}
}
```
### 2. 文件系统访问
```json
{
"mcpServers": {
"filesystem": {
"command": "node",
"args": ["mcp-server-filesystem", "/path/to/project"]
}
}
}
```
### 3. Web搜索
```json
{
"mcpServers": {
"brave-search": {
"command": "node",
"args": ["mcp-server-brave-search"],
"env": {
"BRAVE_API_KEY": "your-api-key"
}
}
}
}
```
## 适用场景
- **数据库访问**：让AI直接查询数据库
- **文件系统访问**：让AI读写文件
- **API调用**：让AI调用外部API
- **浏览器自动化**：让AI操作浏览器
## 优势
- **标准化**：统一的协议规范
- **易用性**：配置即可使用
- **可扩展**：支持自定义Server
- **跨工具**：多个AI工具可以共用
## 挑战
- **安全性**：需要控制AI的访问权限
- **性能**：可能影响AI响应速度
- **维护成本**：需要维护MCP Server
## 最佳实践
1. **最小权限**：只开放必要的MCP Server
2. **环境隔离**：不同环境使用不同的MCP配置
3. **监控日志**：记录AI的MCP调用
4. **定期审查**：定期审查MCP配置
## 相关概念
- [[Harness工程]]：MCP是Harness的组成部分
- [[Agent_as_Code]]：MCP是Agent as Code的组成部分
- [[Skills]]：MCP和Skills都是AI的能力扩展方式

73
AI工程/概念/OpenSpec.md Executable file
View File

@@ -0,0 +1,73 @@
# OpenSpec
> 相关：[[规格驱动开发]]、[[BMAD]]、[[Spec_Kit]]、[[Kiro]]
## 定义
**OpenSpec**是轻量级SDD框架，提供灵活的Spec层。
**核心思想**：Spec = 变更单元（持续演化），适合存量项目和快速迭代。
## 核心特征
### 1. 轻量级定位
- 灵活自由
- 最小化约束
- 快速迭代
### 2. 小粒度Spec
- 变更/Patch级规格
- 长期存在
- 持续演化
### 3. 弱流程控制
- 自由演化
- 最小化流程
- 适合快速迭代
## 与其他SDD框架对比
| 维度 | [[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） | 存量项目/快速迭代 | 小团队/高自动化 |
| 失控风险 | 低 | 中 | 高 | 中 |
## 适用场景
- **存量项目**：已有代码库的项目
- **快速迭代**：需要快速响应变化
- **小型团队**：不需要强治理
- **灵活需求**：需要最大的灵活性
## 优势
- **轻量灵活**：最小化约束
- **快速迭代**：适合快速变化
- **易于上手**：学习曲线平缓
- **适合存量项目**：不需要重构
## 挑战
- **失控风险高**：缺乏流程控制
- **不适合大型项目**：缺乏治理能力
- **不适合新项目**：不如Spec Kit结构化
## 最佳实践
1. **适合存量项目**：已有代码库的项目最适合
2. **快速迭代**：充分利用灵活性
3. **适度约束**：虽然灵活，但需要适度约束
4. **持续演化**：Spec持续演化，保持最新
## 相关概念
- [[规格驱动开发]]：OpenSpec是SDD框架之一
- [[BMAD]]、[[Spec_Kit]]、[[Kiro]]：其他SDD框架

192
AI工程/概念/Playwright.md Executable file
View File

@@ -0,0 +1,192 @@
# Playwright
> 相关：[[测试策略金字塔]]、[[Browser_Use]]、[[MCP]]
## 定义
**Playwright**是最流行的浏览器自动化测试框架，支持Chromium、Firefox、WebKit。
**核心思想**：提供稳定、快速的浏览器自动化能力，支持多浏览器、多平台。
## 核心特征
### 1. 多浏览器支持
- Chromium（Chrome、Edge）
- Firefox
- WebKit（Safari）
- 一套API，多浏览器运行
### 2. 自动化能力
- 自动等待元素可操作
- 自动重试断言
- 网络拦截
- 截图和视频录制
### 3. 稳定性
- 使用稳定的选择器
- 自动处理动态内容
- 支持并行测试
## 基本使用
### 安装
```bash
npm init playwright@latest
```
### 基本测试
```typescript
import { test, expect } from '@playwright/test';
test('basic test', async ({ page }) => {
await page.goto('https://playwright.dev/');
await page.getByText('Get Started').click();
await expect(page).toHaveTitle(/Getting started/);
});
```
### 登录测试
```typescript
test('login success', async ({ page }) => {
await page.goto('https://example.com/login');
await page.getByPlaceholder('Email').fill('test@example.com');
await page.getByPlaceholder('Password').fill('123456');
await page.getByRole('button', { name: 'Login' }).click();
await expect(page).toHaveURL(/dashboard/);
await expect(page.getByText('Welcome')).toBeVisible();
});
```
### API登录（更稳定）
```typescript
test('login via API + set session', async ({ page, request }) => {
const response = await request.post('https://example.com/api/login', {
data: {
email: 'test@example.com',
password: '123456'
}
});
expect(response.ok()).toBeTruthy();
const cookies = await response.headers()['set-cookie'];
await page.context().addCookies([{
name: 'session',
value: cookies,
domain: 'example.com',
path: '/'
}]);
await page.goto('https://example.com/dashboard');
await expect(page.getByText('Welcome')).toBeVisible();
});
```
## 选择器最佳实践
### 推荐的选择器（从优到差）
```typescript
// 1. 使用data-testid（最稳定）
await page.getByTestId('submit-button').click();
// 2. 使用角色和名称（推荐）
await page.getByRole('button', { name: 'Login' }).click();
// 3. 使用标签文本（推荐）
await page.getByLabel('Email').fill('test@example.com');
// 4. 使用占位符（可用）
await page.getByPlaceholder('Enter your email').fill('test@example.com');
// 5. 使用文本（可用）
await page.getByText('Welcome').toBeVisible();
// 6. 使用CSS选择器（不推荐，容易变）
await page.locator('.btn-primary').click();
// 7. 使用XPath（不推荐，容易变）
await page.locator('//button[@type="submit"]').click();
```
## 等待策略
### 自动等待
```typescript
// Playwright自动等待元素可见、可操作
await page.getByRole('button', { name: 'Login' }).click();
```
### 显式等待
```typescript
// 等待URL变化
await expect(page).toHaveURL(/dashboard/);
// 等待元素可见
await expect(page.getByText('Welcome')).toBeVisible();
// 等待元素隐藏
await expect(page.getByText('Loading')).toBeHidden();
// 等待网络请求完成
await page.waitForLoadState('networkidle');
```
## 配置
### playwright.config.ts
```typescript
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
use: {
baseURL: 'http://localhost:3000',
trace: 'on-first-retry',
},
projects: [
{ name: 'chromium', use: { browserName: 'chromium' } },
{ name: 'firefox', use: { browserName: 'firefox' } },
{ name: 'webkit', use: { browserName: 'webkit' } },
],
});
```
## 适用场景
- **E2E测试**：最流行的E2E测试框架
- **浏览器自动化**：自动化浏览器操作
- **视觉回归测试**：截图对比
- **性能测试**：页面加载性能
## 优势
- **多浏览器支持**：一套API，多浏览器运行
- **稳定性**：自动等待、自动重试
- **速度快**：比Selenium快
- **生态成熟**：社区活跃，文档完善
## 挑战
- **学习成本**：需要了解框架API
- **维护成本**：需要维护测试脚本
- **运行时间**：完整的E2E测试运行时间长
## 最佳实践
1. **优先使用稳定的选择器**：data-testid、角色、标签
2. **使用API登录**：提高测试速度
3. **测试数据管理**：使用Fixture或API准备数据
4. **并行测试**：提高测试效率
5. **CI/CD集成**：每次提交自动运行测试
## 相关概念
- [[测试策略金字塔]]：Playwright是E2E测试的工具
- [[Browser_Use]]：Playwright和Browser Use的对比
- [[MCP]]：Playwright MCP是MCP的一种实现

133
AI工程/概念/Rule约束.md Executable file
View File

@@ -0,0 +1,133 @@
# Rule约束
> 相关：[[AI编程演进阶段]]、[[Harness工程]]、[[规格驱动开发]]
## 定义
**Rule约束**是AI编程的第2阶段，通过规则文件约束AI在不同工作模式下的处理方式。
**核心思想**：用明确的规则告诉AI能做什么、不能做什么，而不是依赖AI的"聪明"。
## 核心特征
### 1. 规则显化
- 将隐式的经验转化为显式的规则
- 规则以文件形式存在
- 规则可版本化、可共享
### 2. 工作模式
- 定义AI在不同模式下的行为
- 如：Research模式、Plan模式、Code模式
- 每种模式有不同的约束
### 3. 持续对话
- 需要通过对话输入需求
- AI根据规则约束生成代码
- 人工需要持续监督
## 典型框架
### RIPER-5
- **R**esearch：研究阶段，分析需求
- **I**mplement：实现阶段，编写代码
- **P**lan：规划阶段，制定计划
- **E**valuate：评估阶段，验证结果
- **R**eview：审查阶段，Code Review
### 规则示例
```markdown
# Java代码风格Rules
1. 使用Java 17语法，不使用已废弃API
2. 类名使用大驼峰，方法名使用小驼峰
3. 常量使用全大写下划线分隔
4. 单行代码不超过120字符
5. 禁止使用@Autowired字段注入
6. 数据库表必须包含created_at和updated_at字段
```
## 规则分类
### 1. 代码风格规则
- 命名规范
- 格式规范
- 注释规范
### 2. 架构规则
- 分层架构约束
- 依赖方向约束
- 模块划分规则
### 3. 安全规则
- 敏感数据处理
- 权限控制
- 加密要求
### 4. 性能规则
- 数据库查询优化
- 缓存策略
- 并发控制
## 载体
### .cursor/rules/
```
.cursor/
└── rules/
├── java-style.md
├── api-style.md
└── security.md
```
### CLAUDE.md
```markdown
# 项目规则
## 代码规范
- 使用阿里巴巴Java开发手册
- 所有方法必须有注释
## 数据库规范
- 表名使用下划线命名
- 必须包含时间戳字段
```
### AGENTS.md
```markdown
# AI行为规则
1. 生成代码必须符合代码规范
2. 敏感数据必须加密存储
3. API必须使用RESTful风格
```
## 适用场景
- **个人项目**：约束AI生成符合个人习惯的代码
- **小团队**：统一团队代码风格
- **学习阶段**：通过规则学习最佳实践
## 优势
- **简单直接**：规则清晰，易于理解
- **快速上手**：不需要复杂的工具链
- **灵活调整**：规则可以随时修改
## 局限
- **需要持续对话**：每次都需要输入需求
- **无法自动化**：依赖人工监督
- **规则冲突**：复杂场景规则可能冲突
## 最佳实践
1. **从核心规则开始**：先定义最重要的规则
2. **逐步完善**：根据实践逐步添加规则
3. **定期Review**：定期审查和优化规则
4. **规则分层**：区分强制规则和推荐规则
## 相关概念
- [[AI编程演进阶段]]：Rule是第2阶段
- [[Harness工程]]：Rule是Harness的组成部分
- [[规格驱动开发]]：Rule的进阶是Spec

155
AI工程/概念/Skills.md Executable file
View File

@@ -0,0 +1,155 @@
# Skills
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[MCP]]
## 定义
**Skills**是可复用的AI能力单元，通过打包提示词、脚本、模版，进一步精确拓展AI的能力。
**核心思想**：将常用的能力封装成可复用的单元，提高AI的工作效率。
## 核心特征
### 1. 可复用
- 可以在多个项目中使用
- 可以在团队间共享
- 可以版本化管理
### 2. 触发词驱动
- 通过触发词调用
- 自动识别使用场景
- 无需手动配置
### 3. 封装完整
- 包含提示词
- 包含脚本工具
- 包含文档模版
## 组成
### 1. SKILL.md
- 技能描述
- 使用说明
- 触发词定义
### 2. 脚本文件
- 可执行的脚本
- 自动化工具
- 配置文件
### 3. 文档模版
- 输出格式模版
- 配置文件模版
- 报告模版
## 示例
### Commit & Push Skill
```markdown
# Commit & Push Skill
## 触发词
commit, push, 提交
## 执行
git add -A
git commit -m "{message}"
git push
## 规则
- 提交前检查lint
- 信息遵循conventional commit
- 推送前确认分支
```
### Deploy Skill
```markdown
# Deploy Skill
## 触发词
deploy, 部署, 发布
## 执行
npm run build
npx vercel --prod
## 规则
- 构建前运行测试
- 部署前确认环境
- 部署后验证功能
```
### Test Skill
```markdown
# Test Skill
## 触发词
test, 测试, 运行测试
## 执行
mvn test
## 规则
- 运行所有测试
- 生成测试报告
- 失败时提供修复建议
```
## 目录结构
```
skills/
├── commit-push/
│ ├── SKILL.md
│ └── commit.sh
├── deploy/
│ ├── SKILL.md
│ └── deploy.sh
├── test/
│ ├── SKILL.md
│ └── test.sh
└── code-review/
├── SKILL.md
└── review.sh
```
## 开发流程
1. **需求分析**：确定技能的功能和触发词
2. **脚本开发**：编写可执行的脚本
3. **触发词定义**：定义触发词和使用场景
4. **测试验证**：测试技能的功能
5. **文档编写**：编写SKILL.md文档
## 适用场景
- **常用操作**：提交代码、部署、测试等
- **复杂流程**：需要多个步骤的操作
- **团队协作**：需要统一的操作规范
- **知识沉淀**：最佳实践需要沉淀
## 优势
- **可复用**：可以在多个项目中使用
- **易共享**：可以在团队间共享
- **易维护**：可以版本化管理
- **易扩展**：可以快速添加新技能
## 挑战
- **初始成本**：需要开发Skills
- **维护成本**：需要持续维护Skills
- **学习成本**：团队需要学习Skills
## 最佳实践
1. **从常用操作开始**：先封装最常用的操作
2. **保持简单**：每个Skill只做一件事
3. **文档清晰**：SKILL.md要清晰易懂
4. **定期Review**：定期审查和优化Skills
## 相关概念
- [[Harness工程]]：Skills是Harness的组成部分
- [[Agent_as_Code]]：Skills是Agent as Code的组成部分
- [[MCP]]：MCP和Skills都是AI的能力扩展方式

73
AI工程/概念/Spec_Kit.md Executable file
View File

@@ -0,0 +1,73 @@
# Spec Kit
> 相关：[[规格驱动开发]]、[[BMAD]]、[[OpenSpec]]、[[Kiro]]
## 定义
**Spec Kit**是工程化SDD框架，提供Git集成的Spec工作流。
**核心思想**：Spec = 开发入口 + Git生命周期，适合新项目（0→1）。
## 核心特征
### 1. 工程化定位
- Git集成
- 工程化工作流
- 与开发流程紧密结合
### 2. 中粒度Spec
- Feature级规格
- 与Git分支绑定
- 短生命周期
### 3. 中等流程控制
- Plan→Spec→Tasks
- 灵活但有序
- 适合敏捷开发
## 与其他SDD框架对比
| 维度 | [[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） | 存量项目/快速迭代 | 小团队/高自动化 |
| 失控风险 | 低 | 中 | 高 | 中 |
## 适用场景
- **新项目（0→1）**：从零开始的项目
- **中型团队**：需要工程化工作流
- **敏捷开发**：需要灵活但有序的流程
- **Git重度用户**：深度集成Git
## 优势
- **Git集成**：与Git深度集成
- **工程化**：完整的工程化工作流
- **灵活性**：比BMAD更灵活
- **易于上手**：学习曲线相对平缓
## 挑战
- **失控风险中等**：需要一定的流程控制
- **不适合大型项目**：大粒度不如BMAD
- **不适合存量项目**：不如OpenSpec灵活
## 最佳实践
1. **适合新项目**：从零开始的项目最适合
2. **Git工作流**：充分利用Git的分支和PR
3. **团队协作**：团队成员需要理解工作流
4. **持续迭代**：根据实践持续优化流程
## 相关概念
- [[规格驱动开发]]：Spec Kit是SDD框架之一
- [[BMAD]]、[[OpenSpec]]、[[Kiro]]：其他SDD框架

68
AI工程/概念/Trae.md Executable file
View File

@@ -0,0 +1,68 @@
# Trae
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[Claude_Code]]、[[Cursor]]、[[Kiro]]
## 定义
**Trae**是字节跳动推出的AI IDE，集成豆包大模型，中文支持好。
**核心思想**：集成豆包大模型，中文支持好，适合中文项目。
## 核心特征
### 1. 豆包大模型
- 字节跳动自研模型
- 中文理解能力强
- 适合中文项目
### 2. 中文支持好
- 中文文档完善
- 中文社区活跃
- 中文优化
### 3. IDE集成
- 完整的IDE功能
- AI深度集成
- 易于使用
## 与其他AI工具对比
| 工具 | 类型 | 价格 | AI模型 | 适用场景 |
|------|------|------|--------|---------|
| [[Claude_Code]] | CLI | 按Token | Claude | 复杂逻辑 |
| [[Cursor]] | IDE | $20/月 | 多模型 | 日常开发 |
| [[Kiro]] | IDE | 免费+付费 | Claude | AWS项目 |
| Trae | IDE | 免费+付费 | 豆包 | 中文项目 |
## 适用场景
- **中文项目**：中文理解和生成能力强
- **国内团队**：国内团队使用更方便
- **豆包生态**：使用豆包生态的项目
- **成本敏感**：有免费版本
## 优势
- **中文支持好**：中文理解和生成能力强
- **国内团队**：国内团队使用更方便
- **成本较低**：有免费版本
- **豆包生态**：与豆包生态集成
## 挑战
- **国际项目**：不如Claude Code适合国际项目
- **复杂逻辑**：推理能力不如Claude Code
- **生态成熟度**：生态不如Cursor成熟
## 最佳实践
1. **中文项目首选**：中文项目最适合
2. **国内团队**：国内团队使用更方便
3. **豆包生态**：充分利用豆包生态
4. **成本优化**：使用免费版本降低成本
## 相关概念
- [[Harness工程]]：Trae是Harness的工具之一
- [[Agent_as_Code]]：Trae支持Agent as Code
- [[Claude_Code]]、[[Cursor]]、[[Kiro]]：其他AI编程工具

162
AI工程/概念/_概念索引.md Executable file
View File

@@ -0,0 +1,162 @@
# AI工程概念索引
> 本索引收录团队级 AI Coding 相关的所有核心概念
## 基础概念
### [[AI编程演进阶段]]
AI 编程从手动复制到全自动的5个发展阶段
### [[Harness工程]]
为 AI 提供约束体系和外部接口的工程实践
### [[Agent_as_Code]]
将 AI 协作文件以代码方式管理的理念
---
## 开发方法论
### [[Rule约束]]
通过规则文件约束 AI 行为的方法
### [[规格驱动开发]]
以规格文档为核心的开发方法（SDD）
### [[Loop工程]]
AI 自治运行的开发循环
### [[核心Loop]]
Plan → TDD → 验证的开发循环
### [[超级Loop]]
核心Loop + E2E测试验证的扩展循环
---
## 技术概念
### [[过程方案vs事实方案]]
Plans（追加不维护）vs Designs（覆盖更新）
### [[上下文体系]]
AI 协作的文档组织结构
### [[打样工程]]
提供代码模版让 AI 参考生成代码
### [[技术规格DSL]]
领域模型、数据库、API、时序图的标准化表达
---
## 工具与协议
### [[MCP]]
Model Context Protocol，AI 与外部系统通信的标准协议
### [[Skills]]
可复用的 AI 能力单元
### [[AGENTS.md]]
AI 协作的宪法级配置文件
### [[Git_Worktree]]
Git 多工作区并行开发功能
---
## AI工具
### [[Claude_Code]]
Anthropic 出品的 AI 编程工具
### [[Cursor]]
基于 VS Code 的 AI IDE
### [[Kiro]]
AWS 推出的 AI IDE 和 SDD 框架
### [[Trae]]
字节跳动推出的 AI IDE
---
## SDD框架
### [[BMAD]]
企业级 SDD 框架，强治理
### [[Spec_Kit]]
工程化 SDD 框架，Git 集成
### [[OpenSpec]]
轻量级 SDD 框架，灵活
---
## 测试相关
### [[测试策略金字塔]]
Lint → Code Review → 单元测试 → API测试 → E2E测试
### [[Browser_Use]]
AI 操作浏览器的框架
### [[Playwright]]
浏览器自动化测试框架
### [[Computer_Use]]
Anthropic 的 OS 级视觉操作方案
---
## 统计
- 总概念数：28个
- 分类：7大类
- 创建日期：2026-06-20
- 最后更新：2026-06-20
## 概念清单
### 基础概念
- [[AI编程演进阶段]]
- [[Harness工程]]
- [[Agent_as_Code]]
### 开发方法论
- [[Rule约束]]
- [[规格驱动开发]]
- [[Loop工程]]
- [[核心Loop]]
- [[超级Loop]]
### 技术概念
- [[过程方案vs事实方案]]
- [[上下文体系]]
- [[打样工程]]
- [[技术规格DSL]]
### 工具与协议
- [[MCP]]
- [[Skills]]
- [[AGENTS.md]]
- [[Git_Worktree]]
### AI工具
- [[Claude_Code]]
- [[Cursor]]
- [[Kiro]]
- [[Trae]]
### SDD框架
- [[BMAD]]
- [[Spec_Kit]]
- [[OpenSpec]]
### 测试相关
- [[测试策略金字塔]]
- [[Browser_Use]]
- [[Playwright]]
- [[Computer_Use]]

141
AI工程/概念/上下文体系.md Executable file
View File

@@ -0,0 +1,141 @@
# 上下文体系
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[AGENTS.md]]、[[过程方案vs事实方案]]
## 定义
**上下文体系**是AI协作的文档组织结构，通过分层文档为AI提供完整的上下文信息，让AI能够理解和遵循项目规范。
**核心思想**：使用完整的文档来描述上下文和约束体系，区分过程方案和事实方案，减少维护成本。
## 核心特征
### 1. 分层结构
- 宪法级：AGENTS.md
- 标准层：standards/
- 需求层：features/
- 设计层：designs/
- 计划层：plans/
### 2. 引用关系
- 上层文档引用下层文档
- 形成清晰的依赖关系
- AI可以理解完整上下文
### 3. 双轨管理
- 过程方案：Plans（追加不修改）
- 事实方案：Designs（覆盖更新）
## 文档分层结构
```
AGENTS.md ← 宪法（所有AI工具读取）
docs/
├── standards/ ← 标准规格（架构/命名/API/安全规范）
├── features/ ← 需求规格（产品/BA维护）
├── designs/ ← 设计规格（事实方案，Source of Truth）
├── plans/ ← 计划规格（过程方案，追加不修改）
└── others/ ← 架构决策、Release、测试用例等
skills/ ← AI技能（可复用能力单元）
mcp/ ← MCP配置（外部工具接入）
```
## 各层职责
### AGENTS.md（宪法级）
- 定义项目基本信息
- 定义AI行为规则
- 定义目录结构
- 所有AI工具都从这个文件开始
### standards/（标准层）
- 代码风格规范
- API设计规范
- 数据库设计规范
- 安全规范
### features/（需求层）
- 产品需求文档
- 用户故事
- 验收标准
- 由产品/BA维护
### designs/（设计层）
- 数据库设计
- API设计
- 架构设计
- 事实方案，必须保持最新
### plans/（计划层）
- 任务计划
- 实现方案
- 过程方案，追加不修改
### skills/（技能层）
- 可复用的AI能力单元
- 包含提示词、脚本、文档
### mcp/（工具层）
- MCP配置
- 外部工具接入
## 构建引用关系
### 示例：AGENTS.md
```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x
# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
```
### 示例：Plan引用Design
```markdown
# Plan: 实现用户注册功能
## 参考设计
- 数据库设计：../designs/database-schema.md
- API设计：../designs/api-design.md
## 实现方案
根据设计文档实现...
```
## 适用场景
- **团队协作**：多人协作需要统一的上下文
- **复杂项目**：复杂项目需要完整的文档体系
- **长期维护**：长期项目需要持续的上下文管理
- **知识传承**：新成员需要快速理解项目
## 优势
- **完整上下文**：AI可以理解完整的项目背景
- **易于维护**：分层结构，职责清晰
- **可追溯**：文档变更有历史记录
- **可复用**：标准和设计可以在项目间复用
## 挑战
- **初始成本**：需要建立完整的文档体系
- **维护成本**：需要持续维护文档
- **学习曲线**：团队需要理解文档体系
## 最佳实践
1. **从AGENTS.md开始**：先定义最基本的规则
2. **逐步扩展**：根据实践逐步添加文档
3. **明确职责**：每层文档有明确的职责
4. **定期Review**：定期审查和优化文档
5. **保持最新**：事实方案必须保持最新
## 相关概念
- [[Harness工程]]：上下文体系是Harness的组成部分
- [[Agent_as_Code]]：上下文体系是Agent as Code的文档组织
- [[AGENTS.md]]：上下文体系的宪法级文件
- [[过程方案vs事实方案]]：上下文体系的双轨管理方式

153
AI工程/概念/打样工程.md Executable file
View File

@@ -0,0 +1,153 @@
# 打样工程
> 相关：[[Harness工程]]、[[上下文体系]]、[[技术规格DSL]]
## 定义
**打样工程**是提供代码模版和示例，让AI参考生成代码的工程实践。
**核心思想**：让AI"抄作业"，而不是自由发挥，保证代码风格统一、质量稳定。
## 核心原则
1. **约定大于配置**：通过模版约定代码风格
2. **编排逻辑和原子能力分离**：Controller、Service、Repository职责明确
3. **操作者和被操作对象分离**：分层清晰
## 常见工序
### 1. 简单CRUD（无复用逻辑）
```
Controller + Command → AppService → Repository → Response对象
```
**示例**：
```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;
}
```
### 2. 复杂CRUD（有复用逻辑）
```
Controller + Command → AppService → DomainService → Repository → Response对象
```
**示例**：
```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("用户名已存在");
}
}
```
### 3. 复杂查询
```
Controller + Query对象 → AppService → QueryPO（或复用PO）→ Response对象
```
**示例**：
```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
- **输入**：Command/Query对象
- **输出**：Response对象
- **不包含业务逻辑**
### Service层
- **AppService**：应用服务，编排逻辑
- **DomainService**：领域服务，复杂业务逻辑
- **职责**：编排业务逻辑、调用DomainService/Repository
### Repository层
- **职责**：数据持久化
- **输入**：实体对象
- **输出**：实体对象或PO
## 参考代码
- **DDD微服务示例**：https://github.com/domain-driven-design/ddd-microservices
## 为什么需要打样工程
- **AI生成代码质量不稳定**：需要模版约束
- **不同AI工具风格不同**：需要统一风格
- **AI不知道最佳实践**：需要沉淀最佳实践
## 优势
1. **提高代码质量**：基于模版生成，质量有保障
2. **统一代码风格**：所有代码遵循相同的风格
3. **减少Review成本**：代码符合规范，Review更快
4. **知识沉淀**：最佳实践沉淀在模版中
## 挑战
- **初始成本**：需要建立打样工程
- **维护成本**：需要持续维护模版
- **灵活性**：模版可能限制创新
## 最佳实践
1. **建立打样工程**：提供标准的代码模版
2. **分层清晰**：Controller、Service、Repository职责明确
3. **工序标准化**：简单CRUD、复杂CRUD、复杂查询各有标准
4. **AI参考打样**：让AI根据打样工程生成代码
## 相关概念
- [[Harness工程]]：打样工程是Harness的组成部分
- [[上下文体系]]：打样工程是上下文体系的组成部分
- [[技术规格DSL]]：打样工程使用技术规格DSL

220
AI工程/概念/技术规格DSL.md Executable file
View File

@@ -0,0 +1,220 @@
# 技术规格DSL
> 相关：[[规格驱动开发]]、[[Harness工程]]、[[上下文体系]]
## 定义
**技术规格DSL**（Domain Specific Language）是使用领域特定语言编写技术规格的方法，包括领域模型、数据库、API、时序图等。
**核心思想**：使用DSL驱动技术规格，保证一致性和可执行性。
## 5个模块
| 模块 | 表达标准 | 格式 | 产出内容 | 约束/规范 |
|------|---------|------|---------|----------|
| **领域模型** | PlantUML/Smart Domain | .puml | 实体、属性、关系 | 必须表达实体关系；字段需与数据库一致 |
| **数据库** | SQL DDL/DBML/Flyway | .sql | 表结构、索引、约束 | 必须可执行；包含索引和外键 |
| **API** | OpenAPI 3.x | .yaml/.json | 接口定义、请求/响应 | 必须定义schema；字段与模型一致 |
| **时序图** | PlantUML | .puml | 调用流程、系统交互 | 必须反映真实调用链；包含异常分支 |
| **专题设计** | Markdown | .md | 架构策略 | 只写策略与规则；强调设计决策 |
## 领域模型
### 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;
```
### 约束要求
- 必须可执行
- 使用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'
components:
schemas:
CreateUserRequest:
type: object
required: [username, email, password]
properties:
username:
type: string
minLength: 3
maxLength: 50
email:
type: string
format: email
password:
type: string
minLength: 8
```
### 约束要求
- 必须定义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：减少数据库查询
```
### 约束要求
- 只写"策略与规则"
- 不重复API/DDL
- 强调设计决策
## 为什么用DSL
- **可执行**：DDL可以直接运行，OpenAPI可以生成代码
- **AI友好**：LLM对DSL的理解比自然语言更精确
- **一致性保证**：DSL有语法规则，不容易产生歧义
## 适用场景
- **复杂项目**：需要完整的技术规格
- **团队协作**：需要统一的技术规范
- **AI辅助开发**：需要精确的技术规格
## 优势
- **一致性**：领域模型、数据库、API保持一致
- **可执行**：部分DSL可以直接执行
- **AI友好**：AI可以精确理解DSL
- **可维护**：DSL可以版本化
## 挑战
- **学习成本**：需要学习多种DSL
- **维护成本**：需要保持DSL的一致性
- **工具支持**：需要相应的工具支持
## 最佳实践
1. **使用DSL**：统一技术规格的表示方式
2. **保持一致性**：领域模型、数据库、API要一致
3. **AI辅助生成**：让AI根据规格生成代码
4. **版本控制**：技术规格纳入Git管理
## 相关概念
- [[规格驱动开发]]：技术规格DSL是SDD的组成部分
- [[Harness工程]]：技术规格DSL是Harness的组成部分
- [[上下文体系]]：技术规格DSL是上下文体系的组成部分

177
AI工程/概念/核心Loop.md Executable file
View File

@@ -0,0 +1,177 @@
# 核心Loop
> 相关：[[Loop工程]]、[[超级Loop]]、[[Harness工程]]、[[测试策略金字塔]]
## 定义
**核心Loop**是AI编程中AI自治运行的开发循环，通过Plan → TDD → 验证的流程，实现半自动有人值守的开发。
**核心思想**：Plan阶段人机协作，执行阶段AI自治。
## 核心流程
```
开始进入循环
↓
[Chat] 进入Plan模式
↓
装载需求规格，给出指令进行Plan
↓
[Chat] 符合要求，退出Plan模式，开始执行？
↓ 是
[模型] 读取Plan
↓
创建API测试，实现代码
↓
[模型] 运行测试/浏览器调试，是否成功？
↓ 否 → 重复多次/白天持续很久/夜间
↓ 是
[模型] 退出循环
↓
（给予ByPass权限）
```
## 三个阶段
### 阶段1：Plan（规划）
- **输入**：需求规格、技术规格
- **输出**：实现方案、任务列表
- **关键**：关闭所有开放性问题
- **人工介入**：确认Plan是否合理
**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. 发送验证邮件
## 验收标准
- 所有单元测试通过
- 所有API测试通过
- 代码符合阿里巴巴Java开发手册
## 状态
- 开始时间：2026-06-20 10:00
- 预计完成：2026-06-20 12:00
```
### 阶段2：执行（Implementation）
- **输入**：Plan
- **输出**：API测试、实现代码
- **关键**：按照Plan逐步实现
- **AI自治**：无需人工介入
**步骤**：
1. 编写API测试
2. 运行测试（断言失败）
3. 编写实现代码
4. 运行测试（通过）
### 阶段3：验证（Verification）
- **输入**：API测试、实现代码
- **输出**：测试结果、修复建议
- **关键**：所有测试通过
- **AI自治**：自动运行测试，自动修复
## Loop规则
### 1. Plan等待确认
在docs/plans下根据模版创建Plan，等待人工确认。
### 2. 编写API测试
根据Plan实现API测试，运行成功并断言失败。
```java
@Test
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());
}
```
### 3. 编写实现
编写单元测试 + 实现代码，通过编译。
```java
@PostMapping("/users")
public Response<UserResponse> createUser(@RequestBody CreateUserRequest request) {
return Response.success(userAppService.create(request));
}
```
### 4. 运行API测试
运行测试，并修复失败的测试和其他错误。
```bash
mvn test -Dtest=UserApiTest
```
## 退出条件
1. 所有API测试通过
2. 所有单元测试通过
3. 代码符合规范（Lint通过）
4. 没有编译错误
## ByPass权限
AI在某些情况下可以跳过某些步骤：
- 测试环境不可用
- 第三方服务不可用
- 紧急修复
在AGENTS.md中定义ByPass规则。
## 适用场景
- **后端开发**：API开发、业务逻辑实现
- **中等复杂度**：需要TDD驱动的开发
- **团队协作**：需要统一开发流程
## 优势
- **质量可控**：TDD驱动，代码质量有保障
- **可追溯**：Plan记录了实现过程
- **AI自治**：执行阶段无需人工介入
- **持续迭代**：可以快速修复问题
## 挑战
- **Plan质量**：Plan阶段需要充分沟通
- **测试覆盖**：需要编写全面的测试
- **运行时间**：Loop可能需要较长时间
## 最佳实践
1. **Plan阶段充分沟通**：关闭所有开放性问题
2. **TDD驱动**：先写测试再写代码
3. **记录状态**：方便复盘和优化
4. **ByPass控制**：紧急情况可以跳过步骤
## 相关概念
- [[Loop工程]]：核心Loop是Loop工程的具体实现
- [[超级Loop]]：核心Loop的扩展，增加E2E测试
- [[Harness工程]]：核心Loop是Harness的组成部分
- [[测试策略金字塔]]：核心Loop使用的测试策略

99
AI工程/概念/测试策略金字塔.md Executable file
View File

@@ -0,0 +1,99 @@
# 测试策略金字塔
> 相关：[[核心Loop]]、[[超级Loop]]、[[Playwright]]、[[Browser_Use]]
## 定义
**测试策略金字塔**是AI辅助下的分层测试策略，从代码扫描到端到端测试，层层递进。
**核心思想**：分层测试，每层有不同的测试对象和工具。
## 测试层级
| 测试类型 | 测试对象 | 工具（含AI） | 负责人 |
|---------|---------|--------------|-------------------|
| **Lint代码扫描** | 代码风格、代码逻辑和片段 | TS Lint/SonarQube | 程序 |
| **Code Review** | 代码逻辑、架构设计、规范 | GitHub Copilot、Claude Code、CodeRabbit、GitHub PR | 开发者 + AI Review Agent |
| **单元测试** | 函数/类行为、边界条件、异常处理 | JUnit、pytest、Jest + AI生成测试代码 | 开发者 + Test Generation Agent |
| **API测试** | 接口契约、输入输出、鉴权、错误码、业务规则 | Karate（主）、RestAssured（补充） + AI生成测试用例 | QA + 后端开发 + API Test Agent |
| **E2E测试** | 用户关键路径、跨系统流程、前后端联动 | Playwright + AI生成脚本/自愈 | QA + 自动化测试工程师 + E2E Agent |
## AI的作用
### Lint代码扫描
- 自动修复格式问题
- 检测潜在的bug
- 提供修复建议
### Code Review
- 速度快：几分钟内完成审查
- 覆盖广：可以检查多个维度（安全、性能、规范）
- 一致性：不会遗漏
### 单元测试
- 快速生成大量测试用例
- 覆盖边界条件
- 生成Mock数据
### API测试
- 根据OpenAPI规范生成测试用例
- 生成测试数据
- 自动生成断言
### E2E测试
- 生成测试脚本
- 自愈（selector修复）
- 步骤补全
## 测试金字塔演变
### 传统测试金字塔
```
E2E测试（少量）
/ \
/ 集成测试 \
/ （中等数量） \
/ \
/ 单元测试 \
/ （大量） \
/_________________________\
```
### AI时代的测试策略
- **AI生成大量单元测试**：覆盖边界条件
- **AI生成API测试**：基于OpenAPI规范
- **AI操作浏览器做E2E测试**：模拟真实用户
- **人工专注于Code Review**：审查AI的审查结果
## 适用场景
- **所有项目**：都需要分层测试
- **复杂项目**：需要完整的测试金字塔
- **AI辅助开发**：充分利用AI生成测试
## 优势
- **全面覆盖**：从代码到端到端，全面覆盖
- **自动化**：充分利用AI生成测试
- **质量保障**：多层测试保证代码质量
- **效率提升**：AI生成测试提高效率
## 挑战
- **维护成本**：需要维护多层测试
- **运行时间**：完整的测试金字塔运行时间长
- **学习成本**：需要了解多种测试工具和策略
## 最佳实践
1. **分层测试**：单元测试→API测试→E2E测试
2. **AI生成测试**：利用AI快速生成大量测试用例
3. **人工审查**：AI生成的测试需要人工审查
4. **持续集成**：所有测试集成到CI/CD流程
## 相关概念
- [[核心Loop]]：核心Loop使用测试策略金字塔
- [[超级Loop]]：超级Loop扩展了测试策略金字塔
- [[Playwright]]：E2E测试使用的工具
- [[Browser_Use]]：E2E测试使用的工具

150
AI工程/概念/规格驱动开发.md Executable file
View File

@@ -0,0 +1,150 @@
# 规格驱动开发（SDD）
> 相关：[[AI编程演进阶段]]、[[Harness工程]]、[[Rule约束]]、[[BMAD]]、[[Spec_Kit]]、[[OpenSpec]]、[[Kiro]]
## 定义
**规格驱动开发**（Spec-Driven Development，SDD）是AI编程的第3阶段，以规格文档为核心的开发方法。
**核心思想**：Spec是单一事实来源（SSoT），所有开发活动围绕Spec展开。
## 核心特征
### 1. 规格中心化
- Spec是唯一的真相来源
- 所有代码从Spec生成
- Spec变更驱动代码变更
### 2. 结构化表达
- 需求以结构化形式表达
- 使用Markdown、YAML等格式
- 可机器解析和验证
### 3. 文件驱动
- 文件进，文件出
- 规格文件可版本化
- 规格文件可复用
## SDD框架对比
| 维度 | [[BMAD]] | [[Spec_Kit]] | [[OpenSpec]] | [[Kiro]] |
|------|----------|--------------|--------------|----------|
| 定位 | 企业级SDD操作系统 | 工程化Spec工作流 | 轻量Spec层 | IDE原生SDD |
| 理念 | Spec=治理体系+多Agent编排 | Spec=开发入口+Git生命周期 | Spec=变更单元（持续演化） | Spec=可执行源 |
| 生命周期 | 全生命周期 | 与分支绑定（短） | 长期存在（持续） | 持续驱动 |
| 粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
| 可执行 | 流程驱动 | 驱动开发流程 | 类Prompt | 可生成代码+测试 |
| 自动验证 | 无 | 无 | 弱 | 强（内建） |
| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |
## 规格类型
### 1. 需求规格（Feature Spec）
```markdown
# 用户注册功能
## 用户故事
作为一个新用户，我想要注册账号，以便使用系统功能。
## 验收标准
1. 用户可以输入邮箱和密码
2. 系统发送验证邮件
3. 用户点击链接完成验证
4. 验证成功后可以登录
## 字段定义
- email: string, required, unique
- password: string, required, min:8
- verified: boolean, default:false
```
### 2. 设计规格（Design Spec）
```markdown
# 数据库设计
## users表
- id: bigint, primary key
- email: varchar(100), unique
- password: varchar(255)
- verified: tinyint(1), default:0
- created_at: timestamp
- updated_at: timestamp
```
### 3. API规格（API Spec）
```yaml
openapi: 3.0.3
paths:
/api/v1/users:
post:
summary: 创建用户
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
```
## 规格流转
### 过程方案（Plans）
- 每次创建新文件
- 记录实现过程
- 不修改旧文件
- 保留决策轨迹
### 事实方案（Designs）
- 覆盖更新最终态
- 作为下次Plan的起点
- 必须保持最新
- Source of Truth
## 适用场景
### BMAD
- 企业级项目
- 多团队协作
- 强治理需求
- 合规要求高
### Spec Kit
- 新项目（0→1）
- 需要Git集成
- 中等复杂度
### OpenSpec
- 存量项目
- 快速迭代
- 轻量级需求
### Kiro
- 小团队
- 高自动化需求
- AWS项目
## 优势
- **单一真相来源**：避免信息不一致
- **可追溯**：Spec变更有历史记录
- **可验证**：Spec可以生成测试
- **可复用**：Spec可以在项目间复用
## 挑战
- **初始成本**：需要建立完整的Spec体系
- **维护成本**：Spec需要持续更新
- **学习曲线**：团队需要理解SDD理念
## 最佳实践
1. **从核心Spec开始**：先定义最重要的规格
2. **逐步扩展**：根据实践逐步添加规格
3. **定期Review**：定期审查和优化规格
4. **自动化验证**：尽可能自动化Spec验证
## 相关概念
- [[AI编程演进阶段]]：SDD是第3阶段
- [[Harness工程]]：SDD是Harness的组成部分
- [[过程方案vs事实方案]]：SDD的规格管理方式
- [[BMAD]]、[[Spec_Kit]]、[[OpenSpec]]、[[Kiro]]：SDD框架

223
AI工程/概念/超级Loop.md Executable file
View File

@@ -0,0 +1,223 @@
# 超级Loop（E2E Loop）
> 相关：[[核心Loop]]、[[Loop工程]]、[[测试策略金字塔]]、[[Playwright]]、[[Browser_Use]]
## 定义
**超级Loop**是在[[核心Loop]]基础上增加E2E测试验证的扩展循环，确保前后端联动的正确性。
**核心思想**：通过E2E测试纳入更大的Loop范围，验证完整的用户流程。
## 核心流程
```
开始进入循环
↓
[Chat] 进入Plan模式
↓
装载需求规格/界面原型，给出指令进行Plan
↓
[Chat] 符合要求，退出Plan模式，开始执行？
↓ 是
[模型] 读取Plan，按照Loop规则进行实现
↓
[模型] 满足Loop准出要求？
↓ 否 → 重复多次/白天持续很久/夜间
↓ 是
[模型] 退出循环
↓
（给予ByPass权限）
```
## 7个步骤
### 1. Plan等待确认
在docs/plans下根据模版创建Plan。
```markdown
# Plan: 实现用户注册功能（含前端）
## 目标
实现用户注册功能，包括后端API和前端页面
## 任务列表
- [ ] 1. 实现POST /api/v1/users API
- [ ] 2. 实现注册页面 /register
- [ ] 3. 实现表单验证
- [ ] 4. 实现注册成功跳转
- [ ] 5. 编写API测试
- [ ] 6. 编写E2E测试
## 验收标准
- 所有API测试通过
- 所有E2E测试通过
- 前端页面视觉效果符合设计稿
```
### 2. 编写测试用例
在docs/test-cases下编写E2E测试用例。
```markdown
# docs/test-cases/register.md
## 测试用例
### TC-001: 成功注册
1. 访问 /register 页面
2. 输入用户名 testuser
3. 输入邮箱 test@example.com
4. 输入密码 Password123
5. 确认密码 Password123
6. 点击注册按钮
7. 验证跳转到 /login
8. 验证提示"注册成功"
### TC-002: 用户名已存在
1. 访问 /register 页面
2. 输入已存在的用户名 existinguser
3. 点击注册按钮
4. 验证提示"用户名已存在"
```
### 3. 编写API测试
根据Plan实现API测试，运行成功并断言失败。
```java
@Test
void testRegister() {
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());
}
```
### 4. 编写实现
编写后端和前端实现代码。
**后端实现**：
```java
@PostMapping("/users")
public Response<UserResponse> createUser(@RequestBody CreateUserRequest request) {
return Response.success(userAppService.create(request));
}
```
**前端实现**：
```tsx
function RegisterPage() {
const [form] = Form.useForm();
const handleSubmit = async (values) => {
await axios.post('/api/v1/users', values);
message.success('注册成功');
navigate('/login');
};
return (
<Form form={form} onFinish={handleSubmit}>
<Form.Item name="username" rules={[{ required: true }]}>
<Input placeholder="用户名" />
</Form.Item>
<Button type="primary" htmlType="submit">注册</Button>
</Form>
);
}
```
### 5. 运行API测试
运行测试，并修复失败的测试和其他错误。
```bash
mvn test -Dtest=UserApiTest
```
### 6. 浏览器调试
使用[[Playwright]]调试前端，确认视觉效果和交互功能。
```typescript
test('注册页面视觉效果', async ({ page }) => {
await page.goto('/register');
// 截图验证视觉效果
const screenshot = await page.screenshot();
// 调用AI视觉模型验证
// 验证表单验证
await page.fill('[name="email"]', 'invalid-email');
await page.click('button[type="submit"]');
await expect(page.getByText('请输入有效的邮箱')).toBeVisible();
});
```
### 7. 编写E2E测试
编写[[Playwright]] E2E测试，覆盖本轮需求的测试场景。
```typescript
test('完整的注册流程', async ({ page }) => {
await page.goto('/register');
await page.getByLabel('用户名').fill('testuser');
await page.getByLabel('邮箱').fill('test@example.com');
await page.getByLabel('密码').fill('Password123');
await page.getByLabel('确认密码').fill('Password123');
await page.getByRole('button', { name: '注册' }).click();
await expect(page).toHaveURL(/\/login/);
await expect(page.getByText('注册成功')).toBeVisible();
});
```
## 超级Loop vs 核心Loop
| 维度 | [[核心Loop]] | 超级Loop |
|------|-------------|----------|
| 测试范围 | API测试 | API测试 + E2E测试 |
| 验证层次 | 后端逻辑 | 前后端联动 |
| 复杂度 | 中等 | 高 |
| 运行时间 | 几分钟 | 几十分钟到几小时 |
| Token消耗 | 中等 | 高 |
| 适用场景 | 后端开发 | 全栈开发 |
## 适用场景
- **全栈开发**：需要同时开发前后端
- **复杂交互**：需要验证前后端联动
- **用户体验**：需要验证视觉效果
- **完整流程**：需要验证完整的用户流程
## 优势
- **全面验证**：验证前后端联动的正确性
- **用户体验**：验证视觉效果和交互
- **完整流程**：验证完整的用户流程
- **质量保障**：E2E测试保证质量
## 挑战
- **成本高**：运行时间长，Token消耗大
- **维护成本**：E2E测试需要持续维护
- **调试复杂**：需要调试前后端
- **环境依赖**：依赖完整的环境
## 最佳实践
1. **先写测试用例**：明确验收标准
2. **API测试先通过**：确保后端逻辑正确
3. **浏览器调试**：验证前端视觉效果
4. **E2E测试覆盖**：确保前后端联动正确
5. **成本控制**：仅在必要时使用
## 相关概念
- [[核心Loop]]：超级Loop基于核心Loop
- [[Loop工程]]：超级Loop是Loop工程的扩展
- [[测试策略金字塔]]：超级Loop使用的测试策略
- [[Playwright]]：超级Loop使用的E2E测试工具
- [[Browser_Use]]：超级Loop可能使用的浏览器自动化工具

170
AI工程/概念/过程方案vs事实方案.md Executable file
View File

@@ -0,0 +1,170 @@
# 过程方案vs事实方案
> 相关：[[规格驱动开发]]、[[上下文体系]]、[[Harness工程]]
## 定义
**过程方案**和**事实方案**是[[规格驱动开发]]中两种不同的规格管理方式。
- **过程方案（Plans）**：记录实现过程，每次新建文件，用完即弃
- **事实方案（Designs）**：记录系统真相，覆盖更新，长期维护
## 核心区别
| 维度 | 过程方案（Plans） | 事实方案（Designs） |
|------|------------------|-------------------|
| 目的 | 记录实现过程 | 记录当前状态 |
| 更新方式 | 追加新文件 | 覆盖更新 |
| 生命周期 | 短期（任务完成后归档） | 长期（持续维护） |
| 维护成本 | 低（不修改旧文件） | 高（必须保持最新） |
| 使用场景 | 任务执行、问题排查 | 新功能开发、架构决策 |
| 示例 | plan-2026-06-20-feature-x.md | database-schema.md |
## 过程方案（Plans）
### 特征
- 每次任务创建新文件
- 文件命名包含日期：`plan-YYYY-MM-DD-feature-name.md`
- 任务完成后移动到`archive/`目录
- 不修改旧文件，保留决策轨迹
### 内容结构
```markdown
# Plan: 实现用户注册功能
## 目标
实现用户注册API，支持邮箱验证
## 任务列表
- [ ] 1. 创建数据库表users
- [ ] 2. 实现POST /api/v1/users API
- [ ] 3. 实现邮箱验证逻辑
## 实现方案
1. 使用Flyway创建users表
2. Controller接收CreateUserCommand
3. AppService调用UserRepository保存
## 状态
- 开始时间：2026-06-20 10:00
- 预计完成：2026-06-20 12:00
- 实际完成：2026-06-20 11:30
## 问题记录
- 10:30 发现数据库连接池配置问题
- 11:00 邮箱服务超时，增加重试机制
```
### 最佳实践
- **命名规范**：`plan-YYYY-MM-DD-feature-name.md`
- **内容结构**：目标、方案、任务列表、状态、问题记录
- **归档策略**：任务完成后移动到`archive/`目录
## 事实方案（Designs）
### 特征
- 每次覆盖更新
- 文件命名使用功能名称：`database-schema.md`
- 必须保持最新状态
- 作为下次Plan的事实依据
### 内容结构
```markdown
# 数据库设计
## 概述
系统数据库设计，包含用户、角色、权限等表。
## users表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| username | varchar(50) | 用户名，唯一 |
| email | varchar(100) | 邮箱，唯一 |
| password | varchar(255) | 密码，加密存储 |
| status | tinyint(1) | 状态：0-禁用，1-启用 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |
## roles表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| name | varchar(20) | 角色名称 |
## 变更历史
- 2026-06-20：添加users表
- 2026-06-21：添加roles表
- 2026-06-22：添加user_roles关联表
```
### 最佳实践
- **命名规范**：使用功能名称，如`database-schema.md`
- **内容结构**：概述、详细设计、变更历史
- **更新策略**：每次变更必须更新文档，保持最新
## 目录结构
```
docs/
├── standards/ # 标准规格（事实方案）
├── features/ # 需求规格（事实方案）
├── designs/ # 设计规格（事实方案）
├── plans/ # 计划规格（过程方案）
│ ├── archive/ # 归档的计划
│ └── plan-2026-06-20-feature-x.md
└── others/ # 架构决策、Release、测试用例等
```
## 使用策略
### 何时使用过程方案
- 任务执行过程记录
- 问题排查记录
- 决策轨迹记录
- 临时方案记录
### 何时使用事实方案
- 数据库设计
- API设计
- 架构设计
- 标准规范
- 需求规格
## 优势与局限
### 过程方案
**优势**：
- 维护成本低
- 保留决策轨迹
- 易于追溯历史
**局限**：
- 文件数量多
- 需要定期归档
- 不反映当前状态
### 事实方案
**优势**：
- 反映当前状态
- 单一真相来源
- 易于理解
**局限**：
- 维护成本高
- 需要持续更新
- 丢失历史信息
## 最佳实践
1. **明确区分**：清楚区分哪些是过程方案，哪些是事实方案
2. **定期归档**：过程方案定期归档到`archive/`目录
3. **保持最新**：事实方案必须保持最新状态
4. **变更历史**：事实方案记录变更历史
5. **关联引用**：Plans引用Designs，确保一致性
## 相关概念
- [[规格驱动开发]]：过程方案和事实方案是SDD的规格管理方式
- [[上下文体系]]：过程方案和事实方案是上下文体系的组成部分
- [[Harness工程]]：过程方案和事实方案是Harness的文档管理方式