Translation | A Complete AI Coding Assistant Workflow

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

This guide lays out a reusable, structured process for working with AI coding assistants to produce production-grade code. The examples build a Supabase MCP server in Python, but the methodology applies to any AI-assisted coding scenario.

1. The Golden Rules

A few core principles first—the global rules and prompts that follow are all built around them:

• Manage your project with Markdown files (README.md, PLANNING.md, TASK.md).
• Keep every file under 500 lines; split into modules once it grows past that.
• Don't let conversations drag on—quality drops as context piles up. Start a fresh chat early.
• Don't cram too many things into one message; one task at a time works best.
• Test early, test often—give every new function a unit test.
• Be specific when you ask for things. The more context you give, the better the AI's answer. Examples help even more.
• Write docs and comments as you go—don't tell yourself you'll "fill them in later."
• Configure environment variables yourself. Never hand API keys to the LLM. Ever.

2. Planning & Task Management

Before writing any code, talk things through with the LLM to scope out the project and break down the tasks. Put the high-level plan in PLANNING.md and the concrete tasks in TASK.md. As the project moves forward, have the AI assistant keep both files up to date.

PLANNING.md

• Purpose: capture high-level information—project vision, architecture, tech choices, constraints, and so on.
• Example prompt: "Write the code following the architecture and decisions in PLANNING.md."
• Have the LLM read this file at the start of every new conversation.

TASK.md

• Purpose: track current tasks, backlog items, and subtasks.
• Contents: the list of work currently in progress, milestones, and issues discovered along the way.
• Example prompt: "Update TASK.md to mark XYZ as done and add a new task for ABC."
• You can also have the LLM maintain the task list automatically via your global rules.

3. Global Rules (AI IDE Configuration)

Global rules are the most effective way to make the AI assistant follow the golden rules. Global rules apply to all projects; project rules only affect the current workspace. All the major AI IDEs support both kinds:

• Cursor: https://docs.cursor.com/context/rules-for-ai
• Windsurf: https://docs.windsurf.com/windsurf/cascade/memories
• Cline: https://docs.cline.bot/prompting/prompt-engineering-guide
• Roo Code: configured the same way as Cline

Below is a sample rule set (using the Supabase MCP server as the example) that you can grab as a template:

Project Awareness & Context

• Read PLANNING.md at the start of every new conversation to understand the project's architecture, goals, code style, and constraints.
• Check TASK.md before starting a new task. If the current task isn't recorded there, add it with a brief description and the date.
• Strictly follow the naming conventions, directory structure, and architectural patterns in PLANNING.md.

Code Structure & Modularity

• Never let any file exceed 500 lines. When one gets close to the limit, split it into submodules.
• Organize code into separate modules by feature or responsibility.
• Keep import statements clean and consistent—prefer relative imports within packages.

Testing & Reliability

• Write Pytest unit tests for every new feature (functions, classes, routes, etc.).
• After changing any business logic, check whether existing tests need to be updated to match.
• Keep tests in a /tests directory that mirrors the structure of the main codebase.
  • Cover at least the following for each feature:
    • 1 normal case
    • 1 edge case
    • 1 failure case

Task Completion

• Mark a task as done in TASK.md immediately after finishing it.
• Log new issues or subtasks discovered during development under a "Discovered During Work" section in TASK.md.

Coding Style & Conventions

• Use Python as the primary language.

• Follow PEP8, use type hints, and format with black.

• Use pydantic for data validation.

• Use FastAPI for APIs and SQLAlchemy or SQLModel for the ORM (whichever fits).

• Write a docstring for every function, in Google style:

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

Documentation & Readability

• Update README.md whenever you add a feature, change dependencies, or modify the setup steps.
• Comment any non-obvious code so a mid-level developer can follow it.
• For complex logic, add a # 原因： inline comment explaining why the code is written this way, not just what it does.

AI Behavior Rules

• Ask when unsure—never invent missing context.
• Never make up libraries or functions that don't exist—only use verified Python packages.
• Confirm that file paths and module names actually exist before referencing them.
• Never delete or overwrite existing code unless I explicitly ask for it or it's part of a task in TASK.md.

4. Setting Up MCP

MCP lets the AI assistant interact directly with external services, for example:

• Working with the file system (reading, writing, refactoring, multi-file edits)
• Searching the web with Brave (especially handy for looking up docs)
• Using Git (switching branches, viewing diffs, committing code)
• Hooking into memory stores and other tools (Qdrant, for instance)

Looking for more MCP servers? There are curated lists online with a huge number of MCP servers, install instructions included.

MCP configuration docs for each IDE:

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

Example prompt to use with the Git MCP:

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

5. The First Prompt of the Project

The opening prompt matters enormously. No matter how detailed your PLANNING.md is, how well-groomed your TASK.md is, or how thorough your global rules are, that first prompt still needs to be as specific as possible—tell the LLM what you want to build and which docs it can reference.

The specifics depend on your project, but the best thing you can do is give it a similar example to work from. The best-performing prompts in bolt.new, v0, and Archon all come with examples, without exception. If you're using particular tools, frameworks, or APIs, you'll usually need to supply the relevant docs as well.

There are three ways to provide reference material:

1. Use your AI IDE's built-in documentation indexing. In Windsurf, for example, typing @mcp and hitting Tab tells it to search the MCP docs.
2. Let the LLM go find things online itself through an MCP server like Brave. For example: "Search for how other Python MCP servers are implemented."
3. Paste example code or doc excerpts directly into the prompt.

An opening prompt for building the Supabase MCP server:

参考 @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。

Oh, and remember to start a new conversation once the current one gets long. If you notice the LLM starting to drive you crazy, that's your cue to start over.

6. Iterating: One Thing at a Time

For the changes and iterations after the initial prompt, stick to one task per message unless the change is trivial. Dumping a pile of requirements on the LLM at once is tempting, but the more focused the task, the more consistent the output.

A good prompt:

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

A bad prompt:

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

The key to consistent output is having the LLM change as close to one file at a time as possible.

After each change, don't forget to have the LLM update README.md, PLANNING.md, and TASK.md to match.

7. Test Every Feature

You can require the LLM to write tests automatically after implementing each feature via your global rules, or manually follow up with "write me a test for this." Catching bugs early keeps problems from snowballing—this step really matters.

Writing unit tests is admittedly a bit of a chore, and LLM-written tests aren't always perfect, but try to get every feature covered. If you get truly stuck on one test, it's fine to skip it—keep the main flow working first.

A few testing best practices:

• Keep all test files in a tests/ directory.
• Mock every call to external services like databases and LLMs—never hit them for real.
• Cover at least three cases per function: one normal scenario, one expected failure (to verify error handling), and one edge case.

8. Docker Deployment (Supabase MCP as the Example)

This step is somewhat optional and largely a matter of personal preference, but I want to share my habit anyway. When a project is ready to go live or needs to be shared with others, I usually containerize it with Docker (or Podman).

LLMs are remarkably reliable at anything Docker-related, so this is the most painless packaging approach I've found. On top of that, virtually every cloud platform these days (Render, Railway, Coolify, DigitalOcean, Cloudflare, Netlify…) can run Docker containers. My AI agents, API services, and MCP servers are all deployed as containers.

Example 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"]

Build command:

docker build -t mcp/supabase .

And a prompt to have the LLM generate it for you:

帮这个 MCP 服务器写一个基于 requirements.txt 的 Dockerfile，然后告诉我怎么构建镜像。