AI 辅助编程实践

项目概述

AI 编程助手正在深刻改变软件开发的方式。从早期的代码补全（Copilot）到如今的对话式编程（Cursor、Claude Code），开发者的角色正在从"写代码的人"转变为"指导 AI 写代码的人"。这种转变不仅是工具的升级，更是工作范式的重构。

本案例系统梳理 AI 辅助编程的最佳实践，涵盖三大工具链：Cursor（AI 原生 IDE）、Claude Code（终端 Agent）、MCP（Model Context Protocol）。你将学会如何构建高效的 AI 辅助开发工作流、开发自定义 MCP Server 扩展 AI 的能力边界、以及设计 Agent Skills 实现任务自动化。这些实践不仅提升个人开发效率，也为团队级 AI 编程基础设施的建设提供参考。

详细步骤

步骤 1：日常开发工作流

使用 AI 编程助手的核心原则是"人类思考架构，AI 执行细节"。不要让 AI 从零开始设计系统（它缺乏上下文），而是在你定义好架构和接口后，让 AI 快速实现具体功能。以下是经过实践验证的高效工作流。

1. 需求拆解与接口定义

先手动定义函数签名、类型接口和数据结构，再让 AI 实现具体逻辑。好的接口定义是 AI 生成高质量代码的前提。

// 先定义接口，再让 AI 实现
interface UserRepository {
  findById(id: string): Promise<User | null>
  findByEmail(email: string): Promise<User | null>
  create(data: CreateUserDTO): Promise<User>
  update(id: string, data: UpdateUserDTO): Promise<User>
}

2. 逐功能实现（非一次性生成）

避免让 AI 一次性生成整个文件。按功能模块逐个实现、逐个验证，每次给 AI 的上下文越精确，生成的代码质量越高。在 Cursor 中使用 Cmd+K 选中特定区域让 AI 编辑，比在 Chat 中生成整段代码再粘贴要高效得多。

3. 测试驱动

先写测试用例，再让 AI 实现功能代码。测试用例就是你的"需求规格说明"，AI 根据测试用例实现代码，既准确又有保障。AI 擅长写测试用例——告诉它边界条件和预期行为即可。

步骤 2：代码审查自动化

AI 不仅擅长写代码，也擅长审查代码。将 AI 集成到 Code Review 流程中，可以在 PR 提交前自动检测潜在问题，大幅提升代码质量和团队效率。

// --- Claude Code 代码审查 Skill ---
// 文件: .claude/commands/review.md

请对以下变更进行代码审查，重点关注：

## 安全性
- 是否存在 SQL 注入、XSS、路径遍历等安全风险
- 敏感信息是否泄露（API Key、密码硬编码）
- 输入验证是否充分

## 代码质量
- 是否遵循 DRY、KISS、SOLID 原则
- 错误处理是否完善
- 命名是否清晰、一致
- 是否有明显的性能问题

## 业务逻辑
- 边界条件是否处理
- 并发/竞态条件是否考虑
- 数据一致性是否保证

## 输出格式
对每个问题标注严重程度 [Critical/Warning/Info]，
并给出具体的修改建议和代码示例。

使用方式：在 Claude Code 中执行 /review，或作为 CI/CD 流水线的一部分在每次提交时自动运行。

步骤 3：MCP Server 开发实战

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，让 AI 模型能够与外部工具和数据源交互。通过开发自定义 MCP Server，你可以扩展 Claude 的能力——让它访问你的数据库、调用内部 API、操作文件系统等。MCP Server 本质上是一个标准化了输入输出格式的工具服务。

// --- MCP Server 示例：项目文档搜索 ---
// 文件: mcp-server-docs/src/index.ts

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "project-docs", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// 定义工具
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "search_docs",
      description: "在项目文档中搜索相关内容",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string", description: "搜索关键词" },
          scope: {
            type: "string",
            enum: ["api", "guide", "architecture"],
            description: "文档范围"
          }
        },
        required: ["query"]
      }
    },
    {
      name: "get_api_spec",
      description: "获取 API 接口规格说明",
      inputSchema: {
        type: "object",
        properties: {
          endpoint: { type: "string", description: "API 路径" }
        },
        required: ["endpoint"]
      }
    }
  ]
}));

// 实现工具调用
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "search_docs") {
    const results = await searchProjectDocs(args.query, args.scope);
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  }

  if (name === "get_api_spec") {
    const spec = await getApiSpec(args.endpoint);
    return { content: [{ type: "text", text: JSON.stringify(spec) }] };
  }
});

// 启动服务
const transport = new StdioServerTransport();
await server.connect(transport);

MCP Server 配置：

在 Claude Code 的 MCP 配置中添加你的自定义 Server：

// ~/.claude.json
{
  "mcpServers": {
    "project-docs": {
      "command": "npx",
      "args": ["mcp-server-docs"],
      "cwd": "/path/to/project"
    }
  }
}

步骤 4：Agent Skills 体系设计

Agent Skills 是 Claude Code 的高级能力——将重复性任务封装为可复用的技能。一个 Skill 本质上是一个精心设计的 Markdown 模板，包含任务说明、执行步骤和质量标准。好的 Skill 能让 AI 像一个经验丰富的团队成员一样执行复杂任务。

Skill 设计原则

• 单一职责：一个 Skill 只做一件事
• 明确输入：定义需要用户提供什么信息
• 步骤清晰：每一步都应该具体、可执行
• 质量标准：定义"完成"的标准，包含自检清单

// --- Skill 示例：数据库迁移 ---
// 文件: .claude/commands/migrate.md

根据用户描述的数据库变更需求，执行以下步骤：

## 步骤
1. 分析变更需求，列出所有受影响的表和字段
2. 生成 SQL 迁移脚本（UP 和 DOWN）
3. 检查数据兼容性（是否有默认值、是否有约束冲突）
4. 评估迁移风险和对线上服务的影响
5. 生成回滚方案

## 质量标准
- 迁移脚本必须包含 UP 和 DOWN 两个方向
- 大表变更需要考虑锁表时间和分批执行
- 涉及数据类型变更的，需要数据转换逻辑
- 必须在事务中执行，失败自动回滚

## 输出
1. 迁移 SQL 文件
2. 执行计划（含预估时间）
3. 回滚方案
4. 注意事项清单

步骤 5：效果评估与技巧总结

在长期使用 AI 编程助手的过程中，以下是一些经过验证的最佳实践和常见误区。理解这些原则能帮助你最大限度地发挥 AI 的价值，同时避免常见的陷阱。

推荐做法

• 先写测试再让 AI 实现
• 给 AI 精确的上下文和约束
• 逐模块实现、逐模块验证
• 用 AI 审查自己写的代码
• 将重复任务封装为 Skill
• 让 AI 写文档和注释

常见误区

• 让 AI 从零设计系统架构
• 不审查直接提交 AI 生成的代码
• 一次让 AI 生成整个文件
• 忽略 AI 的安全风险提示
• 过度依赖 AI 丧失基础能力
• 不维护 Prompt 模板复用

效率提升数据

基于实际项目经验，AI 辅助编程在不同场景下的效率提升：

工具对比与选择

常见问题与解决方案

Q: AI 生成的代码不正确怎么办？

不要盲目信任 AI 输出。(1) 理解每一行生成的代码，而不是直接接受；(2) 写测试用例验证行为；(3) 提供更多的上下文和约束条件；(4) 将复杂任务拆分为更小的子任务。

Q: 如何避免 AI 产生的代码安全风险？

(1) 永远不要让 AI 处理包含真实密钥/密码的文件；(2) 对 AI 生成的 SQL 查询、系统命令进行审查；(3) 在 CLAUDE.md 中配置安全规则和权限边界；(4) 使用 Pre-commit Hooks 检测敏感信息泄露。

Q: MCP Server 开发有哪些注意事项？

(1) 工具描述要清晰准确，这是 LLM 决策的唯一依据；(2) 处理好错误和边界情况，返回有意义的错误信息；(3) 控制返回数据的大小，避免超出上下文窗口；(4) 注意安全性，不要暴露敏感操作给未授权的调用。

学习要点总结

1. AI 编程的核心是"人类思考架构，AI 执行细节"
2. Cursor 适合日常编码，Claude Code 适合复杂任务和自动化
3. MCP 协议是连接 AI 和外部世界的桥梁，值得深入学习
4. Agent Skills 将重复性任务标准化，是团队知识资产
5. AI 是工具不是替代品，保持基础编程能力至关重要
6. 安全意识不能放松，AI 生成的代码同样需要审查