python-team

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python 团队协同开发 Skill

Python Collaborative Development Skill

任务目标

Task Objectives

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

This Skill is used to: convert users' natural language requirements into complete Python project deliverables through the collaboration of a virtual four-role team (Autonomous Learning → PM → Architect → Senior Programmer)
Capabilities include: autonomous learning and knowledge integration, requirement analysis and clarification, architecture design (adaptive to project size), code implementation, function verification, version control, feature expansion, project refactoring, skill recognition and invocation, database design and implementation, data layer abstraction
Trigger conditions: Users put forward clear software development requirements (such as "create a weather query tool", "implement a to-do list system", "add data export function", "optimize code performance", "design a user management system", etc.)

前置准备

Preparations

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

Dependency description: web_search tool (integrated)
Package management tool: UV (modern Python package manager, fast, reliable, dependency locking)
- Installation:
```
pip install uv
```
- Project initialization:
```
uv init
```
- Dependency management:
```
uv add package
```
File preparation: No pre-files required
Version control mechanism: All documents and code must include version information, use Semantic Versioning (e.g., v1.0.0), and record version history and change reasons

操作步骤

Operation Steps

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

Phase 0: Autonomous Learning and Knowledge Integration

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

执行步骤：

识别关键词：从用户需求中提取核心技术、领域、工具关键词
- 技术关键词：如"REST API"、"WebSocket"、"CSV处理"、"数据库"、"ORM"
- 领域关键词：如"天气查询"、"待办事项"、"数据分析"、"用户管理"
- 工具关键词：如"Flask"、"pandas"、"UV"、"SQLAlchemy"、"MongoDB"
执行网络搜索（3-6轮）：
- 第1轮：搜索"<领域> 最佳实践"，获取通用设计原则
- 第2轮：搜索"<技术> 框架对比"，如"Flask vs FastAPI 对比"
- 第3轮：搜索"<功能> 实现方案"，如"Python 天气API调用示例"
- 第4轮（可选）：搜索"<问题> 常见坑"，如"REST API 常见错误"
- 第5轮：搜索"Python 3.11+ 新特性"、"框架版本兼容性"、"UV 包管理器最佳实践"、"loguru 日志库最佳实践"
- 第6轮（新增）：搜索"数据库选型"、"SQLAlchemy vs MongoDB"、"向量数据库对比"、"图数据库对比"、"Repository 模式最佳实践"、"数据库性能优化"
筛选与整合信息：
- 评估搜索结果的可信度和时效性
- 提取关键信息：技术选型依据、设计模式、最佳实践、常见问题、版本特性、UV 使用、数据库选型
- 整合冲突信息，标注不同方案的优缺点
- 重点关注：版本兼容性、长期维护性、学习资源、UV 包管理优势、数据库特性
- 生成结构化的知识总结
生成
docs/background.md
：
- 参考 references/background-template.md 的结构
- 包含：项目背景概述、技术领域知识、最佳实践、工具对比（含版本信息）、常见问题、UV 包管理、数据库相关知识
- 增强：工具对比维度增加版本兼容性、长期维护性、学习资源
- 增强：数据库选型指南（SQLite、PostgreSQL、MongoDB、向量数据库、图数据库）
- 增强：数据库设计与实现最佳实践（ORM/ODM、索引策略、性能优化）
- 确保信息准确、实用、易于理解

Objective: Obtain relevant domain knowledge through web search, generate project background documents, and provide knowledge support for subsequent phases

Execution Steps:

Identify keywords: Extract core technology, domain, and tool keywords from user requirements
- Technical keywords: such as "REST API", "WebSocket", "CSV processing", "database", "ORM"
- Domain keywords: such as "weather query", "to-do list", "data analysis", "user management"
- Tool keywords: such as "Flask", "pandas", "UV", "SQLAlchemy", "MongoDB"
Execute web search (3-6 rounds):
- Round 1: Search "<domain> best practices" to obtain general design principles
- Round 2: Search "<technology> framework comparison", such as "Flask vs FastAPI comparison"
- Round 3: Search "<function> implementation scheme", such as "Python weather API call example"
- Round 4 (optional): Search "<problem> common pitfalls", such as "REST API common errors"
- Round 5: Search "Python 3.11+ new features", "framework version compatibility", "UV package manager best practices", "loguru logging library best practices"
- Round 6 (new): Search "database selection", "SQLAlchemy vs MongoDB", "vector database comparison", "graph database comparison", "Repository pattern best practices", "database performance optimization"
Filter and integrate information:
- Evaluate the credibility and timeliness of search results
- Extract key information: technical selection basis, design patterns, best practices, common issues, version features, UV usage, database selection
- Integrate conflicting information, mark the advantages and disadvantages of different solutions
- Key focus: Version compatibility, long-term maintainability, learning resources, UV package management advantages, database features
- Generate structured knowledge summary
Generate
docs/background.md
:
- Refer to the structure of references/background-template.md
- Include: Project background overview, technical domain knowledge, best practices, tool comparison (including version information), common issues, UV package management, database-related knowledge
- Enhancement: Add version compatibility, long-term maintainability, and learning resources to tool comparison dimensions
- Enhancement: Database selection guide (SQLite, PostgreSQL, MongoDB, vector databases, graph databases)
- Enhancement: Best practices for database design and implementation (ORM/ODM, indexing strategies, performance optimization)
- Ensure information is accurate, practical, and easy to understand

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

Phase 1: Project Manager (PM) - Requirement Analysis and Documentation

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

执行步骤：

结合背景知识分析需求：
- 阅读
```
docs/background.md
```
  ，了解领域最佳实践和常见陷阱
- 识别用户需求中可能遗漏的关键点（基于领域知识）
- 评估需求的合理性和可行性
识别需求中的模糊点或不完整之处
最多进行2轮澄清交互（如果需求不明确）：
- 以"【提问】"开头向用户确认细节
- 典型问题：功能边界、输入输出格式、非功能要求、技术栈偏好、版本要求、项目规模预期等
- 示例："做一个天气查询工具" → 澄清"支持哪些城市？数据来源？是否缓存？"
评估项目规模：
- 小项目：< 5 个功能点，< 500 行代码预期
- 中型项目：5-10 个功能点，500-2000 行代码预期
- 大项目：> 10 个功能点，> 2000 行代码预期
- 在
```
requirements.md
```
  中明确标注项目规模
数据库需求澄清（新增）：
- 确认是否需要数据持久化存储
- 确认数据类型（关系型、文档型、向量、图）
- 确认数据规模和并发需求
- 确认是否需要多数据库支持
- 确认是否需要数据库切换能力
基于用户反馈、背景知识和项目规模评估，生成
```
docs/requirements.md
```
：
- 参考 references/requirements-template.md 的结构
- 包含：功能列表、输入输出说明、非功能性要求、假设与约束、版本要求、项目规模、数据库需求
- 关键：参考 background.md 中的最佳实践，完善非功能性要求
- 新增：明确 Python 3.11+ 版本要求、版本控制策略、UV 包管理要求、项目规模、loguru 日志库要求（强制使用）、数据库选型要求（参考 database-selection-guide.md）
- 确保每个功能点都清晰可执行
- 记录版本：v1.0.0（初始版本）

Objective: Combine background knowledge to understand user requirements, generate clear requirement documents, and evaluate project scale

Execution Steps:

Analyze requirements combined with background knowledge:
- Read
```
docs/background.md
```
  to understand domain best practices and common pitfalls
- Identify possible missing key points in user requirements (based on domain knowledge)
- Evaluate the rationality and feasibility of requirements
Identify ambiguous or incomplete parts in requirements
Conduct up to 2 rounds of clarification interactions (if requirements are unclear):
- Start with "[Question]" to confirm details with users
- Typical questions: Function boundaries, input/output formats, non-functional requirements, tech stack preferences, version requirements, expected project scale, etc.
- Example: "Create a weather query tool" → Clarify "Which cities are supported? Data source? Is caching enabled?"
Evaluate project scale:
- Small project: < 5 functional points, expected < 500 lines of code
- Medium project: 5-10 functional points, expected 500-2000 lines of code
- Large project: > 10 functional points, expected > 2000 lines of code
- Clearly mark the project scale in
```
requirements.md
```
Database requirement clarification (new):
- Confirm whether persistent data storage is needed
- Confirm data type (relational, document, vector, graph)
- Confirm data scale and concurrency requirements
- Confirm whether multi-database support is needed
- Confirm whether database switching capability is needed
Based on user feedback, background knowledge, and project scale evaluation, generate
```
docs/requirements.md
```
:
- Refer to the structure of references/requirements-template.md
- Include: Function list, input/output description, non-functional requirements, assumptions and constraints, version requirements, project scale, database requirements
- Key: Refer to best practices in background.md to improve non-functional requirements
- New: Clearly specify Python 3.11+ version requirements, version control strategy, UV package management requirements, project scale, loguru logging library requirements (mandatory use), database selection requirements (refer to database-selection-guide.md)
- Ensure each functional point is clearly executable
- Record version: v1.0.0 (initial version)

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

Phase 2: System Architect - Architecture Design

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

执行步骤：

阅读
```
docs/requirements.md
```
和
```
background.md
```
，理解完整需求、领域知识、项目规模和数据库需求

根据项目规模选择架构组织方式：

小项目：使用单文件或简单文件夹结构

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

设计系统架构：
- 参考 background.md 中的工具对比，进行技术选型
- 模块划分与职责分配（根据项目规模）
- 数据流设计
- 技术选型（必须说明理由，引用 background.md 中的对比分析）：
  - 必须详细对比至少2种方案
  - 说明权衡理由（性能 vs 易用性、功能 vs 复杂度）
  - 引用 background.md 中的对比数据（性能、生态、学习曲线、版本兼容性）
  - 明确说明选择方案的优势和不足
- 接口定义（函数签名、参数说明，必须包含类型注解）
- 参考 background.md 中的最佳实践，应用设计模式和架构模式
- UV 包管理策略：使用 pyproject.toml 管理依赖，uv.lock 锁定版本
- 技能识别：识别项目中可能的可复用技能模块，在 architecture.md 中定义技能接口
设计数据库架构（新增）：
- 参考数据库选型指南选择合适的数据库（SQLite、PostgreSQL、MongoDB、ChromaDB、Neo4j 等）
- 设计数据模型（表结构、索引策略）
- 设计数据访问层（Repository 模式）
- 实现数据库抽象层（支持多数据库切换）
- 生成数据库设计文档和数据层抽象文档
生成以下文件：
- ```
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 包管理任务
  - 新增：数据库设计与实现任务
  - 新增：技能识别与管理任务
  - 新增：根据项目规模调整任务列表

Objective: Based on requirement documents, background knowledge, and project scale, design system architecture, generate design documents and task lists

Execution Steps:

Read
```
docs/requirements.md
```
and
```
background.md
```
to understand complete requirements, domain knowledge, project scale, and database requirements

Select architecture organization method based on project scale:

Small project: Use single file or simple folder structure

project/
├── main.py
├── README.md           # Project root directory
├── pyproject.toml
├── uv.lock
└── docs/               # Document folder
    ├── background.md
    ├── requirements.md
    └── architecture.md

Large project: Use standard Python project folder organization

project/
├── README.md           # Project root directory
├── pyproject.toml
├── uv.lock
├── src/
│   ├── __init__.py
│   ├── main.py
│   ├── api/              # API module
│   ├── models/           # Data models
│   ├── services/         # Business logic
│   ├── repositories/     # Data access layer (Repository)
│   └── utils/            # Utility functions
├── tests/
│   └── test_main.py
└── docs/                  # Document folder
    ├── background.md
    ├── requirements.md
    └── architecture.md

Design system architecture:
- Refer to tool comparison in background.md for technical selection
- Module division and responsibility allocation (based on project scale)
- Data flow design
- Technical selection (must explain reasons, reference comparison analysis in background.md):
  - Must compare at least 2 solutions in detail
  - Explain trade-off reasons (performance vs ease of use, functionality vs complexity)
  - Reference comparison data in background.md (performance, ecosystem, learning curve, version compatibility)
  - Clearly explain the advantages and disadvantages of the selected solution
- Interface definition (function signatures, parameter descriptions, must include type annotations)
- Refer to best practices in background.md to apply design patterns and architecture patterns
- UV package management strategy: Use pyproject.toml to manage dependencies, uv.lock to lock versions
- Skill recognition: Identify possible reusable skill modules in the project, define skill interfaces in architecture.md
Design database architecture (new):
- Select appropriate database (SQLite, PostgreSQL, MongoDB, ChromaDB, Neo4j, etc.) referring to database selection guide
- Design data models (table structure, indexing strategies)
- Design data access layer (Repository pattern)
- Implement database abstraction layer (supports multi-database switching)
- Generate database design documents and data layer abstraction documents
Generate the following files:
- ```
docs/architecture.md
```
  : Refer to references/architecture-template.md
  - New: Database design chapter (refer to database-design-template.md)
  - New: Data access layer chapter (refer to data-abstraction-template.md)
  - New: Select corresponding architecture template based on project scale
  - New: Version control chapter (version strategy, dependency version locking)
  - New: UV package management chapter (pyproject.toml configuration, uv.lock strategy)
  - New: Database design chapter (database selection, data models, indexing strategies)
  - New: Data access layer chapter (Repository pattern, BaseRepository interface, specific implementation)
  - New: Skill recognition and management chapter (skill list, interface definition, reuse guide)
  - Clearly specify Python 3.11+ version requirements
  - Add technical selection trade-off explanations
- ```
docs/database-design.md
```
  : Refer to references/database-design-template.md
  - Database selection and configuration
  - Data model design
  - Indexing strategies
  - Data access interface definition
- ```
docs/data-abstraction.md
```
  : Refer to references/data-abstraction-template.md
  - BaseRepository interface definition
  - SQLAlchemy / MongoDB implementation
  - Repository factory
  - Database switching strategy
- ```
README.md
```
  : Refer to references/readme-template.md, including basic usage, dependency installation (using UV), and running methods
- ```
todo.md
```
  : Refer to references/todo-template.md, mark all tasks as
```
[ ]
```
  (uncompleted) in initial state
  - New: Tasks related to type annotations
  - New: UV package management tasks
  - New: Database design and implementation tasks
  - New: Skill recognition and management tasks
  - New: Adjust task list based on project scale

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

Phase 3: Senior Programmer - Code Implementation

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

执行步骤：

阅读
```
docs/architecture.md
```
、
```
docs/database-design.md
```
、
```
docs/data-abstraction.md
```
、
```
todo.md
```
和
```
background.md
```
，理解系统设计、项目规模、数据库设计、数据访问层架构、领域最佳实践和技能定义
根据项目规模组织代码文件：
- 小项目：所有代码在
```
main.py
```
  中
- 大项目：
  - ```
  src/__init__.py
```
  ：包初始化
- ```
src/main.py
```
    ：主入口
  - ```
  src/api/
```
  ：API 模块
- ```
src/models/
```
    ：数据模型
  - ```
  src/services/
```
  ：业务逻辑
- ```
src/repositories/
```
    ：数据访问层（Repository）
  - ```
  src/utils/
```
  ：工具函数
- ```
tests/
```
    ：测试文件
编写代码：
- 必须使用 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__"
```
  入口
- 确保代码可直接运行，无需额外配置
- 类型注解示例：
  python
```
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
```
- 技能调用示例：
  python
```
from src.utils.helpers import existing_skill

def new_feature(data: list[Any]) -> dict[str, Any]:
    """新功能实现，调用已有技能"""
    # 直接调用技能
    result = existing_skill(data)
    return result
```
- Repository 使用示例：
  python
```
from src.repositories import UserRepository

def get_user(user_id: int) -> User | None:
    """获取用户"""
    repo = UserRepository(session)
    return repo.get_by_id(user_id)
```
生成 UV 依赖文件：
- ```
pyproject.toml
```
  ：使用标准格式，包含项目元数据和依赖
- 新增数据库依赖：sqlalchemy、pymongo、chromadb、psycopg2-binary 等
- 新增迁移工具：alembic（关系型数据库）、mongomock（MongoDB 测试）
- ```
uv.lock
```
  ：自动生成，锁定依赖版本
- 参考模板：references/uv-lock-template.md
同步更新
```
todo.md
```
：
- 将已完成的任务标记为
```
[x]
```
- 确保每个任务对应
```
requirements.md
```
  中的一个条目

Objective: Based on architecture design, task list, and background knowledge, write high-quality executable code

Execution Steps:

Read
```
docs/architecture.md
```
,
```
docs/database-design.md
```
,
```
docs/data-abstraction.md
```
,
```
todo.md
```
and
```
background.md
```
to understand system design, project scale, database design, data access layer architecture, domain best practices, and skill definitions
Organize code files based on project scale:
- Small project: All code in
```
main.py
```
- Large project:
  - ```
  src/__init__.py
```
  : Package initialization
- ```
src/main.py
```
    : Main entry
  - ```
  src/api/
```
  : API module
- ```
src/models/
```
    : Data models
  - ```
  src/services/
```
  : Business logic
- ```
src/repositories/
```
    : Data access layer (Repository)
  - ```
  src/utils/
```
  : Utility functions
- ```
tests/
```
    : Test files
Write code:
- Must use Python 3.11+ features:
  - Type Hints: All function parameters and return values must use type annotations
  - Use PEP 585 (built-in generic types): such as
```
list[int]
```
    instead of
```
List[int]
```
  - Use PEP 646 (type parameters): such as
```
def func[T](items: list[T]) -> T:
```
  - Use match-case statements (Python 3.10+) for pattern matching
  - Use improved features of dataclass
- Clear code structure with necessary comments
- Apply best practices in background.md: such as error handling, use loguru for logging, code specifications
- Refer to common issues in background.md to avoid typical pitfalls
- Call existing skills: When implementing new functions, prioritize calling skill modules defined in architecture.md to avoid repeated development
- Implement data access layer:
  - Implement BaseRepository interface
  - Implement SQLAlchemyBaseRepository / MongoDBBaseRepository
  - Implement Repository for specific entities (UserRepository, etc.)
  - Implement RepositoryFactory
- Implement all functional points
- Include
```
if __name__ == "__main__"
```
  entry
- Ensure code can be run directly without additional configuration
- Type annotation example:
  python
```
def process_data(data: list[dict[str, Any]]) -> dict[str, int]:
    """Process data and return statistical results"""
    counts: dict[str, int] = {}
    for item in data:
        key = item.get("key")
        if key:
            counts[key] = counts.get(key, 0) + 1
    return counts
```
- Skill invocation example:
  python
```
from src.utils.helpers import existing_skill

def new_feature(data: list[Any]) -> dict[str, Any]:
    """New feature implementation, call existing skill"""
    # Directly call skill
    result = existing_skill(data)
    return result
```
- Repository usage example:
  python
```
from src.repositories import UserRepository

def get_user(user_id: int) -> User | None:
    """Get user"""
    repo = UserRepository(session)
    return repo.get_by_id(user_id)
```
Generate UV dependency files:
- ```
pyproject.toml
```
  : Use standard format, include project metadata and dependencies
- New database dependencies: sqlalchemy, pymongo, chromadb, psycopg2-binary, etc.
- New migration tools: alembic (relational databases), mongomock (MongoDB testing)
- ```
uv.lock
```
  : Automatically generated, locks dependency versions
- Refer to template: references/uv-lock-template.md
Synchronously update
```
todo.md
```
:
- Mark completed tasks as
```
[x]
```
- Ensure each task corresponds to an entry in
```
requirements.md
```

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

Phase 4: Quality Verification - Functional Testing

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

执行步骤：

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

Objective: Verify whether the code meets the original requirements, generate test reports

Execution Steps:

Design test cases:
- Cover all functional points in
```
requirements.md
```
- Refer to common issues in background.md to design targeted test scenarios
- Include normal scenarios and boundary cases
- New database tests:
  - Test CRUD operations
  - Test transaction processing
  - Test concurrent operations
  - Use in-memory databases for testing (SQLite / mongomock)
- Record input and expected output for each test case
Execute tests (simulated operation):
- Analyze code logic to verify whether functions are correctly implemented
- Check compliance with architecture design
- Verify UV dependency files: Ensure pyproject.toml and uv.lock are correct
- Verify type annotation completeness: Ensure all key functions have type annotations
- Verify skill invocation: Confirm new functions correctly call existing skills
- Verify loguru logging configuration: Ensure logs are output correctly
- Verify data access layer: Confirm Repository interface implementation is correct
- Verify database operations: Confirm CRUD operations, query optimization are correct
- Refer to security considerations in background.md to verify security measures
Generate
```
test_report.md
```
:
- Refer to references/test-report-template.md
- List: Verified functions, pass status, potential risks or uncovered scenarios
- Give clear pass/fail judgment for each function
- Reference knowledge in background.md to explain common issues covered by tests
- New: Verify Python 3.11+ feature usage, UV dependency management, skill invocation, loguru logging configuration, database operation verification

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

Phase 5: Feature Extension (Add Functions)

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

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

执行步骤：

读取现有项目：

阅读

docs/requirements.md

、

docs/architecture.md

、

docs/database-design.md

、

docs/data-abstraction.md

、

docs/background.md

读取现有代码文件（main.py 或 src/ 目录）
读取
```
pyproject.toml
```
了解现有依赖

分析现有架构：
- 理解现有功能模块和数据流
- 识别 architecture.md 中定义的可调用技能
- 评估数据库扩展需求：是否需要新增数据表/集合、更新索引
- 评估新功能对现有系统的影响
设计功能扩展方案：
- 明确新功能的需求和接口
- 优先使用已有技能实现新功能
- 设计新功能的代码适配方案
- 设计数据库变更：新增表/集合、更新 Repository
- 评估是否需要新增依赖
适配代码：
- 调用已有技能模块
- 编写新功能代码
- 更新数据访问层：新增或修改 Repository
- 编写数据库迁移脚本（如需要）
- 确保与现有代码风格一致
- 添加类型注解和 loguru 日志
更新文档：
- 更新
```
requirements.md
```
  ：添加新功能需求，更新版本号（v1.0.0 → v1.1.0）
- 更新
```
architecture.md
```
  ：更新架构设计、技能列表
- 更新
```
docs/database-design.md
```
  ：更新数据库设计
- 更新
```
docs/data-abstraction.md
```
  ：更新数据访问层
- 更新
```
todo.md
```
  ：添加新功能开发任务、数据库扩展任务
- 更新
```
README.md
```
  ：更新功能列表和使用说明
测试验证：
- 测试新功能
- 回归测试现有功能
- 测试数据库变更：验证新增表/集合、索引、迁移
- 更新
```
test_report.md
```
- 使用 UV 更新依赖（如需要）：
```
uv add package
```
生成扩展计划文档：
- 参考 references/feature-extension-template.md
- 记录扩展过程、代码变更、文档更新、数据库变更

Objective: Add new functions based on existing projects, identify and reuse existing skills

Trigger Conditions: Users put forward requirements such as "add function", "expand function", etc.

Execution Steps:

Read existing project:
- Read
```
docs/requirements.md
```
  ,
```
docs/architecture.md
```
  ,
```
docs/database-design.md
```
  ,
```
docs/data-abstraction.md
```
  ,
```
docs/background.md
```
- Read existing code files (main.py or src/ directory)
- Read
```
pyproject.toml
```
  to understand existing dependencies
Analyze existing architecture:
- Understand existing functional modules and data flow
- Identify callable skills defined in architecture.md
- Evaluate database extension requirements: Whether new tables/collections are needed, index updates
- Evaluate the impact of new functions on existing systems
Design feature extension plan:
- Clarify requirements and interfaces of new functions
- Prioritize using existing skills to implement new functions
- Design code adaptation scheme for new functions
- Design database changes: Add tables/collections, update Repository
- Evaluate whether new dependencies are needed
Adapt code:
- Call existing skill modules
- Write new function code
- Update data access layer: Add or modify Repository
- Write database migration scripts (if needed)
- Ensure consistency with existing code style
- Add type annotations and loguru logging
Update documents:
- Update
```
requirements.md
```
  : Add new function requirements, update version number (v1.0.0 → v1.1.0)
- Update
```
architecture.md
```
  : Update architecture design, skill list
- Update
```
docs/database-design.md
```
  : Update database design
- Update
```
docs/data-abstraction.md
```
  : Update data access layer
- Update
```
todo.md
```
  : Add new function development tasks, database extension tasks
- Update
```
README.md
```
  : Update function list and usage instructions
Test verification:
- Test new functions
- Regression test existing functions
- Test database changes: Verify new tables/collections, indexes, migrations
- Update
```
test_report.md
```
- Use UV to update dependencies (if needed):
```
uv add package
```
Generate extension plan document:
- Refer to references/feature-extension-template.md
- Record extension process, code changes, document updates, database changes

阶段6：项目重构

Phase 6: Project Refactoring

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

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

执行步骤：

读取现有项目：
- 读取所有代码文件
- 读取所有文档文件
- 读取
```
pyproject.toml
```
  和
```
uv.lock
```
分析代码质量与性能：
- 分析代码复杂度、重复代码、命名规范
- 识别性能瓶颈
- 识别架构问题（高耦合、低内聚）
- 分析数据库性能：查询优化、索引优化、连接池
- 识别可提取为技能的模块
设计重构方案：
- 确定重构目标（性能、可读性、可维护性）
- 设计代码重构方案（提取函数/类、简化逻辑）
- 设计性能优化方案（算法、缓存、并发）
- 设计架构优化方案（解耦、接口优化）
- 设计数据库优化方案：查询优化、索引优化、连接池优化
- 识别并定义新的技能模块
执行重构：
- 执行代码重构
- 执行性能优化
- 执行架构优化
- 执行数据库优化：优化查询、更新索引、调整连接池
- 优化数据访问层：改进 Repository 实现
- 更新 architecture.md 中的技能识别章节
- 使用 UV 更新依赖（如需要）：
```
uv lock --upgrade
```
验证重构结果：
- 回归测试
- 性能测试
- 数据库性能测试
- 功能验证
- 更新
```
test_report.md
```
生成重构报告：
- 参考 references/refactoring-plan-template.md
- 记录重构前后的对比（代码质量、性能、架构、数据库性能）
- 记录技能识别和管理

Objective: Analyze code quality and performance, execute refactoring, improve maintainability

Trigger Conditions: Users put forward requirements such as "refactor", "optimize", "improve code", etc.

Execution Steps:

Read existing project:
- Read all code files
- Read all document files
- Read
```
pyproject.toml
```
  and
```
uv.lock
```
Analyze code quality and performance:
- Analyze code complexity, duplicate code, naming conventions
- Identify performance bottlenecks
- Identify architecture issues (high coupling, low cohesion)
- Analyze database performance: Query optimization, index optimization, connection pooling
- Identify modules that can be extracted as skills
Design refactoring plan:
- Determine refactoring goals (performance, readability, maintainability)
- Design code refactoring scheme (extract functions/classes, simplify logic)
- Design performance optimization scheme (algorithm, caching, concurrency)
- Design architecture optimization scheme (decoupling, interface optimization)
- Design database optimization scheme: Query optimization, index optimization, connection pool optimization
- Identify and define new skill modules
Execute refactoring:
- Execute code refactoring
- Execute performance optimization
- Execute architecture optimization
- Execute database optimization: Optimize queries, update indexes, adjust connection pools
- Optimize data access layer: Improve Repository implementation
- Update skill recognition chapter in architecture.md
- Use UV to update dependencies (if needed):
```
uv lock --upgrade
```
Verify refactoring results:
- Regression testing
- Performance testing
- Database performance testing
- Function verification
- Update
```
test_report.md
```
Generate refactoring report:
- Refer to references/refactoring-plan-template.md
- Record comparison before and after refactoring (code quality, performance, architecture, database performance)
- Record skill recognition and management

最终交付

Final Delivery

新项目交付格式

New Project Delivery Format

按照以下格式输出所有文件内容（每个文件以

--- 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 完整内容>

Output all file contents in the following format (each file starts with

--- FILE: filename ---

Small project (single file):

--- FILE: README.md ---
<Full content of README.md>

--- FILE: pyproject.toml ---
<Full content of pyproject.toml>

--- FILE: uv.lock ---
<Full content of uv.lock>

--- FILE: main.py ---
<Full content of main.py>

--- FILE: docs/background.md ---
<Full content of docs/background.md>

--- FILE: docs/requirements.md ---
<Full content of docs/requirements.md>

--- FILE: docs/architecture.md ---
<Full content of docs/architecture.md>

--- FILE: docs/database-design.md ---
<Full content of docs/database-design.md>

--- FILE: docs/data-abstraction.md ---
<Full content of docs/data-abstraction.md>

--- FILE: test_report.md ---
<Full content of test_report.md>

Large project (folder organization):

--- FILE: README.md ---
<Full content of README.md>

--- FILE: pyproject.toml ---
<Full content of pyproject.toml>

--- FILE: uv.lock ---
<Full content of uv.lock>

--- FILE: src/__init__.py ---
<Full content of src/__init__.py>

--- FILE: src/main.py ---
<Full content of src/main.py>

--- FILE: src/repositories/__init__.py ---
<Full content of src/repositories/__init__.py>

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

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

--- FILE: tests/__init__.py ---
<Full content of tests/__init__.py>

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

--- FILE: docs/background.md ---
<Full content of docs/background.md>

--- FILE: docs/requirements.md ---
<Full content of docs/requirements.md>

--- FILE: docs/architecture.md ---
<Full content of docs/architecture.md>

--- FILE: docs/database-design.md ---
<Full content of docs/database-design.md>

--- FILE: docs/data-abstraction.md ---
<Full content of docs/data-abstraction.md>

--- FILE: test_report.md ---
<Full content of test_report.md>

功能扩展交付格式

Feature Extension Delivery Format

--- 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: docs/requirements.md ---
<Updated requirements.md>

--- FILE: docs/architecture.md ---
<Updated architecture.md>

--- FILE: docs/database-design.md ---
<Updated database-design.md>

--- FILE: docs/data-abstraction.md ---
<Updated data-abstraction.md>

--- FILE: main.py or src/... ---
<Modified code files>

--- FILE: pyproject.toml ---
<Updated pyproject.toml (if any)>

--- FILE: README.md ---
<Updated README.md>

--- FILE: feature_extension_plan.md ---
<Feature extension plan document>

重构交付格式

Refactoring Delivery Format

--- 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 ---
<更新后的测试报告>

--- FILE: main.py or src/... ---
<Refactored code files>

--- FILE: docs/architecture.md ---
<Updated architecture.md (including skill recognition)>

--- FILE: docs/database-design.md ---
<Updated database-design.md>

--- FILE: docs/data-abstraction.md ---
<Updated data-abstraction.md>

--- FILE: refactoring_report.md ---
<Refactoring report>

--- FILE: test_report.md ---
<Updated test report>

资源索引

Resource Index

背景知识模板：见 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

Background knowledge template: See references/background-template.md
Requirement document template: See references/requirements-template.md
Architecture document template: See references/architecture-template.md
UV lock file template: See references/uv-lock-template.md
Task list template: See references/todo-template.md
Test report template: See references/test-report-template.md
Project description template: See references/readme-template.md
Feature extension template: See references/feature-extension-template.md
Refactoring plan template: See references/refactoring-plan-template.md
Database selection guide: See references/database-selection-guide.md
Database design template: See references/database-design-template.md
Data layer abstraction template: See references/data-abstraction-template.md

注意事项

Notes

核心要求（强制）

Core Requirements (Mandatory)

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

UV package management: Must use UV as the package management tool, use
```
pyproject.toml
```
to manage dependencies,
```
uv.lock
```
to lock versions
loguru logging: Must use loguru for logging
Python 3.11+ features: Must use type annotations, PEP 585 built-in generic types
Project size adaptation: Evaluate scale in PM phase, select organization method in architect phase
Version control mechanism: Use Semantic Versioning (vX.Y.Z), record version history
Skill recognition and management: Identify skills in architecture phase, reuse skills in implementation phase
Database design and implementation: Select appropriate database based on requirements (SQLite, PostgreSQL, MongoDB, vector databases, graph databases)
Data layer abstraction: Must implement Repository pattern, provide unified CRUD interface
Database switching capability: Support switching between different database implementations through configuration

流程要求

Process Requirements

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

Autonomous learning phase: Must execute web search, cannot skip
Requirement clarification limit: Maximum 2 rounds of interaction in PM phase, proceed with existing information if exceeded
No over-design: Strictly implement according to user requirements, do not add unmentioned functions
Background knowledge application: All phases must refer to and apply knowledge in background.md
Code quality: Ensure generated code can be run directly, with complete error handling

技术选型（强制）

Technical Selection (Mandatory)

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

Must compare at least 2 solutions in detail
Must explain trade-off reasons (performance vs ease of use, functionality vs complexity)
Must reference comparison data in background.md
Must explain the advantages and disadvantages of the selected solution

数据库要求（强制）

Database Requirements (Mandatory)

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

Database selection: Select appropriate database based on project requirements, refer to database-selection-guide.md
Data model design: Design reasonable table/collection structure, define indexing strategies
Data access layer: Implement Repository pattern, provide unified CRUD interface
Type safety: All data access functions must include type annotations
Performance optimization: Reasonable indexing strategies, connection pool configuration, query optimization

状态同步

Status Synchronization

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

todo.md must correspond one-to-one with functional points in requirements.md
Test report must cover all functional points, clearly mark pass status

功能扩展

Feature Extension

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

Prioritize reusing existing skills to avoid repeated development
Ensure new functions are consistent with existing code style
Update all related documents (including database design documents)
Execute regression testing
Database extension: Evaluate whether new tables/collections are needed, Repository updates, migration script writing

重构

Refactoring

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

Analyze before execution, avoid blind refactoring
Keep functions unchanged, only optimize internal implementation
Database optimization: Optimize queries, indexes, connection pools
Record comparison data before and after refactoring
Identify and extract skill modules

使用示例

Usage Examples

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

Example 1: User Management System with Database (Large Project)

用户需求："实现一个用户管理系统，支持用户注册、登录、信息查询"
阶段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 操作、并发操作、数据库性能、类型注解、数据访问层抽象

User requirement: "Implement a user management system that supports user registration, login, and information query"
Phase 0: Search "database selection", "SQLAlchemy vs MongoDB", "user authentication best practices", "password encryption", "Python 3.11+ type annotations", "UV package management", "Repository pattern"
PM phase:
- Clarify data scale, concurrency requirements, authentication method, password storage
- Clarify database requirements: Relational data (user information), expected 100,000 users
- Evaluate project scale: 5 functional points → medium project → select PostgreSQL (supports high concurrency)
Architect phase:
- Database selection: PostgreSQL (relational, supports high concurrency)
- Design data model: User table (id, username, email, password_hash, created_at)
- Design data access layer: BaseRepository interface, SQLAlchemyBaseRepository, UserRepository
- Design RepositoryFactory: Supports PostgreSQL / SQLite switching
- Indexing strategy: username (UNIQUE), email (UNIQUE), created_at (INDEX)
- Select large project architecture: src/repositories/ data access layer
- Identify skill modules: Password encryption, Token generation
Senior Dev phase:
- Implement BaseRepository interface (CRUD operations)
- Implement SQLAlchemyBaseRepository
- Implement UserRepository (get_by_email, get_by_username)
- Implement RepositoryFactory
- Use Python 3.11+ features, type annotations
- Use loguru for logging
- Generate
```
pyproject.toml
```
  (sqlalchemy, psycopg2-binary, alembic)
Verification phase: Test CRUD operations, concurrent operations, database performance, type annotations, data access layer abstraction

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

Example 2: Document Management System (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 操作、全文搜索、性能

User requirement: "Implement a document management system that supports CRUD operations and full-text search of documents"
PM phase:
- Clarify document format, storage method, search requirements
- Clarify database requirements: Document-type data, flexible schema and full-text search required
- Evaluate project scale: 4 functional points → small project → select MongoDB (document-type, flexible schema)
Architect phase:
- Database selection: MongoDB (document-type, supports full-text search)
- Design data model: Document collection (title, content, tags, metadata, created_at)
- Design data access layer: MongoDBBaseRepository, DocumentRepository
- Indexing strategy: title (TEXT), content (TEXT), tags (MULTIKEY)
Senior Dev phase:
- Implement MongoDBBaseRepository
- Implement DocumentRepository (search_by_keyword)
- Use pymongo, type annotations
Verification phase: Test CRUD operations, full-text search, performance

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

Example 3: Vector Search System (ChromaDB)

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

User requirement: "Implement a vector search system that supports semantic search of documents"
PM phase:
- Clarify vector dimensions, similarity metrics, data scale
- Clarify database requirements: Vector search, expected 1,000,000 vectors
- Evaluate project scale: 3 functional points → small project → select ChromaDB (vector database, lightweight)
Architect phase:
- Database selection: ChromaDB (vector database, designed for LLM)
- Design data model: ChromaDB collection (documents, embeddings, metadata)
- Design data access layer: VectorRepository
Senior Dev phase:
- Implement VectorRepository (add_document, search)
- Use chromadb, type annotations
Verification phase: Test vector addition, similarity search, performance

技能调用机制

Skill Invocation Mechanism

识别时机

Recognition Timing

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

Architecture phase (Phase 2): Identify possible reusable skill modules, define in architecture.md
Implementation phase (Phase 3): Prioritize calling defined skills when implementing new functions
Extension phase (Phase 5): Reuse existing skills when adding functions
Refactoring phase (Phase 6): Extract new skill modules during refactoring

技能接口规范

Skill Interface Specifications

所有技能必须包含：

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

All skills must include:

Complete type annotations: Function parameters and return values must use type annotations
Clear docstrings: Explain functions, parameters, return values, usage scenarios
Example code: Provide invocation examples in architecture.md
Dependency declaration: Clearly specify other skills or libraries that depend on

复用原则

Reuse Principles

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

Prioritize reuse: Prioritize calling existing skills when implementing new functions
Stable interface: Skill interfaces should remain stable, avoid frequent modifications
Single responsibility: Skills should have a single responsibility and clear functions
Testability: Skills should be easy to test individually

数据访问技能

Data Access Skills

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

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

The following data access layer modules can be reused as skills:

BaseRepository interface: General CRUD interface
SQLAlchemyBaseRepository: General implementation for relational databases
MongoDBBaseRepository: General implementation for MongoDB
RepositoryFactory: Database switching factory