我用 Claude Code + Superpowers 开发国标麻将能力提升平台全记录

我用 Claude Code + Superpowers 开发国标麻将能力提升平台全记录

本文记录了一个从 0 到 1 用 AI 辅助开发完整 Web 项目的真实历程——包括脑暴、架构、规则引擎、后端 API、前端对战界面、复盘分析、知识中心、个人成长系统的全流程，以及踩过的坑和积累的最佳实践。

---

项目简介

国标麻将能力提升平台：一个以「打 → 学 → 复盘 → 成长」为核心闭环的在线平台。

• 1v3 人机对战（国标竞技麻将规则，136 张牌，8 番起和）
• 实时出牌建议（AI 高亮最优打法并给出理由）
• 对局后自动生成复盘报告（Claude API 自然语言讲解）
• 知识学习中心（81 种番型 + 策略文章 + 练习题）
• 个人成长系统（技能雷达图、等级成就、弱点诊断）

技术栈： React 18 + TypeScript + FastAPI + PostgreSQL + Redis + Docker

链接	地址
在线体验	http://121.40.121.91
开源仓库	github.com/ooaaooaa123…

---

目录

1. 为什么做这个项目
2. 用到的工具链
3. 开发历程
   • 3.1 脑暴阶段：先想清楚再动手
   • 3.2 架构设计与文档沉淀
   • 3.3 P0：国标规则引擎（已完成）
   • 3.4 P1：后端 API + WebSocket + AI 策略（已完成）
   • 3.5 P2：前端对战界面（已完成）
   • 3.6 P3：复盘分析 + Claude 讲解（已完成）
   • 3.7 P4：知识中心 + 个人成长系统（已完成）
4. Claude Code 高级功能实战
   • 4.1 Superpowers Skills：让 AI 先想再做
   • 4.2 Subagents：一人干一件事
   • 4.3 Playwright MCP：AI 自主验收
   • 4.4 Memory：跨对话的项目记忆
5. Harness Engineering：让 Agent 在轨道上跑
6. 踩过的坑
   • 坑 1：没有提前配置 settings.local.json
   • 坑 2：Hit Limit 后无法自动恢复
   • 坑 3：AI 自动下载了 Chrome
   • 坑 4：P1/P2 串行开发，其实可以并行
   • 坑 5：部署踩坑集锦
7. Vibe Coding 最佳实践
8. 结语 & 求职

---

1. 为什么做这个项目

我打麻将好几年了，但一直停在「靠感觉打」的阶段——不知道自己的向听数，不会估算危险牌，更不清楚为什么输了。

市面上有些麻将 App，但要么规则是地方麻将，要么没有系统的训练功能。国标竞技麻将（中国麻将协会竞赛规则）的学习平台几乎是空白。

于是决定：自己做一个。

不过我不是从零手写——整个项目全程用 Claude Code 开发。这篇文章就是这个过程的完整记录。

---

2. 用到的工具链

Claude Code CLI

全程使用 Claude Code CLI，模型为 Claude Sonnet 4.6

Superpowers Skills

Superpowers 是一套 Claude Code 的 Skills 插件，核心价值是让 AI 在动手之前先思考。

我用到的 Skills：

Skill	作用
brainstorming	多轮对话脑暴，帮你想清楚做什么、怎么做
writing-plans	把需求拆成带测试的逐步实现计划
subagent-driven-development	派发子 Agent 执行每个任务，双阶段 Review

Playwright MCP

claude mcp add playwright npx @playwright/mcp@latest

配置后 Claude 可以自主操控浏览器：打开页面、点击按钮、填写表单、截图验证。大幅减少"写代码 → 我手动看效果 → 反馈给 AI"的来回。

Memory 系统

Claude Code 内置持久化 Memory，跨对话保留项目上下文——我的技术偏好、踩过的坑、项目进度，不用每次对话都重新解释。

---

3. 开发历程

3.1 脑暴阶段：先想清楚再动手

最开始我只有一个模糊的想法：「做个麻将学习网站」。直接让 AI 动手写代码，100% 会跑偏。

所以第一步是调用 brainstorming skill，进入结构化脑暴模式。AI 不是直接给方案，而是通过一系列选择题帮我对齐：

目标用户？
A. 完全新手（需要教规则）
B. 有基础、想提升（不需要教基础，注重实战训练）
C. 专业选手（需要对局分析）

几轮问答之后，我们对齐了：

• 目标用户：有基础的玩家（B级），想提升实战水平
• 玩法范围：国标竞技麻将（136 张，无花牌，8 番起和）
• AI 策略等级：策略级（启发式 + 蒙特卡洛）
• 第一版核心：AI 对战练习
• 平台：纯 Web（PC 优先）

这个过程大概花了 20 分钟，但省去了后续无数次「啊，我不是这个意思」的返工。

3.2 架构设计与文档沉淀

脑暴完成后，AI 输出了完整的设计规格文档（docs/superpowers/specs/2026-04-16-majiang-platform-design.md），内容包括：

• 四大功能模块详细需求
• 技术架构图（前端/后端/AI引擎/数据层）
• 数据库 Schema
• WebSocket 消息协议
• 错误处理策略
• P0-P4 分阶段计划

我还让 AI 额外生成了一个独立的 HTML 架构图（docs/architecture-overview.html），方便展示给别人看。

关键决策：规格文档初版把「花牌」写进去了，但国标竞技规则不用花牌（136 张，非 144 张）。发现后立即修正，避免后续规则引擎写错。

3.3 P0：国标规则引擎

P0 是整个项目的基石：没有正确的规则引擎，后面所有的游戏逻辑都是建立在沙滩上。

AI 生成的实现计划（docs/superpowers/plans/2026-04-16-p0-rule-engine.md）把 P0 拆成 9 个任务：

Task 1: 项目脚手架（pyproject.toml + venv + 目录结构）
Task 2: Tile 数据模型（牌面表示）
Task 3: Deck 牌墩操作（洗牌、发牌、摸牌）
Task 4: Hand 手牌状态模型（手牌 + 副露）
Task 5: 合法操作判定（吃/碰/杠/和）
Task 6: 向听数计算（距离和牌的步数）
Task 7: 番型判定（国标 81 种番型的子集）
Task 8: 计分引擎（番型叠加 + 互斥规则）
Task 9: P0 收尾验收（全套测试 + 覆盖率）

全程用 subagent-driven-development skill 执行：每个 Task 派发一个独立的子 Agent 实现，完成后经过两阶段 Review（规格符合度 → 代码质量），才标记完成。

最终结果：

67 passed in 1.87s
覆盖率：ai/ 模块 96%（目标 85%）

3.4 P1：后端 API + WebSocket + AI 策略

P1 的目标是让人机对战真正跑起来：FastAPI 后端 + PostgreSQL + Redis + 完整的 WebSocket 游戏状态机。

实现计划（docs/superpowers/plans/2026-04-16-p1-backend-api-websocket.md）共 9 个任务：

Task 1: 依赖 + Docker Compose（PostgreSQL + Redis）
Task 2: FastAPI App 骨架（config, database, redis, main）
Task 3: ORM 模型 + Alembic 异步迁移
Task 4: Auth 服务 + API（注册/登录/JWT）
Task 5: Games REST API（创建/列表对局）
Task 6: RoomState 模型 + game_service（Redis 操作）
Task 7: AI 策略模块（启发式出牌 + 赢牌判断）
Task 8: WebSocket 游戏通道（完整状态机）
Task 9: 全套测试 + P1 验收

同样全程 subagent-driven-development 执行。

架构的关键设计决策：

游戏逻辑是纯函数。 WebSocket handler 是薄层，游戏逻辑全部拆成操作 RoomState 的纯函数，与 I/O 完全解耦

RoomState 存 Redis，JSON 序列化。 游戏状态用 Pydantic BaseModel 表示，model_dump_json() 存入 Redis，model_validate_json() 读取，TTL 1 小时

AI 策略：最小化向听数 + 安全牌加成。 出牌逻辑：枚举所有合法出牌，选择让剩余手牌向听数最小的那张；同等向听数时，优先打对手已经打过的牌（安全牌）

完整游戏状态机

测试隔离方案： 测试不依赖真实 PostgreSQL / Redis，用 aiosqlite 内存数据库 + fakeredis 模拟，通过 FastAPI 依赖注入覆盖

最终验收结果：

91 passed in 14.3s
烟雾测试：POST /api/auth/register → {"access_token": "...", "user_id": 1}

---

3.5 P2：前端对战界面

P2 的目标是让游戏真正「可玩」——一个完整的浏览器对战界面，能看牌、出牌、看到 AI 回应、知道游戏结果。

实现计划（docs/superpowers/plans/2026-04-17-p2-frontend.md）共 8 个任务：

Task 1: 项目脚手架（Vite + React + TS + Tailwind）+ 后端 CORS
Task 2: 类型定义 + Auth Store + API Client
Task 3: 登录/注册页（/login）
Task 4: 大厅页（/lobby）
Task 5: Tile 组件系统（TileCard / HandArea / DiscardPile）
Task 6: WebSocket Hook（useGameSocket，自动重连）
Task 7: 完整对战页（GamePage + ActionButtons + GameInfo + GameOverModal）
Task 8: Playwright E2E 测试

技术选型：

层	技术
框架	React 18 + TypeScript + Vite
样式	TailwindCSS
路由	React Router v6
状态	Zustand（persist 到 localStorage）
数据请求	@tanstack/react-query
实时通信	原生 WebSocket
测试	Vitest + Testing Library + Playwright

关键设计决策：

牌面用汉字表示，无需图片资源。 TileCard 组件把 "5m" 这样的字符串渲染成 "五万"，颜色区分花色（万=红、筒=蓝、条=绿、字=紫）。实现干净，加载快，无需维护图片

WebSocket hook 封装自动重连。 指数退避策略，最多重试 5 次，组件卸载时自动断连

建议模式：高亮最后一张摸入的牌。 P2 先做纯 UI 高亮——手牌末位就是刚摸入的牌，用黄色环形标注。这个启发式简单有效，P3 再接入后端向听数计算做精确建议

Playwright 用系统 Chrome，不下载 Chromium。 避免下载 100MB+ 的 Playwright 专用浏览器，直接复用用户机器上的 Chrome

E2E 测试遇到了有趣的时序问题： 测试预期「出牌后看到 AI 回合提示」，但 AI 的三个席位处理太快，等 Playwright 检查时，AI 已经跑完三轮并把牌发回给玩家，状态直接变回「你的回合」。解决方案是把「你的回合」也加入期望分支

这个「失败」其实是成功的证明——AI 跑得足够快，状态机运转正常。

最终验收结果：

单元测试：16 passed（authStore × 3 + LoginPage × 2 + LobbyPage × 2 + TileCard × 6 + useGameSocket × 3）
E2E 测试：2 passed（注册→开局→出牌 / 未登录重定向）
TypeScript：tsc --noEmit 零报错

3.6 P3：复盘分析 + Claude 讲解

P3 的目标是完成「打→学→复盘→成长」闭环中最关键的一环：让玩家能看到自己每一局的决策过程，并得到 AI 教练的逐步讲解。

实现计划（docs/superpowers/plans/2026-04-17-p3-replay.md）共 6 个任务：

Task 1: WS Handler 记录出牌 + 游戏结束时持久化到 DB
Task 2: 复盘分析服务 + GET /api/games/{id}/moves + /replay
Task 3: Claude 复盘 SSE 端点 POST /api/games/{id}/review
Task 4: 前端类型定义 + API Client（含 SSE 流读取）
Task 5: 大厅页添加「复盘」按钮
Task 6: 复盘页面（时间轴 + 手牌 + 关键时刻 + Claude 报告）

后端核心设计：

moves_buffer + 批量写入。 不在每次出牌时都写数据库（那会让 WebSocket handler 变慢），而是在 RoomState 里维护一个内存 buffer，游戏结束时一次性批量写入 game_moves 表

向听数变化检测关键时刻。 detect_critical_moments 函数对玩家每次出牌调用 shanten() 计算出牌前后的向听数

AI SSE 流式输出。 用 FastAPI StreamingResponse + OpenAI-compatible SDK 接入阿里云百炼（qwen-turbo），让复盘报告逐字呈现。之所以用百炼而不是 Anthropic API，是因为服务器部署在阿里云 ECS，访问国内端点更稳定

前端 SSE 读取用 fetch + ReadableStream。 EventSource API 不支持自定义请求头（无法带 JWT），所以用 fetch + 手动读取流

复盘页面设计： 左侧时间轴（<input type="range">）控制步骤，联动显示该步的手牌状态和各席位弃牌区；右侧 Claude 报告面板，点击「关键时刻」列表可直接跳转到对应步骤。

最终验收结果：

后端：101 passed（95 原有 + 6 新增）
前端：18 passed（所有单元测试）
TypeScript：tsc --noEmit 零报错
新增 API：GET /api/games/{id}/moves, GET /api/games/{id}/replay, POST /api/games/{id}/review

---

3.7 P4：知识中心 + 个人成长系统

P4 的目标是让「打→学→复盘→成长」闭环真正合拢——玩家不仅能打牌和复盘，还能系统学习番型知识、阅读策略文章、做练习题，并通过个人成长页看到自己的进步。

实现计划（docs/superpowers/plans/2026-04-17-p4-knowledge-growth.md）共 6 个任务：

Task 1: NavBar 共享导航组件 + 路由扩展
Task 2: 番型库页面 /knowledge/fans（30 种核心番型）
Task 3: 策略文章列表页 + 详情页 /knowledge/articles
Task 4: 出牌练习题页面 /knowledge/quiz（10 道题）
Task 5: 后端统计 API GET /api/stats/summary + /history
Task 6: 个人成长页面 /profile（胜率统计 + SVG 趋势图 + 等级系统）

P4 最大的特点是子系统 A（知识中心）和子系统 B（成长系统）相互独立，Tasks 3/4/5/6 可以并行。实际执行时，Tasks 3&4 并行跑在两个后台 Agent，完成后 Tasks 5&6 也并行跑——总耗时缩短了一半以上。

知识中心：静态内容全部硬编码前端。

番型库、策略文章、练习题的数据全部写在 frontend/src/data/*.ts TypeScript 常量文件里，不需要 CMS，不需要后端 API，部署零依赖

出牌练习题：随机顺序 + 即时反馈。 10 道题，每题展示 14 张手牌 + 四个选项，答题后显示正确答案和详细讲解；题目顺序每次随机打乱，支持重新练习

成长系统：后端直接聚合 Game 表。 不需要新建统计表，用 SQLAlchemy 直接聚合现有 Game 表字段（result、score、ended_at）

趋势图不引入图表库，纯 SVG 手绘。 用 React 的 SVG 支持，约 50 行代码实现了带网格线、折线和数据点的胜率趋势图

等级系统：胜率 + 总局数双维度判定。

等级	条件
新手	不足 10 局
学徒	10~30 局，或 30 局以下胜率不足 50%
进阶	30~50 局，胜率 50%+
高手	50~100 局，胜率 60%+
大师	100 局以上，胜率 70%+

最终验收结果：

后端：106 passed（101 原有 + 5 新增统计 API 测试）
前端：23 passed（单元测试全部通过）
TypeScript：tsc --noEmit 零报错
新增路由：/knowledge/fans, /knowledge/articles, /knowledge/articles/:slug, /knowledge/quiz, /profile
新增 API：GET /api/stats/summary, GET /api/stats/history

P4 并行执行效率：

Tasks 1,2 串行（依赖 NavBar 和路由）
Tasks 3,4 并行（文章和习题完全独立）─────────┐
Tasks 5,6 并行（后端和前端完全独立）─────────┴→ 完成

4 个 Task 压缩到 2 个时间槽，总执行时间减少约 40%。

---

4. Claude Code 功能实战

4.1 Superpowers Skills：让 AI 先想再做

普通的 vibe coding 流程是：「我说一句 → AI 写一堆 → 发现跑偏 → 推翻重来」。

用了 Superpowers 之后变成了：「脑暴对齐 → 写规格 → 写计划 → 按计划执行」。

关键是 writing-plans skill——它不只是写个大纲，而是把每个任务拆成带测试代码的逐步步骤：

### Task 6: 向听数计算

- [ ] 写失败测试：
      def test_shanten_tenpai():
      hand = Hand(tiles("1m 2m 3m 4m 5m 6m 7m 8m 9m 1p 2p 9s 9s"))
      assert shanten(hand.tiles) == 0

- [ ] 运行确认失败：pytest tests/test_hand_analyzer.py -v
- [ ] 实现最小代码
- [ ] 运行确认通过
- [ ] 提交

这种格式让子 Agent 执行时几乎不会跑偏——任务粒度刚好，测试先行，每步有验证。

4.2 Subagents：一人干一件事

subagent-driven-development 的精髓是每个任务派一个全新的子 Agent。

新 Agent = 空白上下文。这意味着：

• 不会被前面任务的细节干扰
• Controller（我的主会话）精确控制它看到什么信息
• 两个 Agent 不会相互污染

执行完成后，还有两阶段 Review：

1. Spec Reviewer：确认实现完全符合规格，没有多做也没有漏做
2. Code Quality Reviewer：检查代码质量（安全、性能、可维护性）

这比「让 AI 自己检查自己」靠谱得多——新 Agent，新视角，发现问题更客观。

实际效果举例：

• P0 Task 7（番型判定）Spec Review 发现缺少「连七对」番型，及时补上
• P1 Task 6（game_service）Code Quality Review 发现 make_game_state_view 没有暴露 result 字段，修复后前端才能正常显示游戏结果

4.3 Playwright MCP：AI 自主验收

配置 Playwright MCP 之后，AI 可以：

打开 localhost:5173 → 截图 → 看到页面空白 → 分析原因 → 修复 → 重新截图验证

全程我不需要切换浏览器，AI 自己完成验收循环。

在脑暴阶段，AI 还用 Playwright 来展示它生成的架构图 HTML 效果——自己开浏览器，截图给我看，确认视觉呈现符合预期。

4.4 Memory：跨对话的项目记忆

Claude Code 有持久化 Memory 系统，写入 ~/.claude/projects/ 目录下的 Markdown 文件，每次对话自动加载。

我的项目 Memory 记录了：

• 使用 Python venv（backend/venv/），因为 macOS Homebrew 环境下不能直接 pip install
• pytest exit code 5 表示「没收集到测试」，不是报错
• 向听数算法测试用例要手动验证，别只看期望值
• passlib 不兼容 Python 3.14，改用 bcrypt 直接调用

这样下次开新对话，AI 不会重蹈覆辙。

4.5 Hooks + settings.local.json：解放双手的关键

这是整个工具链里最容易被忽视、却对「解放双手」影响最大的一环。

Claude Code 在执行某些操作（运行命令、写文件、访问网络）时，默认会向用户询问权限。这对安全很好，但对 vibe coding 来说是噩梦——你不得不一直盯着屏幕，随时点「yes」。

解决方案是在 ~/.claude/settings.local.json 里提前声明允许的操作：

{
  "permissions": {
    "allow": ["Bash(*)", "Edit(*)", "Write(*)", "Read(*)"]
  }
}

加上 Bash(*) 之后，AI 可以自由执行任何 shell 命令，不再打断你。从「需要盯着屏幕随时点 yes」变成了「扔给它，去做别的事，回来看结果」。

更进一步，你还可以通过 Hooks 在特定事件时自动触发额外行为。比如每次 Claude Code 停止时自动发一条通知：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude 完成了\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

这应该是启动任何 vibe coding 项目前的第一件事，而不是等到 Claude Code 问你「要不要不再询问？」才去配置。

---

5. Harness Engineering：让 Agent 在轨道上跑

OpenAI 曾发布一篇文章《Harness Engineering》，记录了他们用 Codex 零手写代码构建内部产品的经验。核心论点是：

Humans steer. Agents execute.（人负责指向，Agent 负责执行）

工程师的工作不再是写代码，而是设计环境、明确意图、构建反馈循环，让 Agent 能可靠地自主完成工作。

这个理念在我的开发过程中体现得很具体。

给 Agent 一张地图，不是一本百科全书

Harness Engineering 文章里说，他们踩的第一个坑是写了一个超长的 AGENTS.md——结果适得其反：上下文太长挤掉了任务本身，而且一旦过时就没人维护。

他们的解法是：AGENTS.md 是目录，docs/ 是知识库。AGENTS.md 只有 100 行，告诉 Agent 去哪里找更深的信息，而不是把所有信息塞进去。

我在这个项目里的做法类似：

docs/
├── superpowers/
│   ├── specs/          # 设计规格（脑暴阶段产出）
│   └── plans/          # 实现计划（每个阶段一个文件）

每个子 Agent 启动时，Controller 只把当前任务的完整文本传给它，不传整个计划文件，更不传整个规格文档。Agent 需要什么，精确提供什么——这是控制上下文质量的关键。

把约束编码成规则，不是口头叫喊

Harness Engineering 的另一个核心洞察是：文档说规范没用，把规范变成代码才有用。他们用自定义 linter 强制执行架构约束，把错误信息写成 Agent 能直接理解的补救指令。

我的 writing-plans skill 做了类似的事：把「测试先行」「每步有验证命令」「代码中不能有占位符」变成计划文档的结构约束，而不是靠 Agent 自觉遵守。每个任务步骤都包含：

• 完整的测试代码（不是「写个测试」）
• 具体的运行命令（不是「运行测试」）
• 明确的期望输出（不是「应该通过」）

Agent 拿到这样的计划，很难偷懒或跑偏。

让 Agent 能自己验收

Harness Engineering 团队把 Chrome DevTools Protocol 接入 Agent 运行时，让 Codex 能自己打开浏览器、截图、分析 UI——这样 QA 循环不需要人介入。

我配置的 Playwright MCP 是同样的思路：AI 完成前端代码后，直接打开浏览器自己验收效果，不需要我切换窗口手动看。

这是一个关键认知：Agent 能感知到的东西，才能被它修复。如果验收结果只在我的眼睛里，AI 就永远不知道哪里错了。把验收结果变成 AI 可读的信号（截图、JSON、日志），才能真正闭环。

两阶段 Review 是自动化的品位

Harness Engineering 里提到，他们把 review 推向了 agent-to-agent（PR 由 Agent 发，也由 Agent 审），人类只在必要时介入。

我的 subagent-driven-development workflow 里有两个独立的 Review subagent：Spec Reviewer 和 Code Quality Reviewer，各自独立上下文、各自给出结论。这不是为了形式，而是为了让「品位」变得可自动化、可重复。

每次 Review 都是一次明确的质量门控。不过两个 Review 都没问题，才算任务完成。

---

6. 踩过的坑

这里的「坑」特指我作为 vibe coder 踩的坑——我的目标是人尽量少地介入，AI 尽可能自动跑，并生成符合预期的内容。凡是让我不得不停下来盯着屏幕、或者导致 AI 效率大幅下降的，都算坑。

坑 1：没有提前配置 settings.local.json，一开始总得盯着 AI 干活

这是对「解放双手」影响最大的一个坑，而且完全可以在第一天就避免。

一开始我没有主动维护 settings.local.json，靠的是 Claude Code 执行命令时弹出询问，我再选「yes, and don't ask again for...」来逐渐积累权限。这里有两个问题：

1. 有些操作只有 yes / no，没有「不再询问」的选项，导致每次都要手动确认
2. 积累权限的过程需要你坐在旁边盯着，根本没法去做别的事

正确做法是项目开始前就在 ~/.claude/settings.local.json 里预配置好：

{
  "permissions": {
    "allow": ["Bash(*)", "Edit(*)", "Write(*)", "Read(*)"]
  }
}

加完这一行，AI 就能完全自主地跑了，不需要你守着。

教训： settings.local.json 是 vibe coding 的「发令枪」。没配好就开跑，等于让 AI 每隔几分钟叫你一次。

---

坑 2：Hit Limit 后无法自动恢复，一晚上的算力浪费了

Claude Code 有使用额度限制，达到上限后会停下来，并显示类似「resets 7pm (Asia/Shanghai)」的提示。

问题在于：limit 往往在我睡着后 reset，但没有任何东西会在 reset 后自动唤醒 AI 继续干活。我早上起来，发现它在凌晨 2 点就停了，后面 6 小时什么都没做。

我尝试了 claude-auto-resume 工具和 claude-auto-retry，初步体验下来，跟我的预期还有一大截距离。这个问题目前没有完美解决方案，等到我解决之后，也会写一篇文章来分享。

教训： 让 AI 跑长任务时，要考虑 limit 时间窗口。如果你预计任务会跨越 reset 时间，最好手动拆成两段，reset 后再续。另外，自动恢复脚本对 Claude Code 版本很敏感，升级后要重新验证。

---

坑 3：AI 自动下载了 Chrome，我的电脑明明装了 Chrome

P2 做 E2E 测试时，AI 执行了 npx playwright install，开始下载 Playwright 专用的 Chromium（100MB+）。我的电脑上明明已经有 Chrome，但 AI 不知道——它只知道「要跑 E2E 测试，需要浏览器，安装它」。

我及时发现并纠正（在 playwright.config.ts 里加 channel: "chrome"，复用系统 Chrome），但这件事引发了一个更深的问题：

当我们完全放手让 AI 干活时，如何防止它做「看似合理但实际多余」的事？

AI 不会主动检查「用户机器上是否已有 Chrome」——这不在它的思考路径里。它看到「需要浏览器」就去装，完全合理，但对我来说是浪费时间和 token。

这类问题的根本原因是：AI 的行为边界由你给的上下文决定。如果你没有告诉它「机器上已有 Chrome，用 channel: chrome」，它就只能按照默认路径走。

教训： 在计划文件里把环境假设写清楚。不是「配置 Playwright」，而是「配置 Playwright，使用系统 Chrome（channel: "chrome"），不要下载额外浏览器」。把约束写进计划，不要指望 AI 自动推断。

---

坑 4：P1 后端和 P2 前端串行开发，其实可以并行

P1（后端 API + WebSocket）和 P2（前端对战界面）是顺序执行的——先把后端做完，再做前端。逻辑上说得通（前端依赖后端接口），但实际上这个依赖可以提前解耦。

只要在 P1 开始时先定好 API 契约（URL、请求格式、响应格式），P2 的开发完全可以同步推进：前端 mock 后端返回的数据，等 P1 完成后再接真实接口。两个子 Agent 各干各的，互不干扰。

这个教训在 P4 里得到了实践。P4 的 6 个任务里：

• Tasks 3&4（文章页 + 练习题页）完全独立，两个 Agent 并行跑
• Tasks 5&6（后端统计 API + 前端成长页）一个后端一个前端，也并行跑

结果：4 个任务压缩到 2 个时间槽，总耗时减少约 40%。

教训： 拆任务时，不只要想「任务内部的步骤顺序」，还要想「哪些任务之间没有真实依赖、可以并行」。多一个 subagent，往往比多等一倍时间要划算。

---

坑 5：部署踩坑集锦——shell 换行、Docker 缓存、PyPI 超时

把项目部署到阿里云 ECS 时，连续踩了三个看似不相关却都让人抓狂的坑：

① shell 多行命令换行符害死人

我给 AI 写的 rsync 命令是这样的：

rsync -avz backend/pyproject.toml backend/Dockerfile \
  backend/start.sh \
    root@121.40.121.91:/opt/majiang/backend/

AI 把它分三行输出，粘贴到终端执行时，\ 换行符在 zsh 里没有被正确识别，结果变成了两条命令：

1. rsync -avz backend/pyproject.toml backend/Dockerfile（本地复制，把 pyproject.toml 内容覆盖进了 Dockerfile！）
2. backend/start.sh root@121.40.121.91:/opt/majiang/backend/（尝试把 start.sh 作为命令执行，权限报错）

这一个操作把本地 Dockerfile 毁掉了，还以为是远程问题调了半天。

教训： 给 AI 写多行 shell 命令时，要求它每条命令单独一行。不要依赖 \ 换行符，尤其是在不同终端环境下行为不一致。

---

② --no-cache 让构建从 0 分钟变成 30 分钟

第一次构建成功后，修了一个 Dockerfile 错误重新构建时用了 --no-cache，结果 apt-get install gcc libpq-dev 这一步从缓存命中（秒过）变成了全量下载 60MB 编译工具链，在阿里云慢网络下耗时将近 30 分钟，中途还超时卡死。

教训： --no-cache 只在 Dockerfile 本身或基础镜像变化时才需要。修应用代码时正常构建就好——Docker 的层缓存会自动只重建 COPY app/ 之后的层。

---

③ PyPI 下载在国内服务器频繁超时

pip install 从 files.pythonhosted.org 下载依赖，在阿里云 ECS 上反复超时。解决方案是换成阿里云 PyPI 镜像：

RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ .

一行改动，从「随机超时」变成「秒级完成」。

教训： 国内服务器部署，第一天就该把包管理器镜像源换成国内源。不只是 pip，npm 同样如此（.npmrc 里配 registry=https://registry.npmmirror.com）。

---

7. Vibe Coding 最佳实践

经过这个项目，我总结了几条真正有效的实践。前三条是「启动项目前」的准备，后几条是「执行过程中」的心法。

启动前

1. 先配好 settings.local.json，再开始任何任务

Bash(*)权限一行解决「AI 总是来问我」的问题。这是成本最低、收益最高的一步，却最容易被忽视。开工前五分钟配好，省去开发过程中无数次盯屏幕。

2. 脑暴先于代码，规格先于计划

用 brainstorming skill 把「我要做什么」讲清楚，再用 writing-plans skill 生成带测试的逐步实现计划。这两步做扎实了，后面 AI 很难跑偏。跳过任何一步，返工的概率就大幅上升。

3. 拆任务时，主动识别可以并行的部分

前后端接口定好后，双方可以同时开发——前端 mock 数据，后端独立实现，最后对接。这个思路在 P4 里把 4 个任务压到 2 个时间槽，效率提升 40%。P1/P2 如果这样做，本可以节省一半时间。

执行中

4. 把环境假设写进计划，不要让 AI 自己推断

AI 不知道你机器上装了什么、有哪些约束——它只能根据你给的信息做决定。「配置 Playwright」和「配置 Playwright，用系统 Chrome，不要下载额外浏览器」，对 AI 来说是两种完全不同的任务。环境相关的约束一定要显式写进计划文件，不能靠 AI 猜。

5. 每个 Agent 只干一件事

给 Agent 的上下文越小越精确，它就越不容易跑偏。大任务拆小任务，小任务给独立 Agent。多开几个 Agent 的成本，远低于一个 Agent 跑偏后的返工成本。

6. Review 是质量门控，不是可选项

实现完成 ≠ 任务完成。Spec Review 确认有没有漏做或多做，Code Quality Review 确认代码本身是好的。两步都过了才算完成。在这个项目里，Review 至少发现了三处「实现对但规格没对齐」的问题。

7. 测试用例要手动验证，不要直接信任

尤其是规则类逻辑（麻将、扑克、棋类），期望值要自己推导一遍再填进去。AI 写的测试用例可能逻辑自洽，但期望值是错的——而「测试通过」不能证明「答案正确」。

8. 把约束编码进系统，而不是每次口头说

Memory、CLAUDE.md、计划模板——这三个地方是你的「持久化规则库」。不要在每次对话里重复说「记得用 aiosqlite 不要用真实 PostgreSQL 跑测试」。说一遍和写进系统，差一个数量级。

---

8. 结语 & 求职

整个项目历经 P0-P4 五个阶段，从规则引擎到 WebSocket 对战，从复盘分析到知识中心和成长系统，全程由 Claude Code + Superpowers 辅助完成。最终交付物：

层次	成果
规则引擎	67 tests，覆盖率 96%，支持国标 81 种番型核心子集
后端 API	106 tests，FastAPI + PostgreSQL + Redis + WebSocket
前端	23 unit tests + 2 E2E，React 18 + TypeScript + TailwindCSS
AI 功能	启发式出牌建议 + Claude SSE 复盘讲解
知识中心	30 种核心番型 + 5 篇策略文章 + 10 道练习题
成长系统	胜率统计 + SVG 趋势图 + 5 级等级系统

回顾整个过程，最让我印象深刻的不是「AI 帮我写了多少代码」，而是工程师角色的转变：我花大量时间做的不是编码，而是设计任务边界、写清楚约束、评审产出质量、决定下一步优先级。这正是 Harness Engineering 文章里说的——Humans steer, agents execute。

如果你也在用 Claude Code 做 vibe coding，希望这篇文章里的踩坑经历能让你少走一些弯路。

---

最后，容我打个小广告——

我目前正在找工作，方向是 AI 初创公司的远程岗位。

做完这个项目，我对「用 AI 工具高效构建产品」这件事有了比较深的实战感受：怎么把一个模糊想法变成可执行的规格，怎么设计任务让 AI 不跑偏，怎么在人和 Agent 之间分工才能最大化效率。这不只是「会用 Claude Code」，而是一套完整的 AI 辅助工程方法论。

我在寻找的机会：

• 前端开发工程师 — React / TypeScript，关注 AI 产品的交互体验与工程质量
• AI Agent 开发工程师 — LLM 应用开发、Agent 工作流设计、AI 工具链集成

期待的环境： 有真实用户的产品、重视工程效率、对 AI 开发方式保持开放
工作方式： 远程优先

如果你的团队正好在找这样的人，或者想聊聊 AI 开发的经验，欢迎加微信：

vvxid_513a72de19d76

只找有意向的机会，不打扰。