clj-skill-eval

Clojure 技能评估框架

评估 Clojure 技能需要能够体现可衡量行为差异的真实项目，而不是假设性的推断。这项技能要求采用严谨的评估方法，对比在相同任务中使用技能与不使用技能的开发表现。

核心原则

只有技能能改变实际行为，才有意义。

评估方法：

1. 创建两个隔离的项目（使用技能／不使用技能）
2. 在两个项目中执行相同的真实开发任务
3. 对比：代码质量、开发时间、文档深度、测试全面性
4. 分析 context-logs，观察行为差异（REPL 使用情况、探索模式、调试方法）

---

阶段 1：评估规划

定义要评估的技能

输入：

• 技能名称和路径（例如，clj-discover、clj-debug）
• 技能应改变什么行为？（例如，“应从基于日志的调试转向基于 REPL 的调试”）

输出：

• 明确的评估假设（而非模糊的推断）
• 要衡量的可观察行为差异列表

设计真实的开发任务

要求：

• 真实项目场景——不是玩具示例或牵强的问题
• 具体要求——成功标准明确，而不是含糊的规格
• 中等复杂度——足以展现技能价值，但并非简单任务（每个版本需 5-15 分钟）
• 任务类型多样——不同类型的任务可以展现技能的不同优势：
  • 探索任务：“使用不熟悉的库／API 实现功能”（测试 clj-discover）
  • 调试任务：“修复现有系统中的错误”（测试 clj-debug）
  • 探查任务：“理解并修改宏的行为”（测试 clj-discover）
  • 集成任务：“通过互操作使用 Java 库”（测试 clj-discover）

任务示例：

Implement GET /system-stats API endpoint that returns CPU usage and memory info.
- Use OSHI library for system statistics
- Return JSON with cpu-usage (0.0-1.0) and memory-info {total, available}
- Include at least one passing test

制定评估标准

定量指标：

• 执行时间（秒、分钟）
• Token 用量
• 代码行数
• 文档文件数量
• 测试覆盖率

定性指标：

• API 选择（找到最佳路径还是基本路径？）
• 代码质量（注释、清晰度、类型安全）
• 测试防御性（覆盖了哪些场景？）
• 文档深度（是否解释决策，还是只记录结果？）
• 行为模式（是否使用 REPL？是否添加日志？读取了哪些文件？）

---

阶段 2：项目设置

创建两个隔离的项目

使用 neil 生成两个相同的 Clojure Stack Lite 项目：

neil new io.github.abogoyavlensky/clojure-stack-lite my-test-without-skill
neil new io.github.abogoyavlensky/clojure-stack-lite my-test-with-skill

然后在每个项目中：

cd my-test-without-skill && neil add nrepl
cd my-test-with-skill && neil add nrepl

为什么要隔离？

• 没有共享状态或配置
• 可以并行运行，互不干扰
• 各自获得干净的 Integrant 系统，并执行 (reset)

创建任务说明

在两个项目中创建内容相同的 TASK.md，列出相同的要求：

# Task: [Implementation Task Name]

## Objective
[Clear, concrete objective]

## Requirements
[Bullet points with specific requirements]

## Success Criteria
✓ Criterion 1
✓ Criterion 2

---

阶段 3：使用子 Agent 并行执行

关键权限设置

在 Claude Code 中运行子 Agent 时，使用 --dangerously-skip-permissions，避免受到权限限制：

claude --dangerously-skip-permissions [your-claude-code-command]

**为什么有必要：**技能可能会使用需要明确授权的工具（brepl、WebSearch、文件操作）。如果没有此标志，子 Agent 可能会因“权限限制”而中止，而不是完成任务。

并行启动两个版本

同时（在同一轮中）创建两个子 Agent，以确保计时结果具有可比性：

子 Agent 1（不使用技能）：

Execute this task in /path/to/my-test-without-skill:

1. Read TASK.md to understand requirements
2. Complete the implementation task
3. Save all final code files to outputs/
4. Record your approach in outputs/APPROACH.md:
   - How did you discover what to do?
   - What APIs/libraries did you choose and why?
   - What debugging/exploration did you do?
   - How much time was spent coding vs exploring?
5. DO NOT use any Clojure skills

Focus: Complete the task efficiently.

子 Agent 2（使用技能）：

Execute this task in /path/to/my-test-with-skill:

1. Read TASK.md to understand requirements
2. Complete the implementation task
3. Save all final code files to outputs/
4. Record your approach in outputs/APPROACH.md:
   - Which skills did you use and when?
   - How did each skill influence your decisions?
   - What exploration patterns did you use?
   - Did you use REPL-based debugging or log-based?
5. Use these Clojure skills as they become relevant:
   - clj-discover (understanding APIs, Java interop, macros)
   - clj-debug (interactive debugging via brepl)
   - clj-replace (structural code replacement)

Focus: Complete the task with skill guidance.

**重要：**在同一轮中启动两个子 Agent，确保计时结果具有可比性。

---

阶段 4：深入对比分析

代码质量对比

对比生成的代码文件（处理器、路由、测试）：

API 选择：

• 不使用技能的一方是否选择了最显而易见的路径？
• 使用技能的一方是否找到了更优／更标准的 API 路径？
• 是否有研究的证据，还是直接开始编码？

类型安全：

• 是否进行了显式类型转换，还是依赖隐式假设？
• 是否有注释说明复杂之处？
• 是否处理错误，还是只考虑正常情况？

测试防御性：

• 只有基本断言，还是有全面覆盖？
• 是否处理边缘情况？
• 是否验证业务逻辑（例如，可用数量 ≤ 总数量）？

文档对比

对比 APPROACH.md 和生成的文档：

WITHOUT-skill 应展示：

• “不经探索，直接实现”
• 对决策过程的解释很简略
• 快速成功

WITH-skill 应展示：

• “实现前先研究库”
• “在 REPL 中测试，验证方案”
• 清晰说明 API 选择的理由
• 更全面的文档

行为模式分析

根据 APPROACH.md，识别以下模式：

模式	WITHOUT-skill	WITH-skill	重要性
REPL 使用情况	没有／很少使用	频繁进行交互式测试	表明使用了技能辅助调试
文件读取	零散探索	有针对性的研究	技能指导应查看哪些内容
调试方法	日志／println	交互式 brepl	核心行为转变
文档	简略	详细说明理由	技能鼓励深入思考

时间与令牌数据

从子 Agent 通知中收集：

• 执行时间（WITHOUT-skill 应更快，但质量较低）
• 令牌总数（WITH-skill 探索更多）
• 质量与耗时比

---

第 5 阶段：得出结论

技能效果评分

针对每项技能，估算：

• 使用强度：技能实际发挥了多大作用？（⭐ 等级）
• 对行为的影响：是否改变了开发方法？（是／否）
• 适用性：对哪些类型的任务有价值？

撰写评估报告

结构：

# Evaluation Report: [Skill Name]

## Executive Summary
One sentence: Did the skill improve development outcomes?

## Task Executed
[Task description and success criteria]

## Key Findings

### Quantitative Comparison
- Time: [without-skill] vs [with-skill]
- Tokens: [without-skill] vs [with-skill]
- Code quality metrics

### Behavioral Differences
- API choices: [specific example]
- Testing approach: [specific example]
- Documentation depth: [specific example]

### Skill Activation Analysis
- Which skills were used: [list with ⭐ ratings]
- Permission issues: [if any]
- Unexpected patterns: [if any]

## Recommendations
- Is the skill valuable? [YES/NO with justification]
- In what scenarios is it most useful?
- What could be improved?

---

第 6 阶段：迭代与完善

如果技能效果不明确：

1. 设计更适合该技能的任务

   • 如果未触发 clj-discover：添加一个需要探索陌生 API 的任务
   • 如果未使用 clj-debug：添加一个需要交互式调试的任务

2. 使用新任务再次运行评估

3. 比较多个任务中的模式，了解技能何时、为何会被触发

---

应避免的反模式

❌ 请勿：

• 提出假设性问题（“这项技能对 X 有帮助吗？”）
• 根据“知识传递”给技能打分（技能应该改变行为，而不只是提供信息）
• 将“已加载技能但未执行”视为成功
• 只运行无法展现技能价值的简单任务
• 不与基线进行比较就开展评估

✅ 请：

• 在启用／未启用技能的条件下运行相同任务
• 衡量实际的行为变化（REPL 使用情况、探索模式、调试方法）
• 分析技能未触发或触发的原因
• 使用多种任务类型进行测试，找出技能最能发挥作用的场景
• 记录具体的代码／文档差异

---

任务类型参考

使用以下类型设计多样化的评估任务：

1. 探索任务（触发 clj-discover）

“使用陌生的库实现功能”

• 示例：“使用 auth0 库添加 JWT 身份验证”
• 技能价值：帮助在不反复试错的情况下熟悉陌生 API

2. 调试任务（触发 clj-debug）

“修复多组件系统中的错误”

• 示例：“用户报告登录失败；调试 Integrant 系统生命周期”
• 技能价值：将调试方式从基于日志转为交互式 REPL 调试

3. 宏／元编程任务（触发 clj-discover）

“理解并修改宏的行为”

• 示例：“扩展 defroutes 宏以支持新的模式”
• 技能价值：解释宏展开和元模式

4. Java 互操作任务（触发 clj-discover）

“集成 Java 库”

• 示例：“通过 OSHI 库添加系统监控”（我们测试过的任务）
• 技能价值：阐明如何查阅 Java API 并选择方法

---

请记住

只有当技能改变了 Claude 编写代码的方式，而不仅仅是产出的代码时，它才有意义。

如果评估显示技能没有改变行为，这也是有价值的数据——这意味着：

1. 需要调整技能的触发条件
2. 需要重新思考技能的内容
3. 任务不适合发挥该技能的优势

这些问题都可以解决。但只有衡量行为变化，才能知道答案。