Python Team

Python 团队协同开发 Skill

任务目标

• 本 Skill 用于：通过虚拟四角色团队（自主学习→PM→架构师→高级程序员）协同工作，将用户的自然语言需求转化为完整的 Python 项目交付物
• 能力包含：自主学习与知识整合、需求分析与澄清、架构设计（自适应项目规模）、代码实现、功能验证、版本控制、功能扩展、项目重构、技能识别与调用、数据库设计与实现、数据层抽象
• 触发条件：用户提出明确的软件开发需求（如"做一个天气查询工具"、"实现一个待办事项系统"、"添加数据导出功能"、"优化代码性能"、"设计用户管理系统"等）

前置准备

• 依赖说明：web_search 工具（已集成）
• 包管理工具：UV（现代 Python 包管理器，快速、可靠、锁定依赖）
  • 安装：pip install uv
  • 项目初始化：uv init
  • 依赖管理：uv add package
• 文件准备：无需前置文件
• 版本控制机制：所有文档和代码必须包含版本信息，使用语义化版本（Semantic Versioning，如 v1.0.0），记录版本历史和变更原因

操作步骤

阶段0：自主学习与知识整合

目标：通过网络搜索获取相关领域知识，生成项目背景文档，为后续阶段提供知识支撑

执行步骤：

1. 识别关键词：从用户需求中提取核心技术、领域、工具关键词

   • 技术关键词：如"REST API"、"WebSocket"、"CSV处理"、"数据库"、"ORM"
   • 领域关键词：如"天气查询"、"待办事项"、"数据分析"、"用户管理"
   • 工具关键词：如"Flask"、"pandas"、"UV"、"SQLAlchemy"、"MongoDB"

2. 执行网络搜索（3-6轮）：

   • 第1轮：搜索"<领域> 最佳实践"，获取通用设计原则
   • 第2轮：搜索"<技术> 框架对比"，如"Flask vs FastAPI 对比"
   • 第3轮：搜索"<功能> 实现方案"，如"Python 天气API调用示例"
   • 第4轮（可选）：搜索"<问题> 常见坑"，如"REST API 常见错误"
   • 第5轮：搜索"Python 3.11+ 新特性"、"框架版本兼容性"、"UV 包管理器最佳实践"、"loguru 日志库最佳实践"
   • 第6轮（新增）：搜索"数据库选型"、"SQLAlchemy vs MongoDB"、"向量数据库对比"、"图数据库对比"、"Repository 模式最佳实践"、"数据库性能优化"

3. 筛选与整合信息：

   • 评估搜索结果的可信度和时效性
   • 提取关键信息：技术选型依据、设计模式、最佳实践、常见问题、版本特性、UV 使用、数据库选型
   • 整合冲突信息，标注不同方案的优缺点
   • 重点关注：版本兼容性、长期维护性、学习资源、UV 包管理优势、数据库特性
   • 生成结构化的知识总结

4. 生成 docs/background.md：

   • 参考 references/background-template.md 的结构
   • 包含：项目背景概述、技术领域知识、最佳实践、工具对比（含版本信息）、常见问题、UV 包管理、数据库相关知识
   • 增强：工具对比维度增加版本兼容性、长期维护性、学习资源
   • 增强：数据库选型指南（SQLite、PostgreSQL、MongoDB、向量数据库、图数据库）
   • 增强：数据库设计与实现最佳实践（ORM/ODM、索引策略、性能优化）
   • 确保信息准确、实用、易于理解

阶段1：项目经理（PM）- 需求分析与文档化

目标：结合背景知识理解用户需求，生成清晰的需求文档，评估项目规模

执行步骤：

1. 结合背景知识分析需求：

   • 阅读 docs/background.md，了解领域最佳实践和常见陷阱
   • 识别用户需求中可能遗漏的关键点（基于领域知识）
   • 评估需求的合理性和可行性

2. 识别需求中的模糊点或不完整之处

3. 最多进行2轮澄清交互（如果需求不明确）：

   • 以"【提问】"开头向用户确认细节
   • 典型问题：功能边界、输入输出格式、非功能要求、技术栈偏好、版本要求、项目规模预期等
   • 示例："做一个天气查询工具" → 澄清"支持哪些城市？数据来源？是否缓存？"

4. 评估项目规模：

   • 小项目：< 5 个功能点，< 500 行代码预期
   • 中型项目：5-10 个功能点，500-2000 行代码预期
   • 大项目：> 10 个功能点，> 2000 行代码预期
   • 在 requirements.md 中明确标注项目规模

5. 数据库需求澄清（新增）：

   • 确认是否需要数据持久化存储
   • 确认数据类型（关系型、文档型、向量、图）
   • 确认数据规模和并发需求
   • 确认是否需要多数据库支持
   • 确认是否需要数据库切换能力

6. 基于用户反馈、背景知识和项目规模评估，生成 docs/requirements.md：

   • 参考 references/requirements-template.md 的结构
   • 包含：功能列表、输入输出说明、非功能性要求、假设与约束、版本要求、项目规模、数据库需求
   • 关键：参考 background.md 中的最佳实践，完善非功能性要求
   • 新增：明确 Python 3.11+ 版本要求、版本控制策略、UV 包管理要求、项目规模、loguru 日志库要求（强制使用）、数据库选型要求（参考 database-selection-guide.md）
   • 确保每个功能点都清晰可执行
   • 记录版本：v1.0.0（初始版本）

阶段2：系统架构师（Architect）- 架构设计

目标：基于需求文档、背景知识和项目规模，设计系统架构，生成设计文档和任务清单

执行步骤：

1. 阅读 docs/requirements.md 和 background.md，理解完整需求、领域知识、项目规模和数据库需求
2. 根据项目规模选择架构组织方式：
   • 小项目：使用单文件或简单文件夹结构

     project/
     ├── main.py
     ├── README.md           # 项目根目录
     ├── pyproject.toml
     ├── uv.lock
     └── docs/               # 文档文件夹
         ├── background.md
         ├── requirements.md
         └── architecture.md
     

   • 大项目：使用标准 Python 项目文件夹组织

     project/
     ├── README.md           # 项目根目录
     ├── pyproject.toml
     ├── uv.lock
     ├── src/
     │   ├── __init__.py
     │   ├── main.py
     │   ├── api/              # API 模块
     │   ├── models/           # 数据模型
     │   ├── services/         # 业务逻辑
     │   ├── repositories/     # 数据访问层（Repository）
     │   └── utils/            # 工具函数
     ├── tests/
     │   └── test_main.py
     └── docs/                  # 文档文件夹
         ├── background.md
         ├── requirements.md
         └── architecture.md
     

3. 设计系统架构：
   • 参考 background.md 中的工具对比，进行技术选型
   • 模块划分与职责分配（根据项目规模）
   • 数据流设计
   • 技术选型（必须说明理由，引用 background.md 中的对比分析）：
     • 必须详细对比至少2种方案
     • 说明权衡理由（性能 vs 易用性、功能 vs 复杂度）
     • 引用 background.md 中的对比数据（性能、生态、学习曲线、版本兼容性）
     • 明确说明选择方案的优势和不足
   • 接口定义（函数签名、参数说明，必须包含类型注解）
   • 参考 background.md 中的最佳实践，应用设计模式和架构模式
   • UV 包管理策略：使用 pyproject.toml 管理依赖，uv.lock 锁定版本
   • 技能识别：识别项目中可能的可复用技能模块，在 architecture.md 中定义技能接口
4. 设计数据库架构（新增）：
   • 参考数据库选型指南选择合适的数据库（SQLite、PostgreSQL、MongoDB、ChromaDB、Neo4j 等）
   • 设计数据模型（表结构、索引策略）
   • 设计数据访问层（Repository 模式）
   • 实现数据库抽象层（支持多数据库切换）
   • 生成数据库设计文档和数据层抽象文档
5. 生成以下文件：
   • docs/architecture.md：参考 references/architecture-template.md
     • 新增：数据库设计章节（参考 database-design-template.md）
     • 新增：数据访问层章节（参考 data-abstraction-template.md）
     • 新增：根据项目规模选择对应的架构模板
     • 新增：版本控制章节（版本策略、依赖版本锁定）
     • 新增：UV 包管理章节（pyproject.toml 配置、uv.lock 策略）
     • 新增：数据库设计章节（数据库选型、数据模型、索引策略）
     • 新增：数据访问层章节（Repository 模式、BaseRepository 接口、具体实现）
     • 新增：技能识别和管理章节（技能列表、接口定义、复用指南）
     • 明确 Python 3.11+ 版本要求
     • 增加技术选型权衡说明
   • docs/database-design.md：参考 references/database-design-template.md
     • 数据库选型与配置
     • 数据模型设计
     • 索引策略
     • 数据访问接口定义
   • docs/data-abstraction.md：参考 references/data-abstraction-template.md
     • BaseRepository 接口定义
     • SQLAlchemy / MongoDB 实现
     • Repository 工厂
     • 数据库切换策略
   • README.md：参考 references/readme-template.md，包含基础用法、依赖安装（使用 UV）、运行方式
   • todo.md：参考 references/todo-template.md，初始状态所有任务标记为 [ ]（未完成）
     • 新增：类型注解相关任务
     • 新增：UV 包管理任务
     • 新增：数据库设计与实现任务
     • 新增：技能识别与管理任务
     • 新增：根据项目规模调整任务列表

阶段3：高级程序员（Senior Dev）- 代码实现

目标：基于架构设计、任务清单和背景知识，编写高质量的可执行代码

执行步骤：

1. 阅读 docs/architecture.md、docs/database-design.md、docs/data-abstraction.md、todo.md 和 background.md，理解系统设计、项目规模、数据库设计、数据访问层架构、领域最佳实践和技能定义
2. 根据项目规模组织代码文件：
   • 小项目：所有代码在 main.py 中
   • 大项目：
     • src/__init__.py：包初始化
     • src/main.py：主入口
     • src/api/：API 模块
     • src/models/：数据模型
     • src/services/：业务逻辑
     • src/repositories/：数据访问层（Repository）
     • src/utils/：工具函数
     • tests/：测试文件
3. 编写代码：
   • 必须使用 Python 3.11+ 特性：
     • 类型注解（Type Hints）：所有函数参数和返回值必须使用类型注解
     • 使用 PEP 585（内置泛型类型）：如 list[int] 而非 List[int]
     • 使用 PEP 646（类型参数）：如 def func[T](items: list[T]) -> T:
     • 使用 match-case 语句（Python 3.10+）进行模式匹配
     • 使用数据类（dataclass）的改进特性
   • 代码结构清晰，包含必要注释
   • 应用 background.md 中的最佳实践：如错误处理、使用 loguru 进行日志记录、代码规范
   • 参考 background.md 中的常见问题，避免典型陷阱
   • 调用已有技能：在实现新功能时，优先调用 architecture.md 中定义的技能模块，避免重复开发
   • 实现数据访问层：
     • 实现 BaseRepository 接口
     • 实现 SQLAlchemyBaseRepository / MongoDBBaseRepository
     • 实现具体实体的 Repository（UserRepository 等）
     • 实现 RepositoryFactory 工厂
   • 实现所有功能点
   • 包含 if __name__ == "__main__" 入口
   • 确保代码可直接运行，无需额外配置
   • 类型注解示例：

     def process_data(data: list[dict[str, Any]]) -> dict[str, int]:
         """处理数据并返回统计结果"""
         counts: dict[str, int] = {}
         for item in data:
             key = item.get("key")
             if key:
                 counts[key] = counts.get(key, 0) + 1
         return counts
     

   • 技能调用示例：

     from src.utils.helpers import existing_skill
     
     def new_feature(data: list[Any]) -> dict[str, Any]:
         """新功能实现，调用已有技能"""
         # 直接调用技能
         result = existing_skill(data)
         return result
     

   • Repository 使用示例：

     from src.repositories import UserRepository
     
     def get_user(user_id: int) -> User | None:
         """获取用户"""
         repo = UserRepository(session)
         return repo.get_by_id(user_id)
     

4. 生成 UV 依赖文件：
   • pyproject.toml：使用标准格式，包含项目元数据和依赖
   • 新增数据库依赖：sqlalchemy、pymongo、chromadb、psycopg2-binary 等
   • 新增迁移工具：alembic（关系型数据库）、mongomock（MongoDB 测试）
   • uv.lock：自动生成，锁定依赖版本
   • 参考模板：references/uv-lock-template.md
5. 同步更新 todo.md：
   • 将已完成的任务标记为 [x]
   • 确保每个任务对应 requirements.md 中的一个条目

阶段4：质量验证 - 功能测试

目标：验证代码是否满足原始需求，生成测试报告

执行步骤：

1. 设计测试用例：
   • 覆盖 requirements.md 中的所有功能点
   • 参考 background.md 中的常见问题，设计针对性的测试场景
   • 包含正常场景和边界情况
   • 新增数据库测试：
     • 测试 CRUD 操作
     • 测试事务处理
     • 测试并发操作
     • 使用内存数据库进行测试（SQLite / mongomock）
   • 记录每个测试用例的输入和预期输出
2. 执行测试（模拟运行）：
   • 分析代码逻辑，验证功能是否正确实现
   • 检查是否符合架构设计
   • 验证 UV 依赖文件：确保 pyproject.toml 和 uv.lock 正确
   • 验证类型注解完整性：确保所有关键函数都有类型注解
   • 验证技能调用：确认新功能正确调用了已有技能
   • 验证 loguru 日志配置：确保日志正确输出
   • 验证数据访问层：确认 Repository 接口实现正确
   • 验证数据库操作：确认 CRUD 操作、查询优化正确
   • 参考 background.md 中的安全考虑，验证安全措施
3. 生成 test_report.md：
   • 参考 references/test-report-template.md
   • 列出：已验证功能、是否通过、潜在风险或未覆盖场景
   • 对每个功能给出明确的通过/不通过判断
   • 引用 background.md 中的知识，说明测试覆盖的常见问题
   • 新增：验证 Python 3.11+ 特性使用情况、UV 依赖管理情况、技能调用情况、loguru 日志配置、数据库操作验证

阶段5：功能扩展（添加功能）

目标：在现有项目基础上添加新功能，识别并复用已有技能

触发条件：用户提出"添加功能"、"扩展功能"等需求

执行步骤：

1. 读取现有项目：

   • 阅读 docs/requirements.md、docs/architecture.md、docs/database-design.md、docs/data-abstraction.md、docs/background.md
   • 读取现有代码文件（main.py 或 src/ 目录）
   • 读取 pyproject.toml 了解现有依赖

2. 分析现有架构：

   • 理解现有功能模块和数据流
   • 识别 architecture.md 中定义的可调用技能
   • 评估数据库扩展需求：是否需要新增数据表/集合、更新索引
   • 评估新功能对现有系统的影响

3. 设计功能扩展方案：

   • 明确新功能的需求和接口
   • 优先使用已有技能实现新功能
   • 设计新功能的代码适配方案
   • 设计数据库变更：新增表/集合、更新 Repository
   • 评估是否需要新增依赖

4. 适配代码：

   • 调用已有技能模块
   • 编写新功能代码
   • 更新数据访问层：新增或修改 Repository
   • 编写数据库迁移脚本（如需要）
   • 确保与现有代码风格一致
   • 添加类型注解和 loguru 日志

5. 更新文档：

   • 更新 requirements.md：添加新功能需求，更新版本号（v1.0.0 → v1.1.0）
   • 更新 architecture.md：更新架构设计、技能列表
   • 更新 docs/database-design.md：更新数据库设计
   • 更新 docs/data-abstraction.md：更新数据访问层
   • 更新 todo.md：添加新功能开发任务、数据库扩展任务
   • 更新 README.md：更新功能列表和使用说明

6. 测试验证：

   • 测试新功能
   • 回归测试现有功能
   • 测试数据库变更：验证新增表/集合、索引、迁移
   • 更新 test_report.md
   • 使用 UV 更新依赖（如需要）：uv add package

7. 生成扩展计划文档：

   • 参考 references/feature-extension-template.md
   • 记录扩展过程、代码变更、文档更新、数据库变更

阶段6：项目重构

目标：分析代码质量与性能，执行重构，提升可维护性

触发条件：用户提出"重构"、"优化"、"改进代码"等需求

执行步骤：

1. 读取现有项目：

   • 读取所有代码文件
   • 读取所有文档文件
   • 读取 pyproject.toml 和 uv.lock

2. 分析代码质量与性能：

   • 分析代码复杂度、重复代码、命名规范
   • 识别性能瓶颈
   • 识别架构问题（高耦合、低内聚）
   • 分析数据库性能：查询优化、索引优化、连接池
   • 识别可提取为技能的模块

3. 设计重构方案：

   • 确定重构目标（性能、可读性、可维护性）
   • 设计代码重构方案（提取函数/类、简化逻辑）
   • 设计性能优化方案（算法、缓存、并发）
   • 设计架构优化方案（解耦、接口优化）
   • 设计数据库优化方案：查询优化、索引优化、连接池优化
   • 识别并定义新的技能模块

4. 执行重构：

   • 执行代码重构
   • 执行性能优化
   • 执行架构优化
   • 执行数据库优化：优化查询、更新索引、调整连接池
   • 优化数据访问层：改进 Repository 实现
   • 更新 architecture.md 中的技能识别章节
   • 使用 UV 更新依赖（如需要）：uv lock --upgrade

5. 验证重构结果：

   • 回归测试
   • 性能测试
   • 数据库性能测试
   • 功能验证
   • 更新 test_report.md

6. 生成重构报告：

   • 参考 references/refactoring-plan-template.md
   • 记录重构前后的对比（代码质量、性能、架构、数据库性能）
   • 记录技能识别和管理

最终交付

新项目交付格式

按照以下格式输出所有文件内容（每个文件以 --- FILE: filename --- 开头）：

小项目（单文件）：

--- FILE: README.md ---
<README.md 完整内容>

--- FILE: pyproject.toml ---
<pyproject.toml 完整内容>

--- FILE: uv.lock ---
<uv.lock 完整内容>

--- FILE: main.py ---
<main.py 完整内容>

--- FILE: docs/background.md ---
<docs/background.md 完整内容>

--- FILE: docs/requirements.md ---
<docs/requirements.md 完整内容>

--- FILE: docs/architecture.md ---
<docs/architecture.md 完整内容>

--- FILE: docs/database-design.md ---
<docs/database-design.md 完整内容>

--- FILE: docs/data-abstraction.md ---
<docs/data-abstraction.md 完整内容>

--- FILE: test_report.md ---
<test_report.md 完整内容>

大项目（文件夹组织）：

--- FILE: README.md ---
<README.md 完整内容>

--- FILE: pyproject.toml ---
<pyproject.toml 完整内容>

--- FILE: uv.lock ---
<uv.lock 完整内容>

--- FILE: src/__init__.py ---
<src/__init__.py 完整内容>

--- FILE: src/main.py ---
<src/main.py 完整内容>

--- FILE: src/repositories/__init__.py ---
<src/repositories/__init__.py 完整内容>

--- FILE: src/repositories/base.py ---
<BaseRepository 接口>

--- FILE: src/repositories/user_repo.py ---
<UserRepository 实现>

--- FILE: tests/__init__.py ---
<tests/__init__.py 完整内容>

--- FILE: tests/test_repositories.py ---
<Repository 测试>

--- FILE: docs/background.md ---
<docs/background.md 完整内容>

--- FILE: docs/requirements.md ---
<docs/requirements.md 完整内容>

--- FILE: docs/architecture.md ---
<docs/architecture.md 完整内容>

--- FILE: docs/database-design.md ---
<docs/database-design.md 完整内容>

--- FILE: docs/data-abstraction.md ---
<docs/data-abstraction.md 完整内容>

--- FILE: test_report.md ---
<test_report.md 完整内容>

功能扩展交付格式

--- FILE: docs/requirements.md ---
<更新后的 requirements.md>

--- FILE: docs/architecture.md ---
<更新后的 architecture.md>

--- FILE: docs/database-design.md ---
<更新后的 database-design.md>

--- FILE: docs/data-abstraction.md ---
<更新后的 data-abstraction.md>

--- FILE: main.py 或 src/... ---
<修改后的代码文件>

--- FILE: pyproject.toml ---
<更新后的 pyproject.toml（如有）>

--- FILE: README.md ---
<更新后的 README.md>

--- FILE: feature_extension_plan.md ---
<功能扩展计划文档>

重构交付格式

--- FILE: main.py 或 src/... ---
<重构后的代码文件>

--- FILE: docs/architecture.md ---
<更新后的 architecture.md（包含技能识别）>

--- FILE: docs/database-design.md ---
<更新后的 database-design.md>

--- FILE: docs/data-abstraction.md ---
<更新后的 data-abstraction.md>

--- FILE: refactoring_report.md ---
<重构报告>

--- FILE: test_report.md ---
<更新后的测试报告>

资源索引

• 背景知识模板：见 references/background-template.md
• 需求文档模板：见 references/requirements-template.md
• 架构文档模板：见 references/architecture-template.md
• UV 锁定文件模板：见 references/uv-lock-template.md
• 任务清单模板：见 references/todo-template.md
• 测试报告模板：见 references/test-report-template.md
• 项目说明模板：见 references/readme-template.md
• 功能扩展模板：见 references/feature-extension-template.md
• 重构计划模板：见 references/refactoring-plan-template.md
• 数据库选型指南：见 references/database-selection-guide.md
• 数据库设计模板：见 references/database-design-template.md
• 数据层抽象模板：见 references/data-abstraction-template.md

注意事项

核心要求（强制）

• UV 包管理：必须使用 UV 作为包管理工具，使用 pyproject.toml 管理依赖，uv.lock 锁定版本
• loguru 日志：必须使用 loguru 进行日志记录
• Python 3.11+ 特性：必须使用类型注解、PEP 585 内置泛型类型
• 项目规模自适应：PM 阶段评估规模，架构师阶段选择组织方式
• 版本控制机制：使用语义化版本（vX.Y.Z），记录版本历史
• 技能识别与管理：在架构阶段识别技能，在实现阶段复用技能
• 数据库设计与实现：根据需求选择合适的数据库（SQLite、PostgreSQL、MongoDB、向量数据库、图数据库）
• 数据层抽象：必须实现 Repository 模式，提供统一的 CRUD 接口
• 数据库切换能力：支持通过配置切换不同数据库实现

流程要求

• 自主学习阶段：必须执行网络搜索，不得跳过
• 需求澄清限制：PM 阶段最多进行2轮交互，超过则基于已有信息推进
• 无过度设计：严格按照用户需求实现，不得添加未提及的功能
• 背景知识应用：各阶段必须参考和应用 background.md 中的知识
• 代码质量：确保生成代码可直接运行，包含完整的错误处理

技术选型（强制）

• 必须详细对比至少2种方案
• 必须说明权衡理由（性能 vs 易用性、功能 vs 复杂度）
• 必须引用 background.md 中的对比数据
• 必须说明选择方案的优势和不足

数据库要求（强制）

• 数据库选型：根据项目需求选择合适的数据库，参考 database-selection-guide.md
• 数据模型设计：设计合理的数据表/集合结构，定义索引策略
• 数据访问层：实现 Repository 模式，提供统一的 CRUD 接口
• 类型安全：所有数据访问函数必须包含类型注解
• 性能优化：合理的索引策略、连接池配置、查询优化

状态同步

• todo.md 必须与 requirements.md 的功能点一一对应
• 测试报告必须覆盖所有功能点，并明确标注通过状态

功能扩展

• 优先调用已有技能，避免重复开发
• 确保新功能与现有代码风格一致
• 更新所有相关文档（包括数据库设计文档）
• 执行回归测试
• 数据库扩展：评估是否需要新增表/集合、更新 Repository、编写迁移脚本

重构

• 先分析后执行，避免盲目重构
• 保持功能不变，仅优化内部实现
• 数据库优化：优化查询、索引、连接池
• 记录重构前后的对比数据
• 识别并提取技能模块

使用示例

示例1：带数据库的用户管理系统（大项目）

• 用户需求："实现一个用户管理系统，支持用户注册、登录、信息查询"
• 阶段0：搜索"数据库选型"、"SQLAlchemy vs MongoDB"、"用户认证最佳实践"、"密码加密"、"Python 3.11+ 类型注解"、"UV 包管理"、"Repository 模式"
• PM 阶段：
  • 澄清数据规模、并发需求、认证方式、密码存储
  • 明确数据库需求：关系型数据（用户信息），预期 10万用户
  • 评估项目规模：5 个功能点 → 中型项目 → 选择 PostgreSQL（支持高并发）
• Architect 阶段：
  • 数据库选型：PostgreSQL（关系型，支持高并发）
  • 设计数据模型：User 表（id, username, email, password_hash, created_at）
  • 设计数据访问层：BaseRepository 接口、SQLAlchemyBaseRepository、UserRepository
  • 设计 RepositoryFactory：支持 PostgreSQL / SQLite 切换
  • 索引策略：username（UNIQUE）、email（UNIQUE）、created_at（INDEX）
  • 选择大项目架构：src/repositories/ 数据访问层
  • 识别技能模块：密码加密、Token 生成
• Senior Dev 阶段：
  • 实现 BaseRepository 接口（CRUD 操作）
  • 实现 SQLAlchemyBaseRepository
  • 实现 UserRepository（get_by_email, get_by_username）
  • 实现 RepositoryFactory
  • 使用 Python 3.11+ 特性、类型注解
  • 使用 loguru 记录日志
  • 生成 pyproject.toml（sqlalchemy、psycopg2-binary、alembic）
• 验证阶段：测试 CRUD 操作、并发操作、数据库性能、类型注解、数据访问层抽象

示例2：文档管理系统（MongoDB）

• 用户需求："实现一个文档管理系统，支持文档的增删改查和全文搜索"
• PM 阶段：
  • 澄清文档格式、存储方式、搜索需求
  • 明确数据库需求：文档型数据，需要灵活 schema 和全文搜索
  • 评估项目规模：4 个功能点 → 小项目 → 选择 MongoDB（文档型，灵活 schema）
• Architect 阶段：
  • 数据库选型：MongoDB（文档型，支持全文搜索）
  • 设计数据模型：Document 集合（title, content, tags, metadata, created_at）
  • 设计数据访问层：MongoDBBaseRepository、DocumentRepository
  • 索引策略：title（TEXT）、content（TEXT）、tags（MULTIKEY）
• Senior Dev 阶段：
  • 实现 MongoDBBaseRepository
  • 实现 DocumentRepository（search_by_keyword）
  • 使用 pymongo、类型注解
• 验证阶段：测试 CRUD 操作、全文搜索、性能

示例3：向量搜索系统（ChromaDB）

• 用户需求："实现一个向量搜索系统，支持文档的语义搜索"
• PM 阶段：
  • 澄清向量维度、相似度度量、数据规模
  • 明确数据库需求：向量搜索，预期 100万向量
  • 评估项目规模：3 个功能点 → 小项目 → 选择 ChromaDB（向量数据库，轻量级）
• Architect 阶段：
  • 数据库选型：ChromaDB（向量数据库，专为 LLM 设计）
  • 设计数据模型：ChromaDB 集合（documents, embeddings, metadata）
  • 设计数据访问层：VectorRepository
• Senior Dev 阶段：
  • 实现 VectorRepository（add_document, search）
  • 使用 chromadb、类型注解
• 验证阶段：测试向量添加、相似性搜索、性能

技能调用机制

识别时机

• 架构阶段（阶段2）：识别可能的可复用技能模块，在 architecture.md 中定义
• 实现阶段（阶段3）：实现新功能时，优先调用已定义的技能
• 扩展阶段（阶段5）：添加功能时，复用已有技能
• 重构阶段（阶段6）：重构时，提取新的技能模块

技能接口规范

所有技能必须包含：

1. 完整的类型注解：函数参数和返回值必须使用类型注解
2. 清晰的文档字符串：说明功能、参数、返回值、使用场景
3. 示例代码：在 architecture.md 中提供调用示例
4. 依赖声明：明确依赖的其他技能或库

复用原则

1. 优先复用：实现新功能时，优先调用已有技能
2. 接口稳定：技能接口应保持稳定，避免频繁修改
3. 单一职责：技能应具有单一职责，功能清晰
4. 可测试性：技能应易于单独测试

数据访问技能

以下数据访问层模块可作为技能复用：

• BaseRepository 接口：通用的 CRUD 接口
• SQLAlchemyBaseRepository：关系型数据库的通用实现
• MongoDBBaseRepository：MongoDB 的通用实现
• RepositoryFactory：数据库切换工厂