翻译 ｜ 🧠 完整AI编码助手工作流

credit: https://www.youtube.com/watch?v=SS5DYx6mPw8

本指南概述了一个可重复、结构化的流程，用于与AI编码助手一起构建生产级质量的软件。我们将以使用Python构建Supabase MCP服务器为例，但同样的流程适用于任何AI编码工作流程。

1. 🔑 黄金法则

这些是指导如何高效有效地使用AI工具的高级原则。我们将通过全局规则和在整个过程中的提示来实施这些原则：

• 使用markdown文件管理项目（README.md、PLANNING.md、TASK.md）。

• 保持文件少于500行。需要时拆分为模块。

• 经常开始新的对话。长线程会降低响应质量。

• 不要过载模型。每条消息一个任务是理想的。

• 尽早测试，经常测试。每个新函数都应该有单元测试。

• 在请求中具体明确。提供的上下文越多越好。示例会很有帮助。

• 边做边写文档和注释。不要推迟文档编写。

• 自己实现环境变量。不要将API密钥交给LLM。不要做这样的人。

2. 🧠 规划与任务管理

在编写任何代码之前，与LLM进行对话以规划项目的初始范围和任务是很重要的。范围记录在PLANNING.md中，具体任务记录在TASK.md中。随着项目进展，这些文件应由AI编码助手更新。

PLANNING.md

• 目的：高级愿景、架构、约束、技术栈、工具等。
• 向AI提示：“使用PLANNING.md中概述的结构和决策。”
• 在任何新对话开始时让LLM参考此文件。

TASK.md

• 目的：跟踪当前任务、待办事项和子任务。
• 包括：活动工作的项目符号列表、里程碑和在过程中发现的任何内容。
• 向AI提示：“更新TASK.md，将XYZ标记为已完成，并添加ABC作为新任务。”
• 也可以通过全局规则提示LLM自动更新和创建任务。

3. ⚙️ 全局规则（用于AI IDE）

全局（或项目级别）规则是强制AI编码助手使用黄金法则的最佳方式。 全局规则适用于所有项目。项目规则适用于您当前的工作空间。所有AI IDE都支持这两种规则。

• Cursor规则：https://docs.cursor.com/context/rules-for-ai
• Windsurf规则：https://docs.codeium.com/windsurf/memories#windsurfrules
• Cline规则：https://docs.cline.bot/improving-your-prompting-skills/prompting
• Roo Code规则：与Cline的工作方式相同

使用以下示例（针对我们的Supabase MCP服务器）作为起点，向您的AI IDE系统提示添加全局规则以确保一致性：

🔄 项目意识与上下文

• 始终在新对话开始时阅读PLANNING.md，以了解项目的架构、目标、风格和约束。
• 在开始新任务前检查TASK.md。如果任务未列出，请添加简短描述和今天的日期。
• 使用PLANNING.md中描述的一致命名约定、文件结构和架构模式。

🧱 代码结构与模块化

• 从不创建超过500行代码的文件。 如果文件接近此限制，通过拆分为模块或辅助文件进行重构。
• 将代码组织成明确分离的模块，按功能或责任分组。
• 使用清晰、一致的导入（在包内优先使用相对导入）。

🧪 测试与可靠性

• 始终为新功能创建Pytest单元测试（函数、类、路由等）。
• 更新任何逻辑后，检查是否需要更新现有单元测试。如果需要，请更新。
• 测试应位于/tests文件夹中，镜像主应用程序结构。
  • 至少包括：
    • 1个预期用途测试
    • 1个边缘案例
    • 1个失败案例

✅ 任务完成

• 完成任务后立即在TASK.md中标记已完成任务。
• 在开发过程中发现的新子任务或待办事项添加到TASK.md的”工作中发现”部分。

📎 风格与约定

• 使用Python作为主要语言。

• 遵循PEP8，使用类型提示，并使用black格式化。

• 使用pydantic进行数据验证。

• 如果适用，使用FastAPI构建API，使用SQLAlchemy或SQLModel作为ORM。

• 使用Google风格为每个函数编写文档字符串：

  def example():    """    简要摘要。    Args:        param1 (type): 描述。    Returns:        type: 描述。    """
  

📚 文档与可解释性

• 添加新功能、依赖项更改或修改设置步骤时更新README.md。
• 注释非明显代码，确保中级开发人员能理解所有内容。
• 编写复杂逻辑时，添加内联# 原因：注释，解释原因，而不仅仅是内容。

🧠 AI行为规则

• 永远不要假设缺少上下文。如有不确定，请提问。
• 永远不要虚构库或函数 – 只使用已知、经过验证的Python包。
• 在代码或测试中引用文件路径和模块名称前，始终确认它们存在。
• 永远不要删除或覆盖现有代码，除非明确指示或是TASK.md中的任务。

4. 🧰 配置MCP

MCP使您的AI助手能够与服务交互，以完成以下操作：

• 使用文件系统（读/写、重构、多文件编辑）

  • 获取此服务器

• 搜索网络（适用于获取文档）使用Brave

  • 获取此服务器

• 使用Git（分支、比较差异、提交）

  • 获取此服务器

• 访问内存和其他工具

  • 例如，连接Qdrant

想要更多MCP服务器？ 在此处查看带有安装说明的大量MCP服务器列表。

如何配置MCP：

• Cursor MCP：https://docs.cursor.com/context/model-context-protocol
• Windsurf MCP：https://docs.codeium.com/windsurf/mcp
• Cline MCP：https://docs.cline.bot/mcp-servers/mcp
• Roo Code MCP：https://docs.roocode.com/features/mcp/using-mcp-in-roo

使用Git MCP服务器可能的示例提示：

好的，我喜欢应用程序的当前状态。请进行git提交以保存当前状态。

5. 💬 启动项目的初始提示

开始项目的第一个提示是最重要的。即使在PLANNING.md中有全面的概述，TASK.md中有明确的任务，以及良好的全局规则，仍然重要的是要提供大量详细信息，准确描述您希望LLM为您创建的内容以及它可以参考的文档。

根据您的项目，这可能意味着许多不同的事情，但这里最好的建议是提供您想要构建的类似示例。bolt.new、v0、Archon等应用中最好的提示都提供了示例 - 您也应该这样做。如果使用特定工具、框架或API进行构建，通常还需要其他文档。

提供示例和文档有三种方式：

1. 使用许多AI IDE内置的文档功能。例如，如果我在Windsurf中输入”@mcp”并按tab键，我就告诉Windsurf搜索MCP文档来辅助编码。
2. 让LLM使用像Brave这样的MCP服务器在互联网上查找文档。例如：“搜索网络以查找其他Python MCP服务器实现。”
3. 在您的提示中手动提供示例/文档片段。

创建初始Supabase MCP服务器的示例提示（使用Python）：

使用@docs:model-context-protocol-docs和@docs:supabase-docs创建一个用Python编写的MCP服务器（使用FastMCP）与Supabase数据库交互。服务器应使用Stdio传输并具有以下工具：

- 读取表中的行
- 在表中创建记录（一个或多个）
- 更新表中的记录（一个或多个）
- 删除表中的记录（一个或多个）

确保为每个工具提供全面的描述，使MCP服务器能够有效地向LLM传达何时以及如何使用每种功能。
此MCP服务器的环境变量需要是Supabase项目URL和服务角色密钥。

阅读此GitHub README以了解如何使用Python创建MCP服务器：

https://github.com/modelcontextprotocol/python-sdk/tree/main

使用FastMCP创建MCP服务器后，更新README.md和TASK.md，因为您现在已经有了服务器的初始实现。

记住在对话变长时重新开始对话。当LLM开始让你感到无比沮丧时，你就知道是时候了。

6. 🧩 初始提示后的模块化提示过程

对于项目的任何后续修复或更改，通常您希望一次只给出一个任务，除非任务非常简单。虽然一次向LLM提出很多问题很诱人，但越是集中的更改，结果就越一致。

好例子：

"现在更新列出记录的函数，添加一个用于过滤记录的参数。"

坏例子：

"更新列出记录以添加过滤。然后，我在创建行函数中收到一个错误，说找不到API密钥。此外，我需要为主函数和README.md添加更好的文档，说明如何使用此服务器。"

为了获得一致的输出，最重要的是让LLM尽可能专注于更新单个文件。

记住，在进行任何更改后，始终让LLM更新README.md、PLANNING.md和TASK.md！

7. ✅ 测试每个功能

通过全局规则告诉LLM在实现每个功能后编写单元测试，或者自己作为后续操作进行测试。及早发现错误可以防止问题复合，所以这一点非常重要！

单元测试可能很烦人，LLM在编写它们方面也不是完美的，但尽力让AI编码助手测试它实现的所有内容。在最糟糕的情况下，如果它在测试中卡住而你只想继续前进，你总是可以要求它跳过为某个功能编写测试。

测试最佳实践（LLM应该知道这些，以防万一）：

• 在tests/目录中创建测试
• 始终”模拟”对DB和LLM等服务的调用，这样您就不会与任何东西”真正”交互。
• 对于每个函数，至少测试一个成功场景、一个有意的失败（以确保正确的错误处理）和一个边缘案例。

8. 🐳 Docker部署（Supabase MCP示例）

这一步更加可选，且相当有主见，但我仍然想分享我通常的做法！当我准备好将项目部署到云端托管和/或与他人共享时，我通常使用Docker或类似服务（如Podman）将项目”容器化”。

LLM在处理Docker方面非常出色，所以这是我发现的打包项目最一致的方式。此外，几乎每个用于部署应用的云服务（Render、Railway、Coolify、DigitalOcean、Cloudflare、Netlify等）都支持托管Docker容器。我将所有AI代理、API端点和MCP服务器作为Docker容器托管。

Dockerfile：

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制MCP服务器文件
COPY . .

CMD ["python", "server.py"]

构建命令：

docker build -t mcp/supabase .

从LLM获取这些内容的示例提示：

为这个MCP服务器编写一个使用requirements.txt的Dockerfile。在之后给我构建容器的命令。