audio_codebuddy/CLAUDE.MD

---

description: alwaysApply: true enabled: true updatedAt: 2026-04-04T02:08:26.852Z

provider:

长时运行代理规则

核心原则

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

状态流转

init → start → compiling → running → db-checking → backend-testing → frontend-testing → done
                                                    ↑                      ↑
                                              【后端测试】          【前端测试⚠️】

状态	含义
init	功能已创建，未开始
start	开始开发
compiling	编译中
running	运行中
db-checking	数据库验证中
backend-testing	后端接口测试中（用 curl）
frontend-testing	前端页面测试中（用 Playwright）⚠️
done	功能完成

⚠️ 注意：必须测试前端页面，不能只用 curl 测试后端就结束

---

Initializer Agent 规则

职责（仅第一次运行）

1. 生成 init.sh：安装依赖、初始化数据库、启动服务
2. 生成 agent-progress.txt：进度日志
3. 生成 feature_list.json：细粒度功能清单（JSON 格式）
4. 初始化 Git：创建仓库并提交
5. 自动执行初始化：启动服务并验证

禁止行为

• ❌ 编写功能代码
• ❌ 跳过任何工件生成
• ❌ 使用占位符
• ❌ 输出命令让用户手动执行

---

Coding Agent 规则

标准流程（按顺序执行）

步骤 1：读取状态

pwd
cat agent-progress.txt
cat feature_list.json
git log --oneline -20

步骤 2：选择功能

• 从 feature_list.json 选择最小 id 的未完成功能
• 只做这一条

步骤 3：更新状态为 start

# 修改 feature_list.json: status: "start"
# 记录日志

步骤 4：开发功能

• 编写代码

步骤 5：编译验证（状态 → compiling）

# 根据项目类型执行编译
python -m py_compile backend/*.py  # Python
npm run build  # Node.js/TS
mvn compile  # Java

• 成功 → 更新状态为 running
• 失败 → 修复 → 重新编译

步骤 6：运行验证（状态 → running）

# 重启服务
./init.sh
sleep 10

# 验证服务可用
curl -f http://localhost:{backend_port}/health
curl -f http://localhost:{frontend_port}

• 成功 → 更新状态为 db-checking
• 失败 → 修复 → 重新运行

步骤 7：数据库验证（状态 → db-checking）

python backend/db_check.py

• 成功 → 更新状态为 backend-testing
• 失败 → 修复 → 重新验证

步骤 8：后端接口测试（状态 → backend-testing）

# 按照 backend_test_steps 逐项测试
# 必须包含增删改查（CRUD）

• 成功 → 更新状态为 frontend-testing
• 失败 → 修复 → 重新测试

后端测试要求：

• 必须包含增删改查（Create/Read/Update/Delete）
• 使用 curl 测试 API 接口
• 开发阶段 auth_enabled: false，跳过 token 验证

⚠️ 步骤 9：前端页面测试（状态 → frontend-testing）⚠️

【必须测试前端，禁止跳过此步骤】

# 使用 Playwright 进行浏览器自动化测试
npx playwright test

• 成功 → 更新状态为 done
• 失败 → 修复 → 重新测试

前端测试要求：

• 必须使用 Playwright 或 Playwright cli
• ❌ 禁止使用 curl 测试前端（curl 只能测后端）

步骤 10：功能完成（状态 → done）

# 修改 feature_list.json: status: "done", passes: true
# 更新日志
# Git 提交

禁止行为

• ❌ 每次做多个功能
• ❌ 跳过状态直接 done
• ❌ 不编译就测试
• ❌ 不运行就测试
• ❌ 不验证数据库连接
• ❌ 忘记测试前端（只测后端，不测前端）
• ❌ 用 curl 测试前端页面（禁止 curl 测试前端）
• ❌ 删除/修改 backend_test_steps
• ❌ 删除/修改 frontend_test_steps
• ❌ backend_test_steps 不包含增删改查
• ❌ 输出命令让用户手动执行

---

工件规范

feature_list.json

{
  "project_name": "项目名称",
  "base_config": {
    "backend_port": "{根据实际项目配置}",
    "frontend_port": "{根据实际项目配置}",
    "db_host": "localhost",
    "db_port": 3306,
    "auth_enabled": false
  },
  "features": [
    {
      "id": 1,
      "description": "功能描述",
      "backend_test_steps": [
        "1. curl POST /api/chats - 验证创建（增）",
        "2. curl GET /api/chats - 验证查询（查）",
        "3. curl PUT /api/chats/{id} - 验证更新（改）",
        "4. curl DELETE /api/chats/{id} - 验证删除（删）"
      ],
      "frontend_test_steps": [
        "1. 点击按钮",
        "2. 验证结果"
      ],
      "status": "init",
      "passes": false
    }
  ]
}

agent-progress.txt

• 格式：纯文本
• 要求：每次会话追加记录，保留所有历史

init.sh

• 格式：Bash 脚本
• 要求：一键启动项目、安装依赖、启动服务、运行测试

Git

• 提交频率：每次功能完成后

---

权限验证配置

• auth_enabled: false：开发阶段，跳过登录验证 token
• auth_enabled: true：生产阶段，开启登录验证 token

建议：开发阶段关闭 auth_enabled，等核心功能完成后再开启