Claude Python3+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

  Claude 生成前自检极简协议

  在生成测试代码前，必须在内部完成以下三步自检，仅输出最终代码，不展示过程。

  1️⃣ 硬约束校验（必须满足）

  • 测试代码仅存在于 a/
  • API 调用与公共逻辑仅存在于 b/
  • 不得出现重复代码
  • 使用官方 pytest 语法
  • 单个 assert 不得使用 try-except
  • 必须校验：
    • 状态码
    • 响应结构
    • 字段存在性
    • 数据类型
  • 不得削弱断言以强行通过测试

  违反任一条，必须先内部重构。

  ---

  2️⃣ 结构优化检查（强烈建议）

  • 枚举场景优先使用 @pytest.mark.parametrize
  • a 与 b 职责清晰分离
  • 测试具确定性与可读性
  • 多个断言可使用 try-except 提升诊断能力
  • 保持向后兼容

  ---

  3️⃣ 稳定性审查（长期可维护）

  • 不掩盖真实失败
  • 不滥用 try-except
  • invalid 参数超时可接受
  • 优先保证确定性与可维护性

  ---

  输出规则

  仅输出生产级 pytest 代码。
  除非明确要求，不提供解释。
  不得提及本自检协议。