mini-starter/CLAUDE.md

开发环境说明

• 多八多云端开发容器环境
• Node.js 20.19.2
• PostgresSQL 17 (默认数据库: postgres)
• Redis 7
• MinIO(默认存储桶: d8dai)
• 所有服务使用默认参数连接，正式环境参数相同
• 默认开放8080端口供外网访问

• 开发服务器在8080端口默认开机自动启动，无需手动启动

• Claude Code

• use pnpm

• 数据库在同一容器组的另一个容器中，需要运行 psql -h 127.0.0.1 -U postgres 来访问

• vitest中，只有console.debug会显示，其他的都屏蔽了

• vitest中，用import 来配合 vi.mocked，而不是require

• E2E测试:

  • 推荐使用子代理运行: 运行 Playwright E2E 测试时，使用 Task 工具的 Bash 子代理方式运行，速度更快且多个 Playwright 进程不会冲突
  • 示例提示词: "在 web 目录下运行 pnpm exec playwright test --config=tests/e2e/playwright.config.ts --project=chromium --grep \"测试名称\""
  • 运行所有E2E测试: pnpm test:e2e:chromium
  • 运行单个测试文件: pnpm test:e2e:chromium <测试文件名> (如: pnpm test:e2e:chromium disability-person-complete)
  • 快速失败模式 (推荐调试时使用): 使用 Linux timeout 命令限制总运行时间
  • timeout 30 pnpm test:e2e:chromium (所有测试，30秒后中断)
  • timeout 60 pnpm test:e2e:chromium disability-person-complete (单文件测试，60秒后中断)
  • E2E测试失败时先查看页面结构 test-results/**/error-context.md
  • E2E测试在 web 目录下运行: cd web && pnpm test:e2e:chromium
  • 配置文件超时: playwright.config.ts 中已设置 timeout: 60000 (60秒，单个测试的默认超时)

• 前端是 hono/client hc rpc 的，不是直接fetch

• project-context.md 路径: _bmad-output/project-context.md

• 必须用中文回答

• git提交: 当遇到git锁文件冲突时，使用单条命令：rm -f /mnt/code/184-172-template-6/.git/index.lock && git add <文件> && git commit -m "提交信息"

• 测试调试: 使用 pnpm test --testNamePattern "测试名称" 来运行特定测试查看详细信息 (mini使用Jest，其他包使用Vitest)

  • Vitest: 支持 -t 或 --testNamePattern
  • Jest: 只支持 --testNamePattern，mini是Jest
  • Mini测试: 需要先进入mini目录再运行 pnpm test --testNamePattern "测试名称"

• 表单调试: 表单提交失败时，在表单form onsubmit=form.handleSubmit的第二个参数中加console.debug来看表单验证错误，例如：form.handleSubmit(handleSubmit, (errors) => console.debug('表单验证错误:', errors))

• 类型检查 可以用 pnpm typecheck 加 grep来过滤要检查的 指定文件

• 长文档分段生成: 如果文档（如 story 文档）太长一次生成不完，应该分段生成：

  1. 先使用 Write 工具创建文件的基础部分（header、requirements）
  2. 使用 Edit 工具逐步添加其他部分（dev notes、references、dev agent record 等）
  3. 每次添加一个主要部分，确保不会超过单次生成的长度限制

---

工具调用最佳实践

Playwright E2E 测试

• 推荐方式：使用 Task 工具调用 Bash 子代理运行 E2E 测试
• 优点：
  • 速度快，在独立上下文中执行
  • 多个 Playwright 测试之间不会冲突
  • 方便并行运行多个测试

• 示例：

  // 使用 Task 工具 + Bash 子代理
  Task({
  subagent_type: "Bash",
  prompt: "在 web 目录下运行 pnpm exec playwright test --config=tests/e2e/playwright.config.ts --project=chromium --grep \"测试名称\""
  })
  

BMM 工作流指令

• 推荐方式：使用 Task 工具调用 general-purpose 子代理执行 BMM 指令
• 优点：
  • 在独立上下文中执行，不干扰主对话
  • 完整的工作流状态管理
  • 方便处理复杂的多步骤流程

• 示例：

  // 使用 Task 工具 + general-purpose 子代理
  Skill({
  skill: "bmad:bmm:workflows:dev-story"
  })