Skip to content

workflow_cn.md

Latest commit

 

History

History
163 lines (121 loc) · 6.02 KB

workflow_cn.md

File metadata and controls

163 lines (121 loc) · 6.02 KB
Raw
id python-ai-coding-workflow
type guide
title 用 AI Coding 写好 Python
summary 一套契约优先的工作方法，用 coding agent 完成小而可测、能够安全交付的 Python 修改。
lang zh-CN
content_version 1
status reviewed
reviewed_on 2026-09-02

用 AI Coding 写好 Python

AI coding agent 可以快速生成语法和样板代码，但它不会自动理解项目边界、真实运行环境、 用户风险或完成标准。高质量 AI Coding 的核心不是写出更多代码，而是把工作拆成可理解、 可验证、可回退的小改动。

“使用 AI Coding”与“开发 AI Agent”是两件事：前者是开发方式，后者只是可能构建的一类 产品。无论最终开发 API、自动化脚本、数据工具还是 Agent，都应使用同一套可靠工作循环。

1. 先给任务建立契约

在让 coding agent 修改代码前，至少写清：

  • 目标：用户或系统最终能完成什么；
  • 当前行为：现在具体发生了什么；
  • 输入与输出：数据格式、边界和错误形式；
  • 约束：允许修改什么，明确不修改什么；
  • 验收：要运行哪些测试、命令或真实操作；
  • 权限：是否允许联网、安装依赖、提交、推送或部署。

可直接复用下面的任务模板：

目标：
当前行为：
期望行为：
允许修改：
禁止修改：
验收方式：
提交/推送/部署权限：

模糊的“优化一下”通常会得到范围过大的修改；明确契约才能让 AI 承担执行，而不是替你 猜测产品决定。

2. 要求 AI 先读取仓库

一个可靠的 Python 修改应先检查：

  1. AGENTS.md、README.md 和贡献规则；
  2. 当前 Git 分支、工作树和远程状态；
  3. pyproject.toml、Python 版本和依赖锁文件；
  4. 与目标最接近的实现和测试；
  5. 真实入口，例如 CLI、API route、任务脚本或浏览器流程。

不要让 AI 仅凭 README、TODO 或文件名推断实现已经存在。文档、代码、测试和真实运行结果 需要相互印证。

3. 固定 Python 环境

AI 生成的代码只有在可复现环境中才有意义：

  • 固定 Python 版本；
  • 使用隔离虚拟环境；
  • 声明直接依赖并锁定完整依赖树；
  • 不把本机全局包当成项目依赖；
  • 在干净环境中至少完成一次安装和测试。

现代项目可以参考 uv 官方文档；虚拟环境的底层行为见 Python venv 文档。

4. 每次只实现最小可验证改动

让 coding agent 遵循下面的粒度：

  1. 找到一个明确失败或缺失行为；
  2. 先确定测试或验收观察点；
  3. 修改最少的相关文件；
  4. 运行局部测试；
  5. 再运行受影响范围的完整测试；
  6. 检查 diff 中是否混入无关修改。

一个改动如果无法用一句话说明，通常还可以继续拆小。避免让 AI 同时重构架构、升级依赖、 修改文案并发布生产环境。

5. 用类型、验证和测试约束生成结果

Python 的动态特性适合快速开发，也容易让 AI 生成“看起来合理但边界不清”的代码。 优先使用：

测试至少覆盖：

  • 正常输入；
  • 空值、缺失字段和错误类型；
  • 超时、重试和外部服务失败；
  • 权限不足和不可恢复错误；
  • 不应发生的文件、网络或数据库副作用。

绿色测试只能证明被检查的行为通过，不能证明需求正确，也不能代替真实运行验收。

6. 验证真实入口

完成代码后，运行用户真正会使用的入口：

  • CLI：执行真实命令并检查退出码、标准输出和错误输出；
  • API：检查请求、响应、状态码、超时和验证错误；
  • Web：使用真实浏览器检查 DOM、交互、网络请求和控制台；
  • 自动化：使用无害输入检查重复运行、失败恢复和幂等性；
  • Agent：检查工具参数、结构化输出、权限、轨迹和失败边界。

HTTP 客户端可参考 HTTPX，API 边界可参考 FastAPI，浏览器流程可参考 Playwright for Python。

7. 单独检查副作用和权限

AI 生成的 Python 经常会操作文件、Shell、浏览器、网络、数据库或模型工具。接受修改前 逐项确认：

  • 文件目标是否精确，是否可能覆盖用户数据；
  • subprocess 是否避免不必要的 shell=True；
  • 网络请求是否有超时、重试上限和目标限制；
  • 日志和错误信息是否暴露凭据或私人数据；
  • 数据库修改是否可审计、可回滚；
  • Agent 工具是否使用最小权限并要求必要确认。

相关标准库行为见 subprocess 文档和 pathlib 文档。

8. 交付时报告证据，而不是只说“完成”

一次完整交付至少说明：

  • 修改了什么；
  • 没有修改什么；
  • 实际运行了哪些测试和验收；
  • 哪些结果已经验证；
  • 哪些结果仍然未知；
  • 是否已经提交、推送或部署，以及对应的精确版本。

推荐完成标准：

[ ] 工作树只包含本次范围内的修改
[ ] 类型、格式和单元测试通过
[ ] 失败路径和边界输入已检查
[ ] 真实 CLI/API/浏览器入口已验证
[ ] 文件、网络、凭据和数据库副作用已检查
[ ] 文档与当前实现一致
[ ] 提交、远程和部署版本可以精确核对

下一步

根据正在开发的系统，从仓库 README 中继续选择 Python 基础、Web/API、自动化或 AI Agent 的一手资料。资源目录帮助你选择可靠上下文；这套工作循环帮助你判断 AI 生成的修改是否 真的可以接受。