AI Coding 最佳实践指南

这段时间摸索出来关于开发的 AI 协作工作流。希望能帮你少走点弯路。

目录

1. 引言
2. 第一步：理解与 AI 协作的 5个核心原则则
• 1.明确意图 > 模糊请求
• 2.上下文是质量的关键
• 3.迭代式开发，小步快跑
• 4.用对工具
• 5.完整的工作流长什么样
3. 第二步：实战用GoFrame创建用户管理API
4. 第三步：掌握提示词工程
5. 第四步：代码审查与验证
6. 第五步：管理项目结构与上下文
7. 第六步：避开这些常见的坑
8. 更多实战案例
9. 工具和技能推荐
10. 总结

引言

你想用 AI 提高编程效率，但总觉得差点意思，对吧？

如果你经历过这些，那咱们就是同路人了：

“AI 写的代码总是差点意思，没办法实现闭环。”

“和 AI 聊没两句就花了一堆 token，但实质性进展很少。”

“生成的代码看起来没问题，但一到生产环境就出 bug。”

说实话，这些坑我都踩过。而且不止一次。

最开始我也以为是自己不会用，换了各种工具、试了各种提示词技巧，效果还是时好时坏。后来才明白——问题不在工具，而在工作流。

没有系统化的协作方式，AI 就是个随机的副驾驶。有时候神助攻，有时候拖后腿。

这份指南里的东西，是我在实践中一点点摸索出来的。不是什么高深的理论，就是实打实的经验。按照这个流程走，我现在基本能做到功能模块从开发、测试到验收的完整闭环。

希望对你有用。

你将学到什么

读完这份指南，你将能够：

• ✅ 建立一套可复用的 AI 协作工作流
• ✅ 写出高质量的提示词，减少 token 浪费
• ✅ 用 TDD 模式确保 AI 生成代码的质量
• ✅ 避开 90% 的常见陷阱
• ✅ 从零构建一个完整的 API 模块（实战案例）

前置要求

在开始之前，你需要：

• 熟悉至少一门编程语言（Go/TypeScript/Python 等）
• 安装并配置好 AI 编程助手（如 Claude Code）
• 有实际项目开发经验

第一步：理解与 AI 协作的 5 个核心原则

1. 明确意图 > 模糊请求

这条可能是最重要的。

AI 的表现直接取决于你给它的指令质量。模糊的请求只能得到模糊的回答——这其实挺合理的，对吧？

我见过最多的模糊请求：

修复这个 bug

有效的请求长这样：

这个函数在处理空数组时返回 undefined 而不是空数组，请修复并确保类型安全。具体来说：- 输入：空数组 [] 时，期望返回 [] 而不是 undefined- 需要检查所有调用这个函数的地方，确保返回值类型一致- 添加对应的单元测试

看出来区别了吗？第二个请求告诉 AI：

• 问题是什么
• 正确的行为应该是什么
• 还要考虑影响范围
• 最后要验证

多花 30 秒写清楚，能省下后面 30 分钟的来回扯皮。

2. 上下文是质量的关键

AI 不是万能的。它不知道你的项目结构，不知道你们的代码规范，不知道你已经试过什么。

必须告诉 AI 这些信息：

• 相关文件的完整内容（别只给片段）
• 项目用的技术栈和版本
• 你已经试过什么，结果怎么样
• 项目的代码风格和规范

我一般会这样开头：

项目背景：这是一个基于 GoFrame v2.5 的 API 服务相关文件：- /api/user/controller.go (用户控制器)- /api/user/service.go (业务逻辑)- /model/user.go (数据模型)当前问题：用户注册接口在高并发下出现重复注册已尝试：加数据库唯一索引，但错误处理不够优雅目标：希望在业务层处理并发，返回友好的错误消息

你给的上下文越完整，AI 给你的答案就越靠谱。

3. 迭代式开发，小步快跑

这个是我踩过很多坑才学会的。

不要期待 AI 一次性生成完美代码。 这事儿不可能。

我现在的做法是分轮次迭代：

第一轮：生成基础实现  └─ 目标：验证思路可行第二轮：添加错误处理  └─ 目标：增强健壮性第三轮：优化性能  └─ 目标：消除瓶颈第四轮：补充测试  └─ 目标：确保可维护性

每一轮之后，我都会：

1. 运行代码看看结果
2. 分析问题出在哪
3. 把发现告诉 AI
4. 进入下一轮

这样下来，代码质量会一轮比一轮好。而且你不会在某一个地方卡太久。

4. 用对工具

现在的 AI 编程助手早就不是单纯的对话模式了。善用扩展工具可以大幅提升效率。

我是这么用的：

Skill（技能）：针对特定框架或领域的知识包

• 如果社区有现成的：直接安装（比如 goframe-v2）
• 如果没有：自己创建一个
• 持续优化：定期分析改进

MCP：标准化上下文协议

• 根据项目需要安装，常见的有 filesystem、github、postgres

Plugin（插件）：增强 AI 助手的功能

• 我常用的是 oh-my-claudecode、oh-my-opencode

5. 完整的工作流长什么样

光说原则可能有点抽象。我下面用一个完整的案例，展示怎么把上面这些原则串起来。

第二步：实战用GoFrame创建用户管理API

场景

假设你接到一个任务：给新项目搞个用户管理模块，要有注册、登录、信息管理这些基本功能。

下面我来演示完整的流程。

第一步：先看看有没有现成的技能

# 搜一下有没有 GoFrame 相关的技能npx skills find goframe# 找到了 goframe-v2，装上npx skills add goframe-v2 -g -y

为什么先找技能？

因为技能里包含了框架的最佳实践和代码模板。直接用，能避免很多坑。而且 AI 生成的代码会更符合框架规范。

说白了，就是别重复造轮子。

第二步：让 AI 帮你分析

用 /opsx:explore 让 AI 分析一下，给你一些实现建议：

/opsx:explore "创建用户管理 API，包含注册、登录、信息管理功能"

AI 会返回：

• 技术选型建议（密码用什么加密、JWT 怎么配等）
• 数据库表结构设计
• API 端点规划
• 安全注意事项

这步能帮你快速建立一个全局的认识。

第三步：拆任务

跟 AI 一起把任务拆开：

Task 1: 创建 User 实体和数据库表Task 2: 实现注册接口（含密码加密）Task 3: 实现登录接口（含 JWT 生成）Task 4: 实现用户信息 CRUDTask 5: 实现用户列表查询（含分页、过滤）Task 6: 编写单元测试Task 7: 编写集成测试

拆任务有个技巧：每个任务应该是独立的，这样后面可以并行处理。

第四步：用 team 模式执行

# 启动 team 模式omc team# 分配任务给不同的 agent# planner: 规划每个 task 的实现细节# executor: 编写代码# test-engineer: 编写测试# verifier: 验证完成质量

team 模式的好处是可以并行处理多个任务，而且每个 agent 都有自己的专长。

第五步：测试验证

# 先运行测试（应该是失败的）go test ./api/user -v# 查看失败原因，让 AI 修复# 再次运行测试，直到全部通过

这步是 TDD 的基本操作。先写测试，再写实现，保证代码质量。

第六步：代码审查

# 使用 code-reviewer 审查生成的代码/code-reviewer review ./api/user

审查的时候重点看：

• 是否符合 GoFrame 框架规范
• 有没有重复造轮子
• 有没有安全漏洞
• 有没有性能问题

结果

这样一套流程走下来，你会得到：

• ✅ 所有功能按需求实现
• ✅ 测试覆盖率 > 90%
• ✅ 代码符合 GoFrame 规范
• ✅ 完成从开发到验收的完整闭环

我自己实际做的时候，大概 3 小时左右能搞定一个这样的模块。

第三步：掌握提示词工程

一个万能的模板

下面这个模板我用了很久，基本覆盖了所有必要的信息：

## 任务[清晰描述要完成的任务]## 工作流1. 如果不知道如何开始，使用 `/opsx:explore` 展开功能实现2. 任务安排后，与 openspec 调整 tasks3. 确认 tasks 后，使用 omc team 模式执行4. 全程保持 TDD 模式## 上下文- 项目类型：[Web 应用/CLI 工具/库/...]- 技术栈：[React/Node.js/TypeScript/...]- 相关文件：[列出关键文件路径]## 约束条件- [性能要求]- [代码风格要求]- [兼容性要求]## 验收标准- [ ] 功能点 1- [ ] 功能点 2

你可以根据实际情况调整，但这个框架基本够用了。

什么时候用 /opsx:explore

这个命令是我用得最多的。当你不知道从哪开始的时候，用它准没错。

典型的使用场景：

• 新功能开发，一头雾水
• 要理解现有代码结构
• 想对比多种实现方案

一般流程是这样的：

1. 描述功能目标   → "我需要一个用户认证系统"2. AI 分析现有代码结构   → 识别现有的 auth 相关文件3. 获取多种实现方案对比   → JWT vs Session，各种加密算法对比4. 选择最优方案并细化   → 确定技术栈，生成具体任务

这步能帮你省下大量查文档和摸索的时间。

不同任务的技巧

代码生成时：

• 告诉 AI 输入/输出格式和类型
• 说清楚所有边界情况（空值、错误、并发）
• 要求添加完整的类型定义

代码解释时：

• 要求逐行解释关键逻辑
• 问问设计决策背后的原因
• 了解一下有没有更好的替代方案

重构优化时：

• 明确指出当前代码的问题
• 设定具体的改进目标
• 强调保持向后兼容

第四步：代码审查与验证

我的审查清单

每次 AI 生成代码后，我都会过一遍这个清单：

• 逻辑正确性：边界条件都处理了吗
• 安全性：有没有注入、XSS、CSRF 这些漏洞
• 性能：有没有明显的性能问题
• 可读性：变量命名、注释清楚吗
• 测试覆盖：有对应的测试吗
• 框架规范：符合项目的代码规范吗

这个清单帮我避免过很多次生产事故。

验证策略

# 1. 类型检查（TypeScript/Go 等）tsc --noEmit# 或 go build ./...# 2. Lint 检查npm run lint# 或 golangci-lint run# 3. 运行测试npm test# 或 go test ./... -v# 4. 检查测试覆盖率npm run test:coverage# 或 go test ./... -coverprofile=coverage.out# 5. 手动验证关键路径# 在本地或测试环境实际运行

这步没什么捷径，就是得做。

第五步：管理项目结构与上下文

推荐的项目文档结构

project/├── CLAUDE.md          # AI 助手的全局指令├── AGENTS.md          # 项目架构与开发规范├── .claude            # claude 特定规则（如使用）├── openspec           # openspec init 的目录└── docs/    ├── architecture.md    ├── api-reference.md    └── decisions/     # 架构决策记录 (ADRs)

这套结构是我试了很多次才确定下来的。核心思想是：把 AI 需要知道的信息都写下来，放在固定的地方。

CLAUDE.md 怎么写

CLAUDE.md 是 AI 助手的全局指令文件。我一般会放三类信息：

1. 开发习惯与语言偏好

# 开发偏好- 使用 TypeScript 严格模式- 优先使用函数式编程风格- 变量命名使用 camelCase，常量使用 UPPER_CASE- 函数超过 50 行需要拆分- 所有公共 API 必须有 JSDoc 注释

2. 版本管理流程

# Git 工作流- 功能开发使用 feature/xxx 分支- 每个 commit 只做一个原子性变更- commit message 格式：<type>(<scope>): <subject>- 提交前必须运行 lint 和 test- 使用 Conventional Commits 规范

3. 框架特定规范

# GoFrame 规范- Controller 只处理 HTTP 层逻辑- Service 层处理业务逻辑- Dao 层只负责数据库操作- 错误使用 errors.New 统一处理- 所有接口必须有输入/输出验证

这些东西写下来，AI 生成的代码就会更符合你的项目规范。

第六步：避开这些常见的坑

坑 1：上下文不足

表现：

• AI 生成的代码不符合项目风格
• 用了项目里不存在的依赖
• 重复实现项目里已有的功能

解决办法：

• 提供完整的相关文件内容（别只给片段）
• 建立项目规范文档（CLAUDE.md、AGENTS.md）
• 用示例代码做参考

这坑我踩过太多次了。现在我都会在项目开始就把文档结构搭好，避免每次都要重复说明。

坑 2：缺乏测试

表现：

• AI 生成的代码没有对应测试
• 测试覆盖率低，不敢重构
• 上线后发现问题，但没有回归测试

解决办法：

• 要求 AI 同时生成测试代码
• 用 TDD 模式：先写测试，再写实现
• 建立自动化测试流程（CI/CD）

我现在的原则是：没有测试的代码不应该合并到主分支。

坑 3：过度依赖

表现：

• AI 生成的代码没审查就直接用
• 不符合框架规范，后续维护困难
• 重复造轮子，项目里已经有类似实现

解决办法：

• 要求 AI 回溯完成的代码，优先使用框架 skill
• 如果是自己创建的框架 skill，持续完善
• 建立代码审查流程，确保生成质量

AI 是副驾驶，你才是司机。别把方向盘完全交给它。

坑 4：Token 浪费

表现：

• 和 AI 聊了很多轮，实质性进展很少
• Token 消耗快，但产出有限
• 对话历史冗长，关键信息分散

解决办法：

• 用结构化的提示词模板
• 每次对话聚焦一个具体任务
• 用 /opsx:explore 先探索再执行
• 避免开放式、模糊的问题

我有个简单的公式：

效率 = 实质性进展 / Token 消耗

每次对话前想想：这次对话能带来什么实质性的进展？

更多实战案例

案例 1：从零构建 REST API 模块

背景：给新项目搞个完整的用户管理 API

流程：

1. 探索阶段：用 /opsx:explore 获取实现方案
2. 任务规划：跟 AI 一起拆任务
3. 执行阶段：用 team 模式并行开发
4. 验证阶段：跑测试 + 代码审查

结果：3 小时左右搞定，测试覆盖率 92%

案例 2：重构遗留代码

背景：一个跑了 2 年的老模块，500 多行的函数，没有测试

策略：

阶段 1：先加测试覆盖（保护网）阶段 2：拆成小函数（降低复杂度）阶段 3：拆分职责（单一职责原则）阶段 4：优化命名（提高可读性）

原则：

• 每次只做一个小改动
• 每次改动后跑测试
• 保持向后兼容
• Git 小步提交

结果：拆成了 15 个小于 50 行的函数，测试覆盖率从 0% 到 95%

案例 3：创建 Skill 提升团队效率

背景：团队用 GoFrame，但通用 AI 不熟悉团队规范

做法：

1. 分析团队特定需求
2. 用 /skill-creator 创建自定义 skill
3. 用 /self-improving-agent 持续优化

结果：新成员上手时间从 2 周缩短到 3 天

工具和技能推荐

AI 工具

这三个我都用过。Claude Code 的上下文理解确实好一些，但价格贵一点。Open Code 开源，可以自己改。Codex Code 性价比高，适合长时间用。

技能

MCP Servers

总结

回顾一下

这份指南涵盖了：

1. 5 个核心原则 —— 明确意图、上下文、迭代开发、用对工具、完整工作流
2. 实战案例 —— 从零构建用户管理 API 的完整流程
3. 提示词工程 —— 万能模板和使用技巧
4. 代码审查 —— 审查清单和验证策略
5. 项目管理 —— 文档结构和 CLAUDE.md 编写
6. 常见陷阱 —— 4 个大坑和避开方法

下一步建议

现在你已经有了完整的框架，接下来：

1. 挑一个你手头的任务，试着用这个流程走一遍
2. 别照搬，根据你自己的团队和项目调整
3. 记录反馈，哪里不舒服就改哪里

最重要的是：建立适合自己的工作流。

这份指南里的东西，都是我实打实踩过坑总结出来的。但不是说你照着做就一定行。每个项目、每个团队的情况都不一样。

如果这份指南对你有帮助，或者你有什么问题，欢迎交流。

2026-04-05

Neak