写给跃跃欲试的你上一章我们认识了 AI 搭档你大概已经迫不及待想对它发号施令了。但别急——就像请一位大厨来家里做饭之前你得先把厨房收拾干净告诉他锅碗瓢盆在哪儿。这一章我们要做两件事搭好 Python 开发环境以及配置 Agent 的工作环境。前者让你能跑代码后者让 Agent 能懂你。2.1 为什么要先搭环境这是 SDD 精神的延伸你还记得 SDD 的核心原则吗先定义再实现。环境搭建本身就是一次迷你 SDD 实践规格确定 Python 版本、依赖库、测试框架、Agent 配置文件验证用一条assert和一次 Agent 对话确认环境就绪固化把依赖清单保存到requirements.txt把 Agent 规则写入Agent.md让环境可复现只有环境是确定的Agent 的产出才是可预期的。如果 Agent 用 Python 3.12 的语法生成代码而你本地是 Python 3.8那测试跑不过可不是 Agent 的错。2.2 安装 Python给 Agent 准备一个标准化厨房如果你是 Windows 用户去 python.org 下载最新 3.10 或 3.11 的安装包。安装时务必勾选 “Add Python to PATH”。macOS 或 Linux 用户可以用brew install python3.11或系统包管理器安装。完成后打开终端输入python --version如果屏幕上出现Python 3.10.x或更高恭喜你厨房的灶台已经点着了。布道师碎碎念版本号很重要。我们后面用的类型提示简化语法、pytest最新特性都需要 3.10。统一版本就是在写环境的第一条“规格”。2.3 虚拟环境给 Agent 一个干净的“专属厨房”你未来会做很多项目。如果所有项目的依赖都装在全局 Python 里迟早会打架——“项目 A 需要flask2.0项目 B 需要flask3.0”。Agent 帮不了你解决这个因为它假设你的环境是干净的。虚拟环境就是给每个项目一个独立的 Python 解释器和包空间。创建它# 进入你想存放项目的文件夹 cd ~/projects # 创建项目文件夹 mkdir sdd-tdd-agent-login cd sdd-tdd-agent-login # 创建虚拟环境 python3 -m venv venv激活虚拟环境Windowsvenv\Scripts\activatemacOS/Linuxsource venv/bin/activate激活后终端提示符前面会出现(venv)。现在这个“厨房”里什么都没有我们开始往里放工具。2.4 安装核心依赖给 Agent 备齐食材# 确保在虚拟环境激活状态下 pip install flask pytest pytest-html bcrypt安装完成后把依赖清单“冻结”成文件这样 Agent 和你都能知道当前环境里有什么pip freeze requirements.txt打开requirements.txt你应该能看到类似bcrypt5.0.0 blinker1.9.0 click8.4.2 Flask3.1.3 iniconfig2.3.0 itsdangerous2.2.0 Jinja23.1.6 MarkupSafe3.0.3 packaging26.2 pluggy1.6.0 Pygments2.20.0 pytest9.1.1 pytest-html4.2.0 pytest-metadata3.1.1 Werkzeug3.1.8 ...这就是你的“食材清单”。以后任何人包括未来的你只需要pip install -r requirements.txt就能瞬间拥有和你一模一样的实验环境。这也是契约——环境契约。2.5 选择你的编辑器与终端推荐VS Code。免费、跨平台、插件生态强大。安装后装几个必备插件Python微软官方智能提示、调试、测试集成Pylance更快的语言服务器确保编辑器能识别你的虚拟环境按CtrlShiftPMac 是CmdShiftP输入 “Python: Select Interpreter”选择venv里的那个解释器。2.6 认识pytestAgent 的“眼睛”pytest是我们和 Agent 共同的测试框架。Agent 会用它来跑测试、看红绿状态。我们先手动感受一下。新建test_hello.py# test_hello.py def test_passing(): assert (1 1) 2 def test_failing(): assert (1 1) 3 # 故意写错看红灯在终端运行pytest你会看到test_hello.py .F [100%] FAILURES ________________ test_failing ____________________ def test_failing(): assert (1 1) 3 E assert 2 3 test_hello.py:5: AssertionError short test summary info FAILED test_hello.py::test_failing - assert 2 3 1 passed, 1 failed in 0.05s.表示通过绿F表示失败红pytest会清晰告诉你哪个断言失败了期望值是什么实际值是什么把故意写错的测试改回正确再次运行pytest看一片绿点。这就是 Agent 以后每次写完代码都会做的事情——自动运行测试确认全绿。2.7 配置 Agent 工作环境三份文件让 AI 认识你现在环境能跑 Python 了但 Agent 还不知道自己要干什么、项目长什么样、规矩是什么。我们需要创建三份文件让 Agent “进入角色”。2.7.1Agent.mdAgent 的“身份证”和“行为准则”这是 Agent 的核心配置文件定义了它是什么角色、有什么能力、必须遵守什么规则。--- agent: name: sdd-tdd-python-dev version: 1.0.0 role: full-stack-developer language: python framework: flask database: sqlite testing: pytest --- # Agent: SDDTDD Python 开发者 ## 角色 你是一位严格遵循 SDD规格驱动开发和 TDD测试驱动开发的 Python 后端开发专家。 你的用户是一位大学生或初级程序员你的产出将帮助他们学习专业的开发方法。 ## 核心能力 -解析 Spec.md 中的结构化需求规格 -基于规格自动生成 pytest 测试用例TDD-Red 阶段 -编写刚好通过测试的最小实现代码TDD-Green 阶段 -在测试全绿后执行代码重构TDD-Refactor 阶段 -集成 SQLite 数据库和 Flask Web 框架 -自动生成需求追溯矩阵和测试报告 ## 行为约束 ### 你必须做的 1.✅ **每次任务前**先读取 Spec.md 和 Task.md 2.✅ **在写任何实现代码之前**先写测试代码 3.✅ **每次代码修改后**立即运行 pytest 确认全绿 4.✅ **使用 bcrypt** 进行密码哈希 5.✅ **使用 UUID v4** 作为用户 ID 6.✅ **所有错误码**必须与 Spec.md 中定义的一致 7.✅ **完成任务后**更新 Task.md 中的进度 ### 你绝不能做的 1.❌ **绝不**在 Spec.md 未定义的情况下编写实现代码 2.❌ **绝不**在测试全红之前编写实现代码 3.❌ **绝不**在数据库中存储明文密码 4.❌ **绝不**过度设计——只写刚好通过测试的代码 5.❌ **绝不**跳过人类审查环节——生成代码后必须等待确认才能继续 ## 开发工作流 1.读取 Spec.md → 理解需求 2.编写测试代码 → 确认红灯 3.编写最小实现 → 确认绿灯 4.运行全部测试 → 确保全绿 5.重构优化 → 保持全绿 6.更新 Task.md 和 traceability.md ## 输出格式 -代码块使用 python 标记并标注文件名 -错误修复使用 diff 格式展示变更 -完成任务后输出简要总结通过了几个测试、生成了多少行代码这份文件就是 Agent 的“职业守则”。它告诉 Agent你是谁、你能做什么、你必须遵守什么。当你对 Agent 说“帮我写注册功能”时它会先查 Agent.md再查 Spec.md然后才开始干活。2.7.2Task.md当前任务的“待办清单”Agent.md 定义了 Agent 的身份但 Agent 还需要知道当前要完成什么具体任务。这就是Task.md的作用。--- task: id: REG-001 title: 实现用户邮箱密码注册功能 status: not-started priority: high assigned_to: sdd-tdd-python-dev --- # 任务: 用户邮箱密码注册功能 ## 任务描述 基于 Spec.md 中的需求规格完整实现用户注册功能 包括输入校验、密码哈希、数据持久化和 REST API 端点。 ## 子任务 ### ⬜ 第一阶段: 准备工作 -[ ] 阅读并理解 Spec.md 中的全部需求 -[ ] 确认项目依赖已安装flask, pytest, bcrypt ### ⬜ 第二阶段: TDD-Red编写测试 -[ ] 编写成功注册测试 -[ ] 编写邮箱格式校验测试参数化缺 、空串、超长 -[ ] 编写密码强度校验测试参数化过短、过长、纯字母、纯数字 -[ ] 编写重复注册测试 -[ ] 编写邮箱规范化测试大小写、空格 ### ⬜ 第三阶段: TDD-Green最小实现 -[ ] 实现邮箱格式校验逻辑 -[ ] 实现密码强度校验逻辑 -[ ] 实现重复注册检查逻辑 -[ ] 实现邮箱规范化逻辑 -[ ] 实现 bcrypt 密码哈希 -[ ] 实现 UUID v4 用户 ID 生成 ### ⬜ 第四阶段: TDD-Refactor重构优化 -[ ] 提取常量和错误码 -[ ] 拆分校验辅助函数 -[ ] 引入 UserRepository 数据仓库层 ### ⬜ 第五阶段: 集成与交付 -[ ] 实现 SQLite 数据持久化 -[ ] 实现 Flask API 端点 -[ ] 编写 API 集成测试 -[ ] 生成需求追溯矩阵和测试报告 ## 验收标准 -[ ] 全部 pytest 测试通过单元 集成 -[ ] 数据库中密码为 bcrypt 哈希格式 -[ ] API 返回格式符合 Spec.md 定义 -[ ] traceability.md 覆盖所有规格条目 -[ ] 代码无魔法值结构清晰Task.md 就是一份“任务清单”。你可以在任何时候更新它——添加新任务、调整优先级、标记完成状态。Agent 每次被调用时都会先看这份清单知道自己做到哪了、接下来该做什么。2.7.3SystemPrompt.mdAgent 的“记忆背景”有时候你需要给 Agent 一些额外的上下文比如当前项目的技术栈细节、你个人的编码偏好、或者一些特殊约定。这些不适合写在 Agent.md那是通用规则也不适合写在 Task.md那是具体任务所以有第三份文件。# SystemPrompt 你是一个遵循 SDD规格驱动开发和 TDD测试驱动开发流程的 Python 开发助手。 ## 项目上下文 - 项目名称: sdd-tdd-agent-login - 项目目标: 教学演示 SDD TDD Agent 开发模式 - 用户群体: 大学生 / Python 初学者 - 语言: Python 3.10 - Web 框架: Flask 3.x - 数据库: SQLite 3通过 Python 内置 sqlite3 模块操作 - 测试框架: pytest 8.x含 pytest-html 报告插件 - 密码安全: bcrypt 4.x - 包管理: pip venv ## 项目文件结构 - Spec.md — 唯一的需求真相来源Agent 必须严格遵守 - Agent.md — Agent 的角色定义和行为约束 - Task.md — 当前开发任务的待办清单 - register.py — 核心业务逻辑 - app.py — Flask Web API 入口 - database.py — SQLite 数据库连接与表初始化 - test_register.py — 注册功能单元测试套件 - test_api.py — API 端到端集成测试套件 - pytest.ini — pytest 配置与自定义标记 - traceability.md — 需求追溯矩阵Agent 负责自动维护 ## 编码偏好 - 使用 Python 类型提示如 def register(email: str, password: str) - dict: - 私有辅助函数以下划线开头如 _validate_email - 常量使用大写加下划线如 EMAIL_MAX_LENGTH - 错误码常量集中在文件顶部定义 - 数据库操作封装在 UserRepository 类中 - 测试函数名清晰描述场景如 test_register_duplicate_email ## 注意事项 - 代码是教学用的注释和 docstring 要清晰易懂 - 每个测试函数都有 docstring 说明它验证的是 Spec.md 的哪一条 - 所有生成的文件使用 UTF-8 编码 ## 目标 - 先阅读并理解项目中的 Spec.md 和 Task.md。 - 先编写测试再实现最小代码。 - 每次修改后执行 pytest 验证结果。 - 仅实现规格中明确要求的功能避免过度设计。 ## 项目约束 - 使用 Python 3。 - 使用 Flask 构建 Web 接口。 - 使用 pytest 进行测试。 - 使用 SQLite 进行数据持久化。 - 使用 bcrypt 进行密码哈希。 - 使用 UUID v4 生成用户 ID。 ## 开发原则 1. 先看规格再写测试。 2. 测试失败后再实现功能。 3. 保持代码简洁、清晰、可维护。 4. 运行完整测试集确保全绿。 5. 任务完成后更新 Task.md 和 traceability.md。2.8 创建项目骨架让 Agent 一看就懂现在我们把所有文件和文件夹创建出来。在终端执行# 在项目根目录下 mkdir docs # 创建所有核心文件 touch Agent.md touch Task.md touch SystemPrompt.md touch database.py touch register.py touch app.py touch test_register.py touch test_api.py touch pytest.ini touch traceability.md touch docs/Spec.md把上一节的三份 Agent 配置文件内容分别粘贴进去。database.py、register.py、app.py、测试文件暂时空着——Agent 会帮我们填。完成后你的项目结构应该是这样sdd-tdd-agent-login/ ├── Agent.md # Agent 角色定义 ✅ ├── Task.md # 当前任务清单 ✅ ├── SystemPrompt.md # 系统上下文 ✅ ├── pytest.ini # pytest 配置下一章写 ├── requirements.txt # 依赖清单 ✅ ├── traceability.md # 追溯矩阵空Agent 会填 ├── database.py # 数据库空 ├── register.py # 核心逻辑空 ├── app.py # API 入口空 ├── test_register.py # 单元测试空 ├── test_api.py # 集成测试空 ├── docs/ │ └── Spec.md # 规格文档下一章写 └── venv/ # 虚拟环境 ✅2.9 环境验收确认一切就绪最后我们来一次“环境级验收测试”。创建test_environment.py# test_environment.py import sys def test_python_version(): 确保 Python 版本 ≥ 3.10 assert sys.version_info (3, 10), 本课程需要 Python 3.10 def test_pytest_available(): 确保 pytest 已安装 import pytest assert pytest.__version__ is not None def test_flask_available(): 确保 Flask 已安装 import flask import importlib.metadata assert importlib.metadata.version(Flask) is not None def test_bcrypt_available(): 确保 bcrypt 已安装 import bcrypt import importlib.metadata assert importlib.metadata.version(bcrypt) is not None运行pytest test_environment.py test_hello.py -v如果四个环境测试全绿加上之前的 hello 测试也绿那就说明✅ Python 版本正确✅ 核心依赖全部就绪✅ pytest 工作正常✅ 虚拟环境隔离有效你的实验台和 Agent 工作环境搭建完成。本章小结这一章我们做了两件大事搭好了 Python 实验台安装了 Python 3.10创建了虚拟环境venv安装了 Flask、pytest、bcrypt 等核心依赖冻结了requirements.txt跑通了第一个测试配置了 Agent 工作环境Agent.md定义了 Agent 的角色、能力、行为约束“你是谁你必须遵守什么规则”Task.md定义了当前任务的待办清单“你现在要做什么”SystemPrompt.md提供了项目上下文和编码偏好“这个项目的背景信息”这三份文件就是 Agent 的“入职手册”。从下一章开始我们就要真正开始和 Agent 协作——先写 Spec.md然后对 Agent 说“请开始你的工作。”口诀时刻环境搭好是第一关Agent 三件要齐全角色任务上下文搭档知己才不偏。下一章我们将进入整个课程最核心的环节之一编写一份 Agent 可以精确解析、自动生成测试和代码的 Spec.md。你会发现把需求写清楚比写代码本身更需要功力。准备好了吗