代码 Agent 深度实操架构文档进去,前后端代码出来

AI 工程实战 · Multi-Agent 系列 · 第4篇

代码 Agent 深度实操
架构文档进去，前后端代码出来

业务约定内化 · 前后端并行生成 · 冲突处理机制
Figma MCP 联动 · 代码规范 Skill 配置

Multi-Agent 第4篇代码 Agent全栈实现

架构文档出来了，下一步是代码 Agent 把它变成真实可运行的代码。

代码 Agent 最大的挑战不是「会不会写代码」——Claude 写代码能力毋庸置疑。挑战在于：AI 不知道你团队的隐性约定——命名规范、错误码体系、日志格式、认证方式、组件规范……这些写在脑子里、从没成文的约定，决定了生成的代码能不能直接用。

这篇的核心，就是把这些隐性约定系统化地写进代码 Agent 的 Skill，让它输出符合团队标准的代码，而不是通用的「教科书代码」。

代码 Agent Skill：把隐性约定显性化

把你团队的约定整理成以下六类，全部写进 Skill 文件：

.claude/agents/agent-03-code.md — 代码 Agent 完整配置

## 角色定义

你是一个全栈工程师，基于架构文档生成可运行代码。
只读取 workspace/arch/ 目录，输出到 workspace/code/ 和 src/。

## 技术栈（固定，不可自行更换）
前端：React 18 + TypeScript + Tailwind CSS
后端：Node.js 20 + Express + Prisma ORM
数据库：PostgreSQL 16
测试：Jest + Playwright

## 命名约定
– 组件：PascalCase（PaymentDrawer, ConfirmModal）
– 函数：camelCase（handleSubmit, fetchOrderDetail）
– 常量：UPPER_SNAKE_CASE（MAX_AMOUNT, TAX_RATE_MAP）
– API 路径：/api/v1/[resource]/[action]
– 数据库表名：snake_case（payment_orders, service_records）

## 错误处理规范
– 所有 API 返回统一格式：{ code, message, data }
– 业务错误码：BIZ_XXXX（如 BIZ_4001 金额超限）
– 系统错误码：SYS_XXXX
– 前端统一用 ErrorBoundary 捕获，不允许 console.error

## 注释规范
– 每个函数必须有 JSDoc 注释（@param, @returns, @throws）
– 复杂业务逻辑行内注释，说明「为什么」不说「做什么」
– 禁止无意义注释（如 // 获取用户信息）

## 安全规范
– 金额计算全部使用 Decimal.js，禁止浮点数直接计算
– 所有 API 必须校验 JWT Token
– 敏感字段（手机号/金额）日志脱敏

## 禁止行为
– 不修改架构 Agent 定义的接口契约
– 不自行引入未在技术栈列表中的依赖
– 发现架构问题 → 写入 workspace/code/issues.md，不自行决策

💡 Skill 的价值在于把「第一次写对」变成默认行为。花 2 小时把团队约定整理成 Skill，可以节省后续每次 Code Review 里 80% 的规范问题。

02 · 核心实操

从架构文档到代码：四个生成步骤

代码 Agent 不是「一次性生成所有代码」，而是按模块顺序逐步生成，每个模块完成后通知测试 Agent：

Step 1 数据层	生成数据库迁移脚本读取 arch/schema.sql，生成 Prisma Schema + 迁移文件。同时生成数据库种子文件（用于测试环境初始化）。
Step 2 后端API	生成后端接口实现按 arch/api-spec.md 逐个接口实现，含路由/控制器/服务层/DTO 校验。每个接口完成后在 workspace/code/progress.md 打勾。
Step 3 前端组件	生成前端组件读取 Figma MCP 设计稿（如已连接）+ arch/components.md，生成 React 组件。遵循 frontend-design Skill 规范。
Step 4 完成通知	生成模块完成清单 + 通知 Orchestrator 输出 workspace/code/manifest.md（所有生成文件清单），更新 status.json: code.status = “done”，等待测试 Agent 启动。

实际触发提示词（代码 Agent 启动时）

You → 代码 Agent

读取 workspace/arch/ 目录下的所有架构文档，
按以下顺序生成代码：

1. 先生成 prisma/schema.prisma（数据库层）
2. 再生成后端接口（按 api-spec.md 顺序）
3. 最后生成前端组件（按 components.md 清单）

注意事项：
– 金额计算必须使用 Decimal.js
– 发现架构文档歧义 → 写入 workspace/code/issues.md
– 每个模块完成后在 progress.md 打勾
– 全部完成后更新 status.json

Figma MCP 联动：设计稿直接转代码

如果团队有 Figma 设计稿，代码 Agent 可以通过 MCP 直接读取设计规范，生成像素级还原的组件：

代码 Agent + Figma MCP 联动（在 CLAUDE.md 中配置）

## MCP 连接配置

已连接 Figma MCP，可读取设计稿。

## 前端组件生成流程
1. 从 arch/components.md 获取组件清单
2. 用 MCP 读取对应 Figma 组件的设计规范
3. 提取：颜色/字体/间距/交互状态
4. 按 frontend-design Skill 规范生成 React 组件
5. 确保状态管理（loading/error/empty）全部覆盖

# 触发示例
>读取 Figma 文件中的 PaymentDrawer 组件，
>生成对应的 React 组件，包含以下状态：
>– 初始状态（辅材选择）
>– 金额确认状态
>– 支付中状态（loading）
> – 支付成功/失败状态

⚠️ Figma MCP 读取的是设计规范和组件结构，不是像素截图。确保 Figma 文件里的组件已经完整标注了交互状态，否则 Agent 只能生成默认状态的组件。

04 · 关键机制

冲突处理：代码 Agent 发现架构问题怎么办

代码 Agent 在实现过程中，经常会发现架构文档的问题（接口设计遗漏、参数定义模糊、边界条件未覆盖）。处理机制必须明确，否则两种极端都会出问题：

❌ 错误做法

代码 Agent 自行「修复」架构问题，悄悄改了接口设计，导致测试 Agent 对着旧文档写测试，两边对不上。

✅ 正确做法

写入 workspace/code/issues.md，格式：[问题描述] + [建议方案]，更新 status.json: code.issue = true，等待 Orchestrator 仲裁后再继续。

workspace/code/issues.md — 问题反馈格式

## ISSUE-001 · 架构文档缺失幂等性设计
发现位置：

POST /api/v1/payments/secondary
问题描述：接口未定义幂等键（Idempotency-Key），
网络重试时可能导致重复扣款。
建议方案：在请求头加 Idempotency-Key，
服务端校验并缓存 24 小时。
影响范围：支付接口 + 前端重试逻辑
状态：等待 Orchestrator 仲裁

四个常见问题与解法

P1	金额计算精度问题（高频踩坑） JavaScript 浮点数：0.1 + 0.2 = 0.30000000000000004。解法：Skill 里强制要求所有金额计算用 Decimal.js，Orchestrator 扫描代码文件，发现直接用 + 运算符计算金额的，自动打回。

P2	代码风格和团队规范不一致解法：在 Skill 里放 2–3 个正例代码片段（你们团队写得好的真实代码），Agent 会以此为标准对齐风格，比描述规范有效 10 倍。

P3	生成的代码无法编译解法：在 Skill 里加「每个模块生成完毕后，运行 tsc –noEmit 检查 TypeScript 错误，有错误先修复再继续下一个模块」。

P4	引入了不该用的第三方依赖解法：Skill 里维护一个「已批准依赖清单」，Agent 不能引入清单之外的包。Orchestrator 检查 package.json diff，发现新增依赖就触发人工确认。

总结

代码 Agent 的本质

代码 Agent 不是「万能的代码生成器」，而是一个了解你团队规范的新人工程师。它需要你把规范写清楚，然后严格执行。

Skill 文件的完整程度，直接决定代码质量。第一次配置好 Skill，之后每次生成都是团队标准的代码——这才是 AI 工程化的核心价值。

代码 Agent 深度实操架构文档进去，前后端代码出来

代码 Agent 深度实操
架构文档进去，前后端代码出来