1. 项目概述：一个为AI编程时代量身定制的Python项目模板

如果你和我一样，日常开发重度依赖像 Cursor 这样的 AI 编程助手，那你肯定也经历过类似的烦恼：每次新建一个 Python 项目，都得从头开始配置一遍 pyproject.toml 、设置 linting 规则、配置 CI/CD、还得琢磨怎么让 AI 助手更好地理解你的项目结构和编码规范。这个过程重复、琐碎，而且容易出错。 scot.py 的出现，就是为了终结这种低效的重复劳动。它不是一个普通的项目脚手架，而是一个深度集成了现代开发工具链与 AI 辅助编程最佳实践 的智能模板。它的核心哲学是 “跳过配置，直接构建” ，让你从项目诞生的第一分钟起，就拥有一个结构清晰、工具完备、并且能与 AI 助手高效协作的开发环境。

简单来说，scot.py 为你预设好了从代码质量检查（Ruff）、类型提示（Pyright）、依赖管理（Poetry）到自动化流水线（GitHub Actions）的一切。但它的杀手锏在于 .cursor/rules 目录下那套精心设计的规则文件。这些规则不是简单的代码风格提示，而是定义了如何与 AI 助手进行结构化、可追溯的协作流程。它引导你将一个模糊的想法，通过“项目定义 -> 功能拆解 -> 任务实现”的三步工作流，转化为清晰、可执行的代码。对于追求开发效率、代码质量和团队协作一致性的开发者或团队而言，这个模板能节省大量前期配置和沟通成本，让 AI 真正成为你的结对编程伙伴，而非一个需要不断调教的“实习生”。

2. 核心设计理念与工作流拆解

2.1 为什么是“AI-Optimized”而不仅仅是“Pre-configured”？

市面上优秀的 Python 项目模板不少，比如 Cookiecutter 的各种变体。它们大多解决了“工具链统一”的问题。但 scot.py 往前走了一步，它解决的是“人机协作流程标准化”的问题。在 AI 编程时代，最大的瓶颈往往不是工具本身，而是如何高效、准确地向 AI 传达意图，并管理其产出。

传统的模板告诉你“用什么工具”，而 scot.py 在此基础上定义了“怎么用 AI 工具”。它的 .cursor/rules 目录包含了三个核心的 Markdown 文档（ .mdc 后缀，专为 Cursor 设计）：

  • @new_project.mdc : 引导 AI 助手帮你梳理项目愿景、核心价值和初始范围。
  • @new_feature.mdc : 将模糊的需求转化为结构化的功能规格说明书、技术方案和可执行的任务列表。
  • @implement_feature.mdc : 指导 AI 按任务列表逐一实现代码，并保持上下文清晰。

这个设计背后的逻辑是 “上下文隔离” 和 “渐进式细化” 。每次开启一个新的聊天会话（Chat）来执行一个步骤，可以避免 AI 因上下文过长而“遗忘”或“混淆”早期指令。同时，从愿景到任务，信息是逐层具体化的，这符合人类和 AI 共同思考的自然过程。我实测下来，遵循这个流程，AI 生成的代码和文档的准确性与一致性显著提升，后期返工的概率大大降低。

2.2 工具链选型背后的考量

scot.py 的每一个工具选择都经过了深思熟虑，旨在平衡性能、易用性和社区生态。

  1. Poetry 作为依赖管理核心 ：相比传统的 requirements.txt + venv ，Poetry 提供了声明式依赖管理、锁文件确保一致性、以及虚拟环境管理的统一界面。它对项目结构的标准化（ pyproject.toml 作为单一配置源）也为 AI 助手理解项目提供了便利。模板中默认设置 virtualenvs.in-project=false 是一个细节但重要的选择，主要是为了避免与 Docker 卷映射时可能产生的路径冲突问题。

  2. Ruff 作为 Linter 和 Formatter ：这是一个非常现代且明智的选择。Ruff 用 Rust 编写，速度极快，同时集成了数十种常用插件的规则（如 flake8, isort 的部分规则）。用它替代传统的 flake8 + black + isort 组合，可以大幅缩短 CI/CD 流水线和本地钩子的运行时间。对于追求快速反馈的开发者，尤其是结合 AI 的高频代码生成场景，速度优势非常明显。

  3. Pyright 进行类型检查 ：在 Python 生态中，Pyright（也是 VSCode Pylance 的后端）因其速度快和类型推断能力强而备受青睐。强制类型检查（通过 CI 和 pre-commit）能提前捕获大量由 AI 生成的潜在类型错误，提升代码健壮性。虽然 mypy 更老牌，但 Pyright 在性能和与编辑器的集成上通常表现更好。

  4. GitHub Actions + Pre-commit 构成质量门禁 ： .github/workflows/ci.yml 定义了一个完整的 CI 流水线，在每次推送或拉取请求时自动运行 linting、类型检查和测试。而 pre-commit 则在本地提交前运行一套更轻量级的检查，确保有问题的代码不会进入版本库。这种“本地拦截 + 云端验证”的双重保障，是维持代码库长期健康的关键。

3. 从零开始：详细配置与上手实操

3.1 环境准备与项目初始化

假设你已经在本地安装了 Python 3.10+ 和 Git。首先，我强烈建议使用 pyenv 来管理 Python 版本，这能避免系统 Python 版本带来的各种诡异问题。

# 安装 pyenv (以 macOS 为例，其他系统请参考官方文档)
brew update
brew install pyenv

# 安装并启用指定 Python 版本
pyenv install 3.11.5
pyenv global 3.11.5  # 或仅在项目目录下使用 pyenv local 3.11.5

接下来，使用 Option 1: GitHub Template 来创建你的新项目，这是最干净、最推荐的方式。

  1. 访问 scot.py 的 GitHub 仓库页面 。
  2. 点击绿色的 “Use this template” 按钮。
  3. 在弹出页面中，为你新生成的项目仓库命名（例如 my-awesome-api ），选择公开或私有，然后点击创建。
  4. 将新创建的仓库克隆到本地： 
    git clone https://github.com/your-username/my-awesome-api.git
cd my-awesome-api

注意 ：不要直接 git clone 原始的 ezorita/scotpy 仓库，那样你会失去“模板仓库”的属性，未来无法方便地同步模板更新。使用“Use this template”功能生成的是属于你的全新仓库，与模板源仓库脱钩。

3.2 依赖安装与编辑器关键配置

进入项目目录后，第一件事是安装 Poetry（如果尚未安装），然后通过 Poetry 安装项目依赖。

# 安装 Poetry (推荐方式)
curl -sSL https://install.python-poetry.org | python3 -

# 使用 Poetry 安装项目依赖并创建虚拟环境
poetry install

poetry install 命令会读取 pyproject.toml ，创建虚拟环境（默认在系统缓存目录），并安装所有开发和生产依赖。安装完成后，一个至关重要的步骤是配置你的编辑器（这里是 Cursor）使用正确的 Python 解释器。

  1. 在 Cursor 中打开本项目。
  2. 按下 Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows/Linux)，打开命令面板。
  3. 搜索并选择 “Python: Select Interpreter” 。
  4. 在弹出的列表中，你应该能看到一个标识为 Poetry (my-awesome-api) 或类似名称的解释器。选择它。

为什么这一步至关重要？ 如果 Cursor 的 AI Agent 使用了错误的 Python 环境（比如你的系统 Python），它将无法感知到你项目中使用 poetry add 安装的第三方库，从而导致它在代码建议时导入失败或给出错误的函数签名。正确配置解释器是 AI 辅助编程能正常工作的基石。

最后，激活 pre-commit 钩子，让它在每次 git commit 时自动运行代码检查：

poetry run pre-commit install

现在，当你尝试提交代码时，Ruff 和 Pyright 会自动运行。如果检查失败，提交会被阻止，你必须先修复问题。

3.3 理解项目结构与定制化

初始化后，你的项目结构如下。理解每个部分的作用有助于你后续的定制。

my-awesome-api/
├── .cursor/
│   └── rules/                 # AI 协作规则，这是模板的灵魂
│       ├── @new_project.mdc
│       ├── @new_feature.mdc
│       └── @implement_feature.mdc
├── .github/
│   └── workflows/
│       └── ci.yml            # CI/CD 流水线定义
├── .vscode/                  # 编辑器设置（Cursor 兼容）
│   ├── settings.json         # 推荐的工作区设置
│   └── extensions.json       # 推荐的扩展列表
├── src/                      # 你的源代码放在这里
│   └── my_awesome_api/      # 根据 pyproject.toml 中的 name 自动生成
│       └── __init__.py
├── tests/                    # 测试代码
├── .pre-commit-config.yaml   # 预提交钩子配置
├── CONTRIBUTING.md           # 贡献指南（需根据项目修改）
├── LICENSE                   # 许可证（需替换为你项目的许可证）
├── poetry.toml              # Poetry 配置（如虚拟环境位置）
├── pyproject.toml           # 项目核心配置（依赖、脚本、工具）
└── README.md                # 项目说明（需重写）

需要立即定制的文件 ：

  • README.md : 完全重写，描述你自己的项目。
  • LICENSE : 替换为适合你项目的许可证（如 MIT, Apache 2.0）。
  • CONTRIBUTING.md : 根据你团队的协作习惯进行修改。
  • pyproject.toml : 修改 [tool.poetry] 部分下的 name , version , description , authors 等字段。 src/ 目录下的包名目录也会相应更新。

选择性定制的配置 ：

  • poetry.toml : 如果你想将虚拟环境创建在项目内的 .venv 目录（便于某些编辑器自动识别），可以将 virtualenvs.in-project 改为 true 。记得将 .venv 加入 .gitignore 。
  • .github/workflows/ci.yml : 如果你不使用 Codecov，可以删除或注释掉相关步骤。你也可以添加部署、构建 Docker 镜像等其他步骤。
  • .cursor/rules/ : 高级用户可以修改这些 .mdc 文件，以更贴合你团队特有的 AI 协作习惯。

4. 核心工作流实战：与AI助手协作开发一个功能

让我们通过一个具体的例子，演示如何使用 scot.py 定义的工作流，从零开始开发一个简单的“待办事项 API”的“创建任务”功能。

4.1 第一步：定义项目愿景 ( @new_project.mdc )

  1. 在 Cursor 中，确保你打开了 my-awesome-api 项目，并且 Python 解释器已正确设置。
  2. 打开一个新的 Cursor Chat 窗口。
  3. 在输入框中，键入 @new_project 并选择弹出的 @new_project.mdc 规则文件。
  4. AI Agent 会被激活，并开始引导你对话。它可能会问：
    • “What is the name of your project?” (你的项目名是什么？)
    • “What is the primary goal or vision for this project?” (项目的主要目标或愿景是什么？)
    • “Who are the target users?” (目标用户是谁？)
    • “What are the key features you envision?” (你设想的核心功能有哪些？)

你可以这样回答（示例）：

  • 项目名 : Todo API Service
  • 愿景 : 构建一个简洁、高性能的 RESTful API，用于管理个人或团队的待办事项。
  • 目标用户 : 需要快速集成待办事项功能的移动应用或前端开发者。
  • 核心功能 : 用户认证、待办事项的增删改查、任务分类、截止日期提醒。
  1. 经过几轮问答，AI 会总结并生成一个 project/vision.md 文件。 务必仔细审查这个文件 ，确保它准确反映了你的想法。这是后续所有工作的蓝图。

实操心得 ：在这一步使用 Claude 4 模型（如果可用）效果最好，因为它更擅长理解和梳理复杂的、非结构化的需求。不要急于确认，多花几分钟和 AI 讨论细节，清晰的愿景能极大减少后续的返工。

4.2 第二步：拆解功能 ( @new_feature.mdc )

项目愿景有了，现在我们要开发第一个具体功能：“创建待办事项”。

  1. 开启一个新的 Chat 会话 。这是关键！避免与上一步的上下文混合。
  2. 在新的 Chat 中输入 @new_feature 并选择 @new_feature.mdc 。
  3. AI 会询问你要开发什么功能。你回答：“Implement a RESTful endpoint to create a new todo item.”
  4. AI 会引导你进行功能定义：
    • 输入参数 ： title (字符串，必填)， description (字符串，可选)， due_date (ISO 格式日期字符串，可选)。
    • 输出 ：返回创建成功的待办事项对象（包含ID、创建时间等）。
    • 错误处理 ：验证输入， title 不能为空；处理数据库错误。
    • 技术栈 ：使用 FastAPI（假设我们选这个框架），SQLAlchemy ORM，Pydantic 做数据验证。
  5. AI 会生成技术实现方案，并最终将任务拆解。完成后，你会在 project/ 目录下看到一个以功能命名的文件夹，例如 project/01_create_todo/ ，里面包含三个文件：
    • feature.md : 功能规格说明书。
    • implementation.md : 技术实现细节（如：使用哪个路由、数据模型设计、依赖注入等）。
    • tasks.md : 详细的任务清单，例如：
      1. Install FastAPI and SQLAlchemy dependencies via Poetry.
      2. Define Pydantic models for request/response.
      3. Define SQLAlchemy model for Todo item.
      4. Create database connection utility.
      5. Implement the POST endpoint /todos .
      6. Write unit tests for the endpoint.

注意事项 ：仔细审查 implementation.md 和 tasks.md 。AI 的拆解可能过于理想化或遗漏某些细节（如数据库迁移、环境变量配置）。你可以手动编辑这些文件，调整任务顺序或补充子任务。一个好的任务清单应该是原子化的，每个任务都能在单独的一次 AI 会话中完成。

4.3 第三步：实现任务 ( @implement_feature.mdc )

现在，我们开始逐个击破 tasks.md 中的任务。

  1. 再次开启一个新的 Chat 会话 。
  2. 输入 @implement_feature 并选择 @implement_feature.mdc 。
  3. AI 会首先读取 project/01_create_todo/tasks.md ，识别出第一个未完成的任务（例如，“1. Install FastAPI and SQLAlchemy dependencies”）。
  4. AI 会询问你是否要执行这个任务。你确认后，它会生成相应的命令或代码。
    • 对于安装依赖的任务，它可能会生成： poetry add fastapi sqlalchemy pydantic 。你只需要复制命令到终端执行。
  5. 任务完成后，AI 会更新 tasks.md ，将第一个任务标记为完成（例如，在前面加上 [x] ）。
  6. 对于下一个任务（如“2. Define Pydantic models”） ， 重复步骤1-3 ：开启一个新 Chat，引用 @implement_feature.mdc 。AI 会读取更新后的 tasks.md ，自动定位到下一个未完成的任务，并开始生成 Pydantic 模型的代码。

这个“新会话 per 任务”的模式是保持 AI 专注度的关键。当实现到第 5 步“实现 POST 端点”时，AI 会根据之前任务生成的模型和工具代码，合成出完整的端点逻辑。

# 例如，AI 可能会在 src/ 下生成类似这样的代码
# src/api/endpoints/todos.py
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from ... import schemas, crud, models
from ...database import get_db

router = APIRouter()

@router.post("/", response_model=schemas.TodoOut)
def create_todo(todo_in: schemas.TodoCreate, db: Session = Depends(get_db)):
    """
    Create a new todo item.
    """
    # 输入验证已由 Pydantic (TodoCreate) 完成
    # 调用 CRUD 层
    db_todo = crud.todo.create(db=db, obj_in=todo_in)
    return db_todo
  1. 在每个任务生成的代码后， 你必须进行人工审查 。运行 poetry run poe lint 和 poetry run poe typecheck 来确保代码风格和类型安全。也可以手动运行一下相关部分，看逻辑是否符合预期。

踩坑实录 ：我曾经在连续实现多个任务时没有开启新会话，导致 AI 的上下文变得混乱，它有时会忘记之前定义的数据模型结构，生成错误的字段引用。严格遵守“一个任务，一个新会话”的纪律，能极大提升生成代码的准确性。另外，不要完全依赖 AI 编写测试，它生成的测试有时覆盖不全边界情况，需要你手动补充和完善。

5. 进阶配置与效能调优

5.1 定制 Cursor Rules 以适应团队规范

scot.py 提供的 .cursor/rules 是一个绝佳的起点，但每个团队都有自己独特的编码习惯和架构偏好。你可以修改这些 .mdc 文件来强化某些规则。

例如，在 @implement_feature.mdc 中，你可以增加更具体的指令：

## 代码生成规范
- 所有数据库操作必须通过 `crud` 模块中的函数进行，不要直接在端点中写 SQLAlchemy 查询。
- 错误响应必须使用项目内定义的统一异常处理器 `app.exception_handler`。
- 为每个新增的公开函数编写 Google 风格的类型提示和文档字符串。
- 优先使用异步 `async/await` 语法（如果项目是异步的）。

你也可以创建新的规则文件，比如 @refactor_code.mdc 来专门指导 AI 进行代码重构，或者 @write_tests.mdc 来规范测试代码的生成（要求必须包含边界条件测试和模拟）。

5.2 集成外部服务与调整 CI/CD

代码覆盖率集成 ：模板默认配置了 Codecov。你需要：

  1. 访问 codecov.io ，用 GitHub 账号登录。
  2. 添加你的 my-awesome-api 仓库。
  3. 在仓库设置中获取上传令牌。
  4. 在你的 GitHub 仓库的 Settings -> Secrets and variables -> Actions 中，添加一个名为 CODECOV_TOKEN 的 secret，值为你获取的令牌。 这样，每次 CI 运行后，覆盖率报告就会自动上传并在 Pull Request 中显示。

添加更多 CI 步骤 ：编辑 .github/workflows/ci.yml ，你可以轻松添加新任务。

# 示例：添加安全漏洞扫描
- name: Run Security Scan
  run: |
    poetry add safety --dev
    poetry run safety check

或者添加构建 Docker 镜像并推送到注册表的步骤。

调整 Pre-commit 钩子 ： .pre-commit-config.yaml 文件定义了本地检查项。你可以添加更多钩子，例如：

- repo: https://github.com/pre-commit/pre-commit-hooks
  rev: v4.5.0
  hooks:
    - id: check-yaml
    - id: end-of-file-fixer
    - id: trailing-whitespace
    - id: detect-private-key # 检测意外提交的私钥

运行 poetry run pre-commit autoupdate 可以自动将钩子更新到最新版本。

5.3 虚拟环境与多环境管理

对于更复杂的项目，你可能需要区分开发、测试和生产环境。Poetry 支持依赖组（Dependency Groups）。

在 pyproject.toml 中，你可以这样配置：

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
ruff = "^0.1.0"
# ... 其他开发工具

[tool.poetry.group.test.dependencies]
pytest-asyncio = "^0.21.0"
httpx = "^0.25.0"
# ... 其他测试专用库

# 默认安装所有组
poetry install
# 仅安装主依赖（不含 dev, test）
poetry install --without dev,test
# 安装主依赖和测试依赖
poetry install --with test

对于生产部署，你可以使用 poetry export 生成 requirements.txt ：

poetry export --without-hashes --format=requirements.txt > requirements.txt

这能兼容那些尚不支持 Poetry 的部署环境（如某些 PaaS 平台）。

6. 常见问题与故障排除

在实际使用 scot.py 模板的过程中，你可能会遇到一些典型问题。这里我总结了一份速查表。

问题现象 可能原因 解决方案
Cursor AI 无法识别项目依赖（如 import 报错） Python 解释器未设置为 Poetry 创建的虚拟环境。 在 Cursor 中按 Cmd/Ctrl+Shift+P ，选择“Python: Select Interpreter”，切换到 Poetry 环境。
运行 poetry install 失败，提示 Python 版本不兼容 本地 Python 版本与 pyproject.toml 中指定的版本不符。 使用 pyenv 安装并切换至指定版本（如 3.10），或在 pyproject.toml 中放宽 Python 版本约束。
Pre-commit 钩子失败，阻止提交 代码不符合 Ruff 或 Pyright 的规则。 运行 poetry run poe lint 和 poetry run poe typecheck 查看具体错误，根据提示修复代码。也可用 poetry run ruff format . 自动格式化。
GitHub Actions CI 流水线失败 1. 代码有 lint/type 错误。
2. 测试用例失败。
3. Codecov 令牌未设置。		 1. 在本地运行 poetry run poe check 通过后再推送。
2. 检查并修复测试逻辑。
3. 在 GitHub 仓库设置中添加 CODECOV_TOKEN secret。
AI 生成的代码不符合项目结构 .cursor/rules 中的规则未明确指定代码生成路径，或 AI 上下文理解有误。 1. 在规则文件中明确指定生成文件应放在 src/ 下的具体位置。
2. 在 Chat 中手动纠正 AI，例如：“请将生成的模型文件放在 src/models.py 中。”
使用 Docker 时，本地虚拟环境路径冲突 模板默认虚拟环境在 ~/.cache/... ，但 Docker 卷映射可能导致路径问题。 考虑在 poetry.toml 中设置 virtualenvs.in-project = true ，并在 .gitignore 中忽略 .venv 。或在 Dockerfile 中直接使用 poetry install --no-root 在容器内创建环境。
@implement_feature.mdc 无法识别下一个任务 tasks.md 文件的格式被意外修改，或 AI 解析出错。 确保 tasks.md 使用标准的 Markdown 任务列表语法（ - [ ] 或 - [x] ）。可以手动编辑该文件，明确标记当前任务。

个人调试技巧 ：当 AI 的行为不符合预期时，一个有效的方法是“重置上下文”。关闭当前 Chat，甚至重启 Cursor，然后从一个全新的会话开始，重新引用规则文件。很多时候，这比在已经混乱的上下文中反复纠错要高效得多。另外，养成随时手动运行 poetry run poe check 的习惯，将 AI 的产出迅速纳入质量检查的闭环，避免问题堆积。

Logo
亚马逊云科技技术品牌专区

更多推荐

cover

Hugging Face Optimum 源码静态评测：模型部署优化框架的工程结构与验证边界

avatar 亚马逊云科技技术品牌专区
cover

智能软件工程AI4SE（一）——智能需求工程

avatar 亚马逊云科技技术品牌专区
cover

车载OBD的6路摄像头同时传，画面卡？选对物联网卡立马流畅回传

avatar 亚马逊云科技技术品牌专区