audio_codebuddy/.codebuddy/rules/harness.mdc

---
description: 
alwaysApply: true
enabled: true
updatedAt: 2026-04-04T00:38:45.522Z
provider: 
---

# 长时运行代理规则

## 核心原则

1. **双 Agent 架构**：Initializer Agent（仅首次）+ Coding Agent（后续所有会话）
2. **外部持久化**：所有进度必须写入文件，不依赖 AI 记忆
3. **增量开发**：每次会话只完成 1 个功能
4. **状态流转**：功能状态按流程逐步推进（start → 编译 → 运行 → 数据库 → 测试 → done）
5. **自动执行**：AI 必须自动执行所有命令，禁止输出命令让用户手动执行
6. **失败处理**：验证失败 → 记录状态 → 修复 → 重新执行该环节

---

## 功能状态定义

### 状态流转图

```
init → start → compiling → running → db-checking → backend-testing → frontend-testing → done
  ↓       ↓         ↓          ↓            ↓            ↓              ↓              ↓      ↓
初始化  开始开发  编译中    运行中     数据库验证中   后端测试中    前端测试中      完成
```

### 状态说明

| 状态 | 含义 | 下一步 |
|------|------|--------|
| `init` | 功能已创建，未开始 | → `start` |
| `start` | 开始开发 | → `compiling` |
| `compiling` | 编译中/编译失败 | 成功 → `running`，失败 → 修复 |
| `running` | 运行中/运行失败 | 成功 → `db-checking`，失败 → 修复 |
| `db-checking` | 数据库验证中/失败 | 成功 → `backend-testing`，失败 → 修复 |
| `backend-testing` | 后端接口测试中/失败 | 成功 → `frontend-testing`，失败 → 修复 |
| `frontend-testing` | 前端页面测试中/失败 | 成功 → `done`，失败 → 修复 |
| `done` | 功能完成 | - |

### 测试阶段说明

**为什么测试要分开**：
> - **后端测试**：使用 curl 测试 API 接口，验证业务逻辑
> - **前端测试**：使用浏览器自动化测试用户交互，验证页面功能
> 
> **顺序要求**：
> 1. 先测后端接口 → 确保 API 正常
> 2. 再测前端页面 → 确保交互正常
> 
> **原因**：如果后端接口都有问题，前端测试没有意义

---

## Initializer Agent 规则

### 职责（仅第一次运行）

**核心原则：AI 必须自动执行所有初始化步骤，禁止让用户手动操作**

1. **生成 `init.sh`**：安装依赖、初始化数据库、启动服务
2. **生成 `claude-progress.txt`**：进度日志
3. **生成 `feature_list.json`**：100-200+ 细粒度功能清单（JSON 格式）
4. **初始化 Git**：
   ```bash
   git init
   git add .
   git commit -m "initial: 初始化项目"
   git branch main
   ```
5. **自动执行初始化**（关键！禁止输出命令让用户执行）：
   ```bash
   # 5.1 初始化数据库
   mysql -u root -p123456 < database/init.sql
   
   # 5.2 安装后端依赖
   cd backend && mvn install
   
   # 5.3 安装前端依赖（包括 Playwright）
   cd ../frontend && npm install && npx playwright install chromium
   
   # 5.4 启动后端（后台运行）
   cd backend && mvn spring-boot:run &
   
   # 5.5 启动前端（后台运行）
   cd ../frontend && npm run dev &
   
   # 5.6 等待服务启动
   sleep 15
   
   # 5.7 验证服务可用性
   curl -f http://localhost:8000/health
   curl -f http://localhost:8080
   python db_check.py
   ```

### 禁止行为
- ❌ 编写功能代码
- ❌ 跳过任何工件生成
- ❌ 使用占位符
- ❌ **输出初始化命令让用户手动执行**
- ❌ **说"启动方式"、"访问地址"等，而不实际执行**

---

## Coding Agent 规则

### 标准流程（按顺序执行，禁止跳步）

#### 步骤 1：读取状态
```bash
pwd
cat claude-progress.txt
cat feature_list.json
git log --oneline -20
```

#### 步骤 2：选择功能
- 从 `feature_list.json` 选择最小 id 的未完成功能
- 查看当前状态（应该是 `init` 或 `start`）
- **只做这一条**

#### 步骤 3：更新状态为 `start`
```bash
# 修改 feature_list.json
{
  "id": X,
  "status": "start",  # 更新为 start
  "description": "功能描述"
}

# 记录日志
echo "[时间戳] 开始功能 X：功能描述" >> claude-progress.txt
```

#### 步骤 4：开发功能
- 编写代码

#### 步骤 5：编译验证（更新状态为 `compiling`）
```bash
# 先更新状态
{
  "id": X,
  "status": "compiling"  # 更新为 compiling
}

# 执行编译
python -m py_compile backend/*.py
# 或
npm run build
```

**编译结果处理**：
- ✅ 成功 → 更新状态为 `running`，进入步骤 6
- ❌ 失败 → 保持 `compiling` 状态，记录错误，修复后重新编译

#### 步骤 6：运行验证（更新状态为 `running`）
```bash
# 先更新状态
{
  "id": X,
  "status": "running"  # 更新为 running
}

# 执行运行验证
pkill -f "python.*main.py" || true
pkill -f "npm.*dev" || true
sleep 2
./init.sh
sleep 10

curl -f http://localhost:8000/health
curl -f http://localhost:8080
```

**运行结果处理**：
- ✅ 成功 → 更新状态为 `db-checking`，进入步骤 7
- ❌ 失败 → 保持 `running` 状态，记录错误，修复后重新运行

#### 步骤 7：数据库验证（更新状态为 `db-checking`）
```bash
# 先更新状态
{
  "id": X,
  "status": "db-checking"  # 更新为 db-checking
}

# 执行数据库验证
python backend/db_check.py
python -c "from backend.db import DB; db = DB(); db.test_connection()"
```

**数据库结果处理**：
- ✅ 成功 → 更新状态为 `testing`，进入步骤 8
- ❌ 失败 → 保持 `db-checking` 状态，记录错误，修复后重新验证

#### 步骤 8：后端接口测试（更新状态为 `backend-testing`）
```bash
# 先更新状态
{
  "id": X,
  "status": "backend-testing"  # 更新为 backend-testing
}

# 使用 curl 测试后端接口
# 按照 feature_list.json 中 backend_test_steps 逐项测试
curl -s http://localhost:8000/api/chats/new | jq '.status' | grep -q "success"
curl -f http://localhost:8000/health
```

**后端测试要求**：
> - 必须按照 backend_test_steps 逐项测试
> - 使用 curl 测试 API 接口
> - 验证接口返回状态码和数据格式

**后端测试结果处理**：
- ✅ 成功 → 更新状态为 `frontend-testing`，进入步骤 9
- ❌ 失败 → 保持 `backend-testing` 状态，记录错误，修复后端接口后重新测试

#### 步骤 9：前端页面测试（更新状态为 `frontend-testing`）
```bash
# 先更新状态
{
  "id": X,
  "status": "frontend-testing"  # 更新为 frontend-testing
}

# 复制模板并修改
cp .codebuddy/rules/frontend-test-template.js tests/test-frontend.js

# 根据当前功能的 frontend_test_steps 修改测试内容
# 然后执行浏览器自动化测试
node tests/test-frontend.js
```

**前端测试要求**：
> - 必须按照 frontend_test_steps 逐项测试
> - 使用浏览器自动化（Playwright/Puppeteer）
> - 模拟真实用户操作

**前端测试结果处理**：
- ✅ 成功 → 更新状态为 `done`，进入步骤 10
- ❌ 失败 → 保持 `frontend-testing` 状态，记录错误，修复前端后重新测试

#### 步骤 10：功能完成（更新状态为 `done`）
```bash
# 更新 feature_list.json
{
  "id": X,
  "status": "done",  # 更新为 done
  "passes": true
}

# 更新日志
echo "[时间戳] 功能 X 完成 | 状态流转：start→compiling→running→db-checking→backend-testing→frontend-testing→done" >> claude-progress.txt

# Git 提交
git add .
git commit -m "feat: 完成功能 X | 状态流转：start→compiling→running→db-checking→backend-testing→frontend-testing→done"
```

### 状态流转规则

**核心原则**：
> 状态必须逐步流转，不能跳跃
> 
> 每个环节失败 → 保持当前状态 → 修复 → 重新执行该环节
> 
> 只有该环节成功 → 才能更新为下一个状态

**状态流转示例**：
```
功能 1: init → start → compiling → running → db-checking → testing → done ✅
功能 2: init → start → compiling → (失败) → 修复 → compiling → running → ...
功能 3: init → start → compiling → running → (失败) → 修复 → running → ...
```

### 禁止行为
- ❌ 每次做多个功能
- ❌ **跳过状态直接更新为 done**
- ❌ **不执行验证流程**
- ❌ 不编译就测试
- ❌ 不运行就测试
- ❌ 不验证数据库连接
- ❌ **前端功能测试只用 curl**
- ❌ **不执行前端浏览器自动化测试**
- ❌ 不测试就标记 done
- ❌ 删除/修改 backend_test_steps（后端接口测试步骤）
- ❌ 删除/修改 frontend_test_steps（前端页面测试步骤）
- ❌ **验证失败不修复**
- ❌ **输出初始化/启动命令让用户手动执行**
- ❌ **说"启动方式"、"访问地址"、"请执行"等**

---

## passes: true 的条件

只有状态流转到 `done`，才允许设置 `passes: true`：

```json
{
  "id": X,
  "status": "done",
  "passes": true
}
```

**状态流转要求**：
> 必须经历完整流程：start → compiling → running → db-checking → backend-testing → frontend-testing → done
> 
> 不允许跳跃状态
> 
> 失败时保持当前状态，修复后重新执行

**测试阶段要求**：
> - 先测后端接口 → 确保 API 正常
> - 再测前端页面 → 确保交互正常
> - 后端测试失败 → 禁止进入前端测试

---

## 工件规范

### feature_list.json
```json
{
  "project_name": "项目名称",
  "base_config": {
    "backend_port": 8000,
    "frontend_port": 8080,
    "db_host": "localhost",
    "db_port": 3306
  },
  "features": [
    {
      "id": 1,
      "description": "功能描述",
      "backend_test_steps": [
        "1. curl POST /api/chats/new - 验证创建聊天接口返回 200",
        "2. curl GET /api/chats - 验证获取聊天列表接口返回 200",
        "3. curl POST /api/messages - 验证发送消息接口返回 200"
      ],
      "frontend_test_steps": [
        "1. 点击'新聊天'按钮",
        "2. 验证新聊天窗口创建",
        "3. 输入消息内容",
        "4. 点击'发送'按钮",
        "5. 验证消息显示在聊天窗口"
      ],
      "status": "init",
      "passes": false
    }
  ]
}
```

**更新规则**：
- ✅ 只允许按流程更新 status 字段
- ✅ 只有 status 为 done 时才可修改 passes: true
- ❌ 禁止删除功能
- ❌ 禁止删除或修改 backend_test_steps
- ❌ 禁止删除或修改 frontend_test_steps
- ❌ 禁止合并功能

**重要说明**：
> 每个功能必须包含 backend_test_steps（后端接口测试）和 frontend_test_steps（前端页面测试）
> - backend_test_steps：使用 curl 测试 API 接口
> - frontend_test_steps：使用浏览器自动化测试用户交互

### claude-progress.txt
```
[时间戳] 初始化完成
[时间戳] 开始功能 1：功能描述 | 状态：init→start
[时间戳] 功能 1 编译中 | 状态：start→compiling
[时间戳] 功能 1 编译失败 | 错误：XXX | 状态：compiling
[时间戳] 功能 1 编译成功 | 状态：compiling→running
[时间戳] 功能 1 运行成功 | 状态：running→db-checking
[时间戳] 功能 1 数据库验证成功 | 状态：db-checking→backend-testing
[时间戳] 功能 1 后端接口测试成功 | 状态：backend-testing→frontend-testing
[时间戳] 功能 1 前端页面测试成功 | 状态：frontend-testing→done
[时间戳] 功能 1 完成 | passes: false→true
```

**更新规则**：
- ✅ 每次会话追加新记录
- ✅ 记录状态流转过程
- ✅ 记录失败和修复
- ❌ 禁止删除历史记录

### init.sh
- 格式：Bash 脚本
- 位置：项目根目录
- 要求：
  - ✅ 一键启动项目
  - ✅ 安装依赖（固定版本）
  - ✅ 启动开发服务器
  - ✅ 运行基础测试

### Git
- 提交频率：每次功能完成后
- 提交信息：
  ```
  initial: 初始化项目
  feat: 完成功能 X | 状态流转：start→compiling→running→db-checking→backend-testing→frontend-testing→done
  fix: 修复功能 X | 状态：backend-testing (修复后端接口)
  fix: 修复功能 X | 状态：frontend-testing (修复前端页面)
  ```

---

## 失败模式处理

| 问题 | 处理 |
|------|------|
| 过早宣布完成 | 必须按 feature_list.json 顺序完成 |
| 一次做多个功能 | 每次只做 1 个 |
| 留下 Bug | 每次会话前运行基础测试 |
| 过早标记完成 | 必须状态流转到 done |
| 数据库连不上 | 保持 db-checking 状态，修复后重新验证 |
| 后端接口失败 | 保持 backend-testing 状态，修复后重新测试 |
| 前端页面失败 | 保持 frontend-testing 状态，修复后重新测试 |
| AI 推卸责任 | 立即纠正，必须自动执行命令 |
| 一次性通过太难 | 使用状态流转，逐步推进 |

---

## 违规处理

以下行为禁止，发现后立即纠正：

1. ❌ 每次做多个功能 → 回退，重新按流程执行
2. ❌ 跳过状态直接 done → 回退，重新执行流程
3. ❌ 跳过测试阶段（后端→前端） → 回退，重新测试
4. ❌ 不测试就标记 done → 重新测试
5. ❌ 删除/修改 backend_test_steps → 恢复原文件
6. ❌ 删除/修改 frontend_test_steps → 恢复原文件
7. ❌ 不更新进度日志 → 补充更新
8. ❌ 留下 Bug → 立即修复或回退
9. ❌ 数据库失败还标记 done → 回退，修复数据库
10. ❌ 后端测试失败就测前端 → 回退，先修复后端
11. ❌ 输出命令让用户执行 → 立即纠正，AI 必须自己执行