翻译 ｜ 一套完整的 AI 编程助手工作流

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

这篇指南梳理了一套可复用的结构化流程，教你怎么和 AI 编程助手配合写出生产级的代码。文中会以用 Python 搭建 Supabase MCP 服务器为例，但这套方法论适用于任何 AI 辅助编程场景。

1. 黄金法则

先说几条核心原则，后面的全局规则和提示词都是围绕它们展开的：

• 用 Markdown 文件管理项目（README.md、PLANNING.md、TASK.md）。
• 单个文件不超过 500 行，大了就拆模块。
• 对话别拉太长，上下文一多质量就下降，及时开新对话。
• 别一条消息塞太多事，一次一个任务效果最好。
• 早测试、勤测试，每个新函数都配上单元测试。
• 提问题要具体，给的上下文越多，AI 回答越靠谱。附上示例更好。
• 文档和注释随手写，别想着“回头再补”。
• 环境变量自己配。API 密钥别交给 LLM，千万别。

2. 规划与任务管理

动手写代码之前，先和 LLM 聊聊，把项目的大致范围和任务理清楚。整体规划写进 PLANNING.md，具体任务记在 TASK.md。项目推进过程中，让 AI 助手持续更新这两个文件。

PLANNING.md

• 用途：记录项目愿景、架构设计、技术选型、约束条件等高层信息。
• 提示词示例："参照 PLANNING.md 里的架构和决策来写代码。"
• 每次开新对话都先让 LLM 读一遍这个文件。

TASK.md

• 用途：追踪当前任务、待办项和子任务。
• 内容包括：当前进行中的工作清单、里程碑、以及过程中发现的问题。
• 提示词示例："更新 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 服务器为例），可以直接拿来当模板：

项目感知与上下文

• 每次新对话都先读 PLANNING.md，了解项目的架构、目标、代码风格和约束。
• 开始新任务前先看 TASK.md，如果当前任务没记录，就加一条简要描述和日期。
• 严格遵循 PLANNING.md 中的命名规范、目录结构和架构模式。

代码结构与模块化

• 任何文件都不要超过 500 行。 快到上限了就拆成子模块。
• 按功能或职责把代码组织成独立模块。
• 导入语句保持清晰一致，包内优先用相对导入。

测试与可靠性

• 每个新功能都要写 Pytest 单元测试（函数、类、路由等）。
• 改了业务逻辑之后，检查现有测试是否需要同步更新。
• 测试放在 /tests 目录下，目录结构与主代码保持一致。
  • 每个功能至少覆盖：
    • 1 个正常用例
    • 1 个边界情况
    • 1 个异常情况

任务完成

• 做完一个任务就立刻在 TASK.md 里标记完成。
• 开发过程中发现的新问题或子任务，记到 TASK.md 的“过程中发现”一栏。

编码风格与约定

• 主语言用 Python。

• 遵循 PEP8，用类型标注，用 black 格式化。

• 数据校验用 pydantic。

• API 用 FastAPI，ORM 用 SQLAlchemy 或 SQLModel（按需选择）。

• 每个函数都写 docstring，采用 Google 风格：

  def example():
      """
      简要说明。
  
      Args:
          param1 (type): 参数描述。
  
      Returns:
          type: 返回值描述。
      """
  

文档与可读性

• 加了新功能、改了依赖或配置流程时，同步更新 README.md。
• 给不直观的代码加注释，确保中级开发者能看懂。
• 遇到复杂逻辑，用 # 原因： 行内注释说明为什么这么写，而不只是描述做了什么。

AI 行为准则

• 拿不准就问，不要自己脑补缺失的上下文。
• 不要编造不存在的库或函数——只用经过验证的 Python 包。
• 引用文件路径或模块名之前，先确认它真的存在。
• 不要擅自删除或覆盖已有代码，除非我明确要求或者它在 TASK.md 的任务里。

4. 配置 MCP

MCP 能让 AI 助手直接和外部服务交互，比如：

• 操作文件系统（读写、重构、跨文件编辑）
• 用 Brave 搜索网页（查文档特别好用）
• 操作 Git（切分支、看 diff、提交代码）
• 接入记忆存储等其他工具（比如 Qdrant）

想找更多 MCP 服务器？网上有汇总了大量 MCP 服务器的列表，带安装说明。

各 IDE 的 MCP 配置文档：

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

配合 Git MCP 的提示词示例：

现在代码状态不错，帮我 git commit 保存一下。

5. 项目的第一条提示词

开局的第一条提示词至关重要。哪怕 PLANNING.md 写得再详细、TASK.md 梳理得再清楚、全局规则配得再完善，第一条提示依然要尽可能具体——告诉 LLM 你要做什么，以及可以参考哪些文档。

具体到你的项目会有不同，但最好的做法是：给一个类似的参考示例。bolt.new、v0、Archon 里那些效果最好的提示词，无一例外都附带了示例。如果你用到了特定的工具、框架或 API，通常还需要额外提供相关文档。

提供参考材料有三种方式：

1. 用 AI IDE 自带的文档索引功能。比如在 Windsurf 里输入 @mcp 再按 Tab，就是在告诉它去搜 MCP 文档。
2. 让 LLM 通过 Brave 等 MCP 服务器自行上网找。比如："帮我搜一下其他 Python MCP 服务器的实现方式。"
3. 直接在提示词里贴上示例代码或文档片段。

以创建 Supabase MCP 服务器为例的起手提示词：

参考 @docs:model-context-protocol-docs 和 @docs:supabase-docs，用 Python + FastMCP 写一个与 Supabase 数据库交互的 MCP 服务器。传输方式用 Stdio，需要支持以下操作：

- 读取表中的行
- 创建记录（支持单条和批量）
- 更新记录（支持单条和批量）
- 删除记录（支持单条和批量）

每个工具的描述要写清楚，让 LLM 能准确判断什么时候该用哪个工具。
环境变量需要 Supabase 项目 URL 和 Service Role Key。

先读一下这个 README 了解 Python MCP SDK 的用法：
https://github.com/modelcontextprotocol/python-sdk/tree/main

写完之后更新 README.md 和 TASK.md。

对了，对话拉长了记得及时开新的。如果你发现 LLM 开始让你抓狂，那就是该重开的信号了。

6. 后续开发：一次只做一件事

初始提示之后的修改和迭代，尽量一次只给一个任务，除非是很简单的改动。虽然一口气丢一堆需求给 LLM 很诱人，但任务越聚焦，输出质量越稳定。

好的提示词：

给“列出记录”的函数加一个过滤参数。

不好的提示词：

给列出记录加个过滤功能。另外创建记录那个函数报错说找不到 API Key。还有，README.md 里关于怎么用这个服务器的文档写得太简单了，帮我补充一下。

想要稳定的输出，关键是让 LLM 每次尽量只改一个文件。

改完之后别忘了让 LLM 同步更新 README.md、PLANNING.md 和 TASK.md。

7. 每个功能都要测

可以在全局规则里要求 LLM 实现功能后自动写测试，也可以自己手动跟一步“帮我写个测试”。尽早发现 bug 能避免问题滚雪球，这一步非常重要。

写单测确实有点烦，LLM 写的测试也不总是完美的，但尽量让它把每个功能都覆盖到。实在卡在某个测试上推不动了，跳过也行——先保证主流程。

测试的几个最佳实践：

• 测试文件统一放在 tests/ 目录下。
• 对数据库、LLM 等外部服务的调用一律用 mock，不要真的去请求。
• 每个函数至少覆盖：一个正常场景、一个预期内的失败（验证错误处理）、一个边界情况。

8. Docker 部署（以 Supabase MCP 为例）

这一步算是可选的，而且比较看个人偏好，但还是想分享一下我的习惯。当项目准备上线或者需要分享给别人的时候，我一般会用 Docker（或者 Podman）把它容器化。

LLM 处理 Docker 相关的东西非常靠谱，所以这是我目前觉得最省心的打包方式。而且现在几乎所有云平台（Render、Railway、Coolify、DigitalOcean、Cloudflare、Netlify……）都支持跑 Docker 容器。我的 AI Agent、API 服务和 MCP 服务器全部容器化部署。

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，然后告诉我怎么构建镜像。