用 AI Agent 开发和自动发布微信小程序——以「拾光恋人」为例

• 规模：298 commits、263 文件、39 个前端页面、546 个后端测试、72 天开发周期
• 方法：AI Agent（Claude Code）全流程驱动——从架构设计到迭代打磨到自动部署

1. 为什么选择 Agent 驱动开发小程序#

小程序开发有一个独特优势：它是目前最适合 Agent 操作的交付形态。

• 无浏览器依赖：小程序不能在浏览器中预览，传统开发流程需要频繁切换开发者工具和编辑器；Agent 反而不受影响——它本来就不依赖 GUI 调试，靠读代码 + 构建验证就够了。
• 构建可验证：npm run build 编译成功 = 代码正确性基线保证。Agent 每次改动后构建验证，形成闭环。
• 部署链路可自动化：后端推 GitHub → 微信云托管自动部署；前端构建产物 → 开发者工具上传。整条链路 Agent 都能触达。
• 页面级原子化：小程序的每个页面是一个独立 .mpx 文件（模板 + 逻辑 + 样式），天然适合 Agent 做页面级迭代——一轮改一个页面，干净利落。

「拾光恋人」就是这一方法的完整实践：从零开始，72 天，298 次提交，最终交付了一个 25+ 页面、功能完整的产品。

2. 项目全貌#

2.1 产品#

拾光恋人——情侣积分与共同打卡小程序。核心模块：

产品全貌——从引导页到核心功能，6 个代表性界面：

2.2 技术架构#

微信小程序 (MPX 2.x)                    微信云托管              Django 后端
┌─────────────────────────────────┐  ┌─────────────────┐  ┌──────────────┐
│ 39 个页面                        │  │                 │  │ REST API     │
│ Pinia defineStore × 10           │──│ CLOUD_ENV       │──│ JWT 认证      │
│ antd-mini + weapp-tailwindcss    │  │ 对象存储 COS     │  │ 13 个 Model   │
│ Less + 设计 Token 系统            │  └─────────────────┘  │ 546 个测试    │
└─────────────────────────────────┘                       └──────────────┘

2.3 关键数字#

3. Agent 开发工作流#

3.1 项目配置层——让 Agent 理解你的项目#

Agent 驱动开发的前提是：Agent 需要能在每次唤醒时快速理解项目全貌。我们通过三层配置文件实现：

AGENTS.md / CLAUDE.md——项目宪法

score-miniapp/
├── AGENTS.md           # 全局规则：角色、技术栈、开发规则、部署命令
├── CLAUDE.md           # Claude Code 专用：命令速查、架构概览、子文档索引
├── frontend/
│   └── CLAUDE.md       # 前端详细：Store 模式、页面设计原则、项目结构
├── backend/
│   └── CLAUDE.md       # 后端详细：Views 架构规则、API 全览、环境变量
└── .guardrails/
    └── RULES.md         # 错误资产化：每次犯错后追加规则

核心设计原则：

• 角色定义清晰：「资深全栈产品工程师：MPX 小程序 + Django/DRF 后端 + 恋爱心理学产品」
• 命令即文档：所有常用命令（启动、构建、测试、部署）直接写在配置中，Agent 可以直接执行
• 规则来自真实事故：例如「2026-05-17 事故：未提交改动被重构覆盖」→ 生成 5 条防止代码丢失的强制规则

设计 Token 单一数据源

前端有一个 theme.js 作为设计 token 的唯一真相来源：

// 颜色、字号、阴影、圆角全部在这里定义
// Agent 每次迭代前读取这个文件，确保所有修改遵循设计系统
primary: '#FF8A80'
primarySafe: '#E8655A'   // CTA 按钮，对比度安全
// 字号严格 8 级：20/22/24/28/32/36/40/72 rpx

这意味着 Agent 做设计迭代时不需要「设计感」——它只需要遵循 token 系统。规范化比审美更重要。

3.2 迭代执行层——Loop 机制#

整个项目的 298 次提交不是随意产生的，而是通过 Loop 迭代机制 有节奏地推进。

功能迭代 Loop

每轮迭代是一个结构化的闭环：

Spec（迭代目标）
  → Tasks（拆解 5-10 个任务）
    → Execute（每个任务独立 commit）
      → Verify（后端测试 + 前端构建）
        → Result（输出 result.md）
          → Feedback（审查反馈，下轮必须回应）

迭代节奏示例（iter-round-5，2026-07-13）：

关键设计：反馈审查机制。每轮迭代的产出都要经过审查维度检验：

• ❌ 防御代码堆积（不必要的 try/catch、fallback）
• ❌ 硬编码绕过（为通过测试而 hardcode）
• ❌ 测试退化（删除/简化测试以通过验证）
• ❌ 方向偏离（改动与项目核心方向无关）
• ❌ 空转（≤2 commits 或 result.md 缺失）

设计迭代 Loop——50 轮自动化打磨

这是最有意思的部分。我们设计了一个 50 轮的设计审查 Loop，每轮处理一个页面：

# .claude/design-loop/playbook.md 核心逻辑
目标: 50 iterations of per-page UI optimization
每轮: pick ONE page → audit 4 dimensions → apply fixes → build verify → commit → log

4 个审查维度:
  1. UI 美观度 — spacing/hierarchy/shadow/visual polish
  2. UI 风格 — module theme consistency, brand voice
  3. UI 规范 — token adherence, font scale, :active feedback
  4. UI 组件程度 — prefer antd-mini, use shared components

硬约束:
  - CSS-first, minimal changes
  - Build-verify every iteration
  - One commit per iteration
  - 不改业务逻辑

Agent 会自动调度：读 progress.json → 确定下一个页面 → 审查 → 修改 → 构建 → 提交 → 更新进度 → 调度下一轮。50 轮跑完，全站 38 个页面都经过系统性打磨。

实际产出示例（设计迭代摘录）：

[iter-65] design-loop34/50: add-record — 提交栏冷阴影→暖 + 照片添加 +→AddOutline
[iter-70] design-loop39/50: activity-detail — 活动信息标签 emoji→ant-icon
[iter-73] design-loop42/50: 字号 scale 系统清扫 — 弹窗标题 34→32(h3)
[iter-74] design-loop43/50: 新增共享 error-state 组件 (P0)
[iter-81] design-loop50/50: activity-detail — 互动统计栏 emoji→ant-icon ✅ 50 轮完成

50 轮迭代带来的系统性改进：

• 三件套覆盖率：empty-state 22%→85%，loading-skeleton 11%→78%，error-state 8%→70%
• Emoji-as-icon 清扫：全站 emoji 图标统一迁移到 antd-mini ant-icon
• 设计 Token 合规：字号从 20+ 种散乱值收敛到严格 8 级
• 共享组件提取：error-state、loading-skeleton、empty-state 从 0 到 3 个复用组件

3.3 质量保证层——测试驱动的 Agent 开发#

Agent 最容易翻车的是：改了 A，坏了 B。解决方案是测试全覆盖 + 每次改动后全量验证。

后端测试策略

# Agent 每次后端改动后的验证命令
cd backend && DJANGO_SETTINGS_MODULE=scoreapp.settings_test python3 -m pytest api/tests/ -q

测试演进历程：

• iter-1~3：333 tests → 修复 SQLite 兼容 → 346 passed, 0 failed
• iter-8~9：补充 Notification/Anniversary 边界测试 → 360 passed
• iter-20：ScoreRecord 边界测试（异常输入/分页/权限） → 374 passed
• iter-round-4：daily-summary bug 修复 + 测试 → 430 passed
• iter-round-5：daily-summary + album 边界测试 → 446 passed, 0 failed

关键：SQLite 测试环境。生产用 MySQL 5.7，但 Agent 跑测试时用 SQLite（settings_test.py），避免 Docker 依赖。为此注册了自定义 SQLite 函数模拟 MySQL 的 NOW() / DATEDIFF()。

前端构建验证

cd frontend && npm run build  # → dist/wx/，必须 "Compiled successfully"

Agent 无法在微信开发者工具中预览，所以构建成功是最基本的质量门禁。每次迭代必须通过。

4. 自动发布流程#

4.1 后端——GitHub 推送即部署#

git push origin main
  → 微信云托管检测到推送
    → Docker 多阶段构建（Python 3.13 + Django 5.2）
      → docker-entrypoint.sh:
          1. makemigrations --check（拒绝未提交的 migration）
          2. migrate --noinput
          3. gunicorn --workers 2 --bind 0.0.0.0:80

安全设计：docker-entrypoint.sh 中的 makemigrations --check --dry-run 会检测到模型变更但没有生成 migration 文件的情况，直接拒绝启动。这防止了 Agent 忘记跑 migration 导致生产 schema 不一致。

4.2 前端——构建产物 + 手动上传#

# 开发版（用于测试）
pnpm run serve    # → dist/wx/（开发模式）

# 生产版
npm run build     # → dist/wx/（生产模式，压缩混淆）

构建产物 dist/wx/ 用微信开发者工具打开 → 上传代码 → 提交审核。

前端发布目前仍需手动操作（微信小程序限制，CI 无法绕过开发者工具的上传步骤）。但 Agent 可以完成到「构建出可发布的产物」为止的所有工作。

4.3 环境切换#

// frontend/src/utils/env.js
const USE_LOCAL = false  // true → localhost:8000, false → 微信云托管

一个布尔值切换本地/生产环境。简单、够用。

5. 实践中的工程智慧#

5.1 错误资产化#

传统项目的经验靠人记，Agent 项目靠文件记。.guardrails/RULES.md 就是「错误资产化」文件：

## 规则
1. design loop 上限 10 轮 — 超过后必须切换回功能迭代
2. PROGRESS.md 必须与 git log 同步
3. 不添加不必要的 fallback / try-catch
4. 不简化代码来通过验证
5. 不删除测试用例
6. 不在 design loop 中改功能逻辑

每条规则背后都是一个真实踩过的坑。Agent 下一轮迭代启动时会先读这个文件，避免重蹈覆辙。

5.2 渐进式测试加固#

不在项目初期一口气写完所有测试，而是每轮迭代补 5-15 个。5 轮功能迭代从 0 增长到 546 个测试：

iter-round-1: +34 tests (SQLite 兼容修复 + ScoreRecord + Achievement + DailyQuestion)
iter-round-2: +13 tests (Notification + Anniversary 边界)
iter-round-3: +14 tests (ScoreRecord 边界深化)
iter-round-4: +13 tests (daily-summary bug 修复验证 + stats trend)
iter-round-5: +16 tests (daily-summary + album on-this-day)

测试跟功能同步增长，不欠技术债。

5.3 Agent 友好的代码组织#

• Views 按业务域拆分：api/views/lover.py, api/views/checkin.py... Agent 改打卡功能时只读一个文件，上下文消耗最小
• Store 与 API 一一映射：useCheckinListStore → /api/checkin-lists/，Agent 看到 Store 就知道对应哪个 API
• 子目录独立 AGENTS.md：前端和后端各有自己的 CLAUDE.md，Agent 可以只加载需要的上下文

5.4 迭代边界设计#

每轮迭代有明确的 scope：

• 功能迭代：5-10 个有意义的改动，每个独立 commit
• 设计迭代：50 轮分页打磨，每轮 CSS-first 只改样式
• 禁止混线：design loop 中不改功能逻辑；功能迭代不做设计打磨

这个约束防止 Agent 在一轮迭代中同时改功能和样式，导致无法定位问题来源。

6. Agent 驱动 vs 传统开发对比#

Agent 驱动的核心优势：不是速度（虽然确实快），而是一致性。50 轮设计迭代每轮都严格遵循 4 维度审查 + token 系统 + 构建验证——人类开发者很难保持这种纪律性。

Agent 驱动的核心限制：无法做视觉验证。小程序不能浏览器预览，Agent 只能靠代码审查 + 构建验证，最终视觉效果仍需人类确认。这意味着 Agent 适合做「规范化」（token 合规、组件复用、交互统一）而非「创意设计」。

7. 复用指南——如何复制这套方法#

如果你也想用 Agent 开发小程序，核心要素：

必须有的#

1. AGENTS.md / CLAUDE.md：项目宪法，定义角色、技术栈、命令、规则
2. 构建验证闭环：npm run build 或等价命令作为每次改动的质量门禁
3. 测试基础设施：至少有 pytest/jest 可跑，Agent 每轮迭代可以验证
4. 错误资产化文件：把犯过的错写成规则，Agent 下一轮自动遵守

强烈推荐的#

5. 设计 Token 系统：颜色/字号/阴影/间距的单一数据源，让 Agent 做设计决策变成查表而非审美
6. Loop 迭代机制：Spec → Tasks → Execute → Verify → Result → Feedback 闭环
7. 按域拆分代码：Agent 每次只加载必要上下文，节省 context window
8. 渐进式测试策略：每轮迭代补 5-15 个测试，不一次性写完

锦上添花的#

9. 设计审查 Loop：自动化逐页打磨，适合 UI 一致性要求高的项目
10. 自动部署链路：git push → 云托管自动构建，Agent 也能触发部署

8. 总结#

「拾光恋人」证明了一件事：小程序是 Agent 驱动开发的理想场景。

• 无 GUI 依赖 → Agent 不受影响
• 构建可验证 → 质量闭环
• 页面级原子化 → 迭代天然适合
• 部署链路可达 → 全流程自动化

72 天，298 次提交，546 个测试，39 个页面，50 轮设计打磨——这不是一个 demo，是一个真实交付的产品。而驱动这一切的，是一套结构化的工程方法：配置层让 Agent 理解项目，Loop 层让 Agent 有节奏地推进，质量层让 Agent 不翻车。

Agent 不会取代开发者，但会用 Agent 的开发者，效率是完全不同的量级。

项目开源：score-miniapp（拾光恋人）| 技术栈：MPX 2.x + Django 4.2 + 微信云托管