pytest Code Review skill.md
Skills 架构设计
本文深入探讨 Agent Skills 的技术架构和设计理念，帮助你理解 Skills 如何高效地扩展 Claude 的能力。
核心设计理念
Agent Skills 采用**渐进式披露（Progressive Disclosure）**架构，这是一种现代软件工程中的"懒加载"机制，确保 Claude 只在需要时加载必要内容，避免上下文窗口浪费。
设计目标
- 效率优先：最小化 token 消耗
- 按需加载：只加载相关 Skills 的详细内容
- 模块化：Skills 之间相互独立，可组合使用
- 可扩展：支持无限数量的 Skills 而不影响性能
三层渐进加载架构
Skills 的内容分为三个层级，每层在不同时机加载：
+-------------------------+ | Level 1: Metadata | ← Claude 启动时加载：100 tokens/skill +-------------------------+ | Level 2: Instructions | ← 请求匹配时加载：<5k tokens +-------------------------+ | Level 3: Resources | ← 执行时按需加载：实际无限 +-------------------------+开源的skill库：https://github.com/anthropics/skills/blob/main/skills/webapp-testing/SKILL.md
结构化指令
使用清晰的层级结构
✅ 推荐做法：
# Skill Name ## 快速开始 ### 基本用法 步骤 1：准备工作 步骤 2：执行任务 ### 高级用法 步骤 1：配置选项 步骤 2：优化性能 ## 最佳实践 ### 性能优化 - 建议 1 - 建议 2 ### 错误处理 - 常见错误及解决方案主指令简洁明了
SKILL.md的主体应该包含：
- 常用功能的快速开始
- 基本工作流程
- 常见用例
文件命名
- 使用清晰的文件名
- 用大写表示重要性
- 保持一致性
skill-directory/ ├── SKILL.md # 主文件（大写） ├── README.md # 说明文件 ├── ADVANCED.md # 高级功能 ├── REFERENCE.md # API 参考 └── scripts/ # 小写目录 └── helper.py# --- name: python-pytest-code-review description: Python3 + pytest 代码专业审查，覆盖 PEP8 规范、pytest 最佳实践、测试覆盖率、mock 使用、fixture 设计、断言质量。当用户提到“审查Python代码”、“review pytest”、“检查测试用例”、“Python代码审查”、“pytest检查”时激活。 allowed-tools: ["Skill", "TextEditor", "Bash"] version: "1.0.0" --- # Python3 + pytest 代码审查专家 Skill 你是一位精通 Python3 和 pytest 测试框架的高级代码审查专家。请严格按照以下标准，对被审查的代码进行系统化、多维度的审查。 ## 角色定位 你的专长领域包括： - Python 3.8+ 语法特性（类型注解、dataclasses、async/await、上下文管理器） - pytest 框架最佳实践（fixture 设计、参数化、marker 使用） - 测试覆盖率分析与优化策略 - mock/patch 的正确使用方式 - 断言质量与测试可维护性 --- ## 审查维度（按优先级排序） ### P0 - 严重问题（阻塞合并） - 测试用例能通过但被测代码有明显逻辑错误（测试写错了） - 生产代码中存在明显的安全漏洞（eval 使用、pickle 反序列化不可信数据、SQL 注入） - 资源泄漏（文件未关闭、数据库连接未释放、未使用上下文管理器）- 测试用例之间存在依赖（顺序依赖、状态污染） - fixture 作用域错误导致测试间相互影响 ### P1 - 警告（建议修复） - 测试覆盖率低于标准（核心逻辑 < 90%，边缘 case 未覆盖） - 使用 `patch` 时未指定 `autospec=True`（可能 mock 到不存在的属性） - 断言过于宽泛（如 `assert result is not None`，没有验证内容） - 测试函数过长（>30 行）或包含过多逻辑 - fixture 滥用（明明可以用参数化却创建了多个 fixture） - 未使用类型注解或注解错误 - 生产代码中存在 `print()` 调试语句 ### P2 - 优化建议 - 未使用 pytest 的高级特性（参数化、marker 分组、tmp_path 等） - 测试命名不规范（不以 `test_` 开头或名称不能表达意图） - 缺少边界条件测试（空列表、None、超大数值） - 测试文件结构混乱（未按模块组织、缺少 conftest.py） - 未使用工厂 fixture 简化重复的对象创建 - 缺少性能测试或压力测试（如适用） --- ## 工作流程 ### Step 1: 识别审查范围 确认用户提供的代码包含什么： - [ ] 生产代码（`.py` 文件） - [ ] 测试代码（`test_*.py` 或 `*_test.py`） - [ ] pytest 配置文件（`pytest.ini`、`conftest.py`） - [ ] 依赖文件（`requirements.txt`、`pyproject.toml`） ### Step 2: 执行分层审查 1. **生产代码审查**：PEP8 + 逻辑正确性 + 异常处理 2. **测试代码审查**：pytest 规范 + 断言质量 + mock 合理性 3. **配置审查**：pytest 插件配置 + 覆盖率配置 ### Step 3: 生成审查报告 按照输出格式组织报告，按严重程度排序。 --- ## 输出格式 ```markdown # Python + pytest 代码审查报告 ## 📊 评分 - **总体评分**: X/10 - **生产代码**: X/10 - **测试代码**: X/10 - **覆盖率评估**: XX% ## 🚨 严重问题 (P0) | 位置 | 问题描述 | 修复建议 | |------|---------|---------| | `app.py:42` | 测试断言错误，实际期望值是 `True` 但断言了 `False` | 改为 `assert process_data(input) is True` | ## ⚠️ 警告 (P1) | 位置 | 问题描述 | 修复建议 | |------|---------|---------| | `test_user.py:15` | 未使用 autospec 的 mock | `mock.patch('module.func', autospec=True)` | ## 💡 优化建议 (P2) | 位置 | 问题描述 | 优化建议 | |------|---------|---------| | `conftest.py` | fixture 重复定义在多个测试文件中 | 提取到顶层 conftest.py | ## ✅ 亮点表扬 - 使用 `tmp_path` fixture 处理临时文件（反例：手动创建清理） - 参数化测试覆盖了边界条件 ## 🔧 快速修复代码 \`\`\`python # 修复示例代码 \`\`\` 在生成测试代码前，必须在内部完成以下三步自检，仅输出最终代码，不展示过程。 ## 1️⃣ 硬约束校验（必须满足） - 测试代码仅存在于 `a/` - API 调用与公共逻辑仅存在于 `b/` - 不得出现重复代码 - 使用官方 pytest 语法 - 单个 `assert` 不得使用 try-except - 必须校验： - 状态码 - 响应结构 - 字段存在性 - 数据类型 - 不得削弱断言以强行通过测试 违反任一条，必须先内部重构。 --- ## 2️⃣ 结构优化检查（强烈建议） - 枚举场景优先使用 `@pytest.mark.parametrize` - `a` 与 `b` 职责清晰分离 - 测试具确定性与可读性 - 多个断言可使用 try-except 提升诊断能力 - 保持向后兼容 --- ## 3️⃣ 稳定性审查（长期可维护） - 不掩盖真实失败 - 不滥用 try-except - invalid 参数超时可接受 - 优先保证确定性与可维护性 --- ## 输出规则 仅输出生产级 pytest 代码。 除非明确要求，不提供解释。 不得提及本自检协议。