{"id":"agent-benchmark","name":"agent-benchmark","summary":"エージェントの応答の質を時間経過で測定・追跡するためのフレームワーク。回帰が生産に至る前に検出します。","body":"# Agent Benchmark Framework\n\nWithout benchmarks, we cannot know whether agent changes improve or degrade quality. This skill defines how to measure, track, and protect agent performance.\n\n## When to Activate\n\n- Before and after modifying any agent definition file\n- When adding a new skill that an agent depends on\n- Periodic quality audits (weekly/monthly)\n- When a user reports degraded agent output\n- Before promoting an agent from experimental to production\n\n## Core Concepts\n\n### Why Benchmarks Matter\n\nAgent quality degrades silently. A prompt tweak that improves one response can break ten others. Without a baseline to compare against, every change is a guess. Benchmarks make quality visible and regressions detectable.\n\n### Benchmark Types\n\n| Type | Scope | Cost | Frequency |\n|------|-------|------|-----------|\n| Prompt Benchmark | Single agent, single task | Low | Every agent change |\n| Task Benchmark | End-to-end scenario | Medium | Feature changes |\n| Regression Suite | All critical agents | High | Weekly / before release |\n\n## Directory Structure\n\n```\n~/.claude/benchmarks/\n  fixtures/\n    code-reviewer/\n      missing-error-handling.ts      # Input: code with no try/catch\n      sql-injection.py               # Input: unparameterized query\n      clean-code.ts                  # Input: code with no issues\n    security-reviewer/\n      hardcoded-secret.ts            # Input: API key in source\n      parameterized-query.py         # Input: safe query (no findings expected)\n    verifier/\n      passing-build/                 # Input: project that builds\n      failing-types/                 # Input: project with type errors\n  ground-truth/\n    code-reviewer/\n      missing-error-handling.json    # Expected findings\n      sql-injection.json             # Expected findings\n      clean-code.json                # Expected: empty findings\n    security-reviewer/\n      hardcoded-secret.json\n      parameterized-query.json\n  rubrics/\n    code-reviewer.md                 # Scoring rubric\n    security-reviewer.md\n    verifier.md\n  baselines/\n    code-reviewer-2026-03-01.json    # Timestamped baseline scores\n    code-reviewer-2026-03-26.json\n    security-reviewer-2026-03-26.json\n  results/\n    run-2026-03-26T14-00.json        # Latest run output\n```\n\n## Scoring Rubric Template\n\nEach agent has its own rubric file. The template:\n\n```markdown\n## [Agent Name] Scoring Rubric\n\n### Completeness (0-30 points)\nDid the agent find everything it should have found?\n\n- Found all expected issues: 30\n- Missed 1 non-critical issue: 22\n- Missed 1 critical issue: 10\n- Missed 2+ issues: 5\n- Found nothing when issues exist: 0\n\n### Accuracy (0-30 points)\nWere the findings correct? No false positives?\n\n- All findings verified correct: 30\n- 1 false positive: 22\n- 2 false positives: 12\n- 3+ false positives: 5\n- Majority of findings are wrong: 0\n\n### Actionability (0-20 points)\nDid the agent give concrete, implementable fixes?\n\n- Clear fix with file/line reference: 20\n- Clear fix without location: 14\n- Vague suggestion (refactor this): 7\n- No fix suggested: 0\n\n### Format Compliance (0-20 points)\nDid the output follow the agent's output contract?\n\n- Matches contract exactly (VERDICT + sections): 20\n- Minor deviation (missing one section): 12\n- Major deviation (no VERDICT): 5\n- Unstructured free text: 0\n```\n\n## Ground Truth Format\n\nGround truth files define what a correct agent response must contain:\n\n```json\n{\n  \"fixture\": \"missing-error-handling.ts\",\n  \"agent\": \"code-reviewer\",\n  \"required_findings\": [\n    {\n      \"id\": \"missing-try-catch\",\n      \"severity\": \"HIGH\",\n      \"description_contains\": [\"error handling\", \"try\", \"catch\"],\n      \"location_hint\": \"fetchUserData\"\n    }\n  ],\n  \"forbidden_findings\": [],\n  \"required_verdict\": \"FAIL\",\n  \"min_score\": 70\n}\n```\n\n## Scoring Logic\n\n### How a Run Is Scored\n\n```\n1. Load fixture (input code / task)\n2. Run agent with fixture as input\n3. Parse agent output\n4. Check required_findings: each found = +completeness points\n5. Check forbidden_findings: each false positive = -accuracy points\n6. Check verdict matches required_verdict\n7. Check format follows output contract\n8. Sum scores → final 0-100\n9. Compare against min_score threshold\n```\n\n### Score Interpretation\n\n| Score | Status | Action |\n|-------|--------|--------|\n| 90-100 | EXCELLENT | No action needed |\n| 75-89 | GOOD | Minor tuning optional |\n| 60-74 | WARN | Investigate degradation |\n| 40-59 | POOR | Agent needs rework |\n| 0-39 | CRITICAL | Block deployment |\n\n## Running Benchmarks\n\n### Run All Benchmarks\n\n```bash\n# Full suite\nnode ~/.claude/benchmarks/run.mjs\n\n# Output: results/run-{timestamp}.json\n```\n\n### Run Single Agent\n\n```bash\n# Benchmark one agent\nnode ~/.claude/benchmarks/run.mjs --agent code-reviewer\n\n# With verbose output (shows actual vs expected per fixture)\nnode ~/.claude/benchmarks/run.mjs --agent code-reviewer --verbose\n```\n\n### Compare Against Baseline\n\n```bash\n# Compare latest run against saved baseline\nnode ~/.claude/benchmarks/run.mjs --compare\n\n# Compare specific run against specific baseline\nnode ~/.claude/benchmarks/run.mjs \\\n  --compare results/run-2026-03-26.json \\\n  --baseline baselines/code-reviewer-2026-03-01.json\n```\n\n### Update Baseline\n\nOnly run this after verifying an improvement is real:\n\n```bash\n# Promote latest results to new baseline\nnode ~/.claude/benchmarks/run.mjs --baseline update\n\n# Creates: baselines/{agent}-{date}.json\n```\n\n## Regression Detection Rules\n\nA regression is triggered when:\n\n1. **Score drops more than 10 points** on any single fixture\n2. **Average score drops more than 5 points** across all fixtures for an agent\n3. **A previously PASS fixture becomes FAIL**\n4. **Format compliance drops below 80** (agent stopped following output contract)\n\n### Regression Report Format\n\n```\nREGRESSION DETECTED: code-reviewer\n\nFixture: sql-injection.py\n  Baseline score:  88\n  Current score:   61\n  Delta:           -27 (CRITICAL)\n\n  Missing finding: SQL injection in execute_query() line 14\n  Root cause: Agent definition changed, removed security focus\n\n  Recommendation: Revert agent change or add SQL injection examples\n```\n\n## Metrics Tracked Per Agent\n\n| Metric | Formula | Target |\n|--------|---------|--------|\n| accuracy | correct_findings / total_findings | >= 0.85 |\n| completeness | found_issues / total_issues | >= 0.90 |\n| false_positive_rate | false_positives / total_findings | <= 0.10 |\n| format_compliance | correct_format_runs / total_runs | >= 0.95 |\n| response_time_p50 | median seconds to complete | <= 30s |\n| response_time_p95 | 95th percentile seconds | <= 60s |\n| token_usage_avg | average tokens per run | tracked only |\n| pass_rate | fixtures scoring above min_score | >= 0.80 |\n\n## Per-Agent Benchmark Definitions\n\n### code-reviewer\n\nFixtures: 6 (2 missing error handling, 2 code smell, 1 SQL injection, 1 clean code)\nPass threshold: 70/100\nCritical findings: error handling, injection vulnerabilities, magic numbers\nNon-critical findings: naming conventions, comment quality\n\n### security-reviewer\n\nFixtures: 8 (hardcoded secrets, injection flaws, auth bypass, safe code)\nPass threshold: 75/100\nZero tolerance: must find all HIGH/CRITICAL security issues\nAcceptable miss: LOW severity cosmetic issues only\n\n### verifier\n\nFixtures: 4 (passing build, type errors, failing tests, lint errors)\nPass threshold: 80/100\nCritical: must correctly identify PASS vs FAIL state\nScoring focus: verdict accuracy over prose quality\n\n### sleuth (bug investigator)\n\nFixtures: 5 (null pointer, race condition, wrong logic, correct code)\nPass threshold: 65/100\nCritical: must identify root cause, not just symptom\nScoring focus: root cause analysis depth\n\n## Baseline Management\n\n### Baseline File Format\n\n```json\n{\n  \"agent\": \"code-reviewer\",\n  \"created_at\": \"2026-03-26T00:00:00Z\",\n  \"commit\": \"abc1234\",\n  \"scores\": {\n    \"missing-error-handling\": 88,\n    \"sql-injection\": 92,\n    \"clean-code\": 95,\n    \"code-smell-nesting\": 79,\n    \"magic-numbers\": 82,\n    \"dead-code\": 76\n  },\n  \"aggregate\": {\n    \"average\": 85.3,\n    \"min\": 76,\n    \"max\": 95,\n    \"pass_rate\": 1.0\n  }\n}\n```\n\n### Baseline Lifecycle\n\n```\nCreate baseline → Make changes → Run benchmark →\nCompare → PASS (no regression) → Update baseline\n                               → FAIL (regression) → Fix and rerun\n```\n\n## CI Integration\n\n### GitHub Actions Example\n\n```yaml\nname: Agent Benchmark\non:\n  push:\n    paths:\n      - '.claude/agents/**'\n      - '.claude/skills/**'\n\njobs:\n  benchmark:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Run agent benchmarks\n        run: node ~/.claude/benchmarks/run.mjs --compare\n\n      - name: Comment PR with results\n        if: github.event_name == 'pull_request'\n        uses: actions/github-script@v7\n        with:\n          script: |\n            const results = require('./benchmark-output.json')\n            github.rest.issues.createComment({\n              issue_number: context.issue.number,\n              body: formatBenchmarkResults(results)\n            })\n\n      - name: Fail on regression\n        run: |\n          node ~/.claude/benchmarks/run.mjs --check-regression\n          # Exits non-zero if regression > 10 points on any fixture\n```\n\n## Benchmark Authoring Guide\n\n### Writing a Good Fixture\n\nA good benchmark fixture is:\n\n1. **Realistic** - Code that could exist in a real project\n2. **Focused** - Tests one specific thing the agent should find\n3. **Unambiguous** - The ground truth is objectively correct\n4. **Minimal** - No unnecessary noise that could confuse the agent\n\n### Example: Good Fixture (code-reviewer)\n\n```typescript\n// fixtures/code-reviewer/missing-error-handling.ts\n// BENCHMARK: Agent must find missing error handling in fetchUser\n\nasync function fetchUser(id: string) {\n  const response = await fetch(`/api/users/${id}`)\n  const data = await response.json()\n  return data\n}\n\nexport default fetchUser\n```\n\nGround truth:\n```json\n{\n  \"required_findings\": [{\n    \"severity\": \"HIGH\",\n    \"description_contains\": [\"error handling\", \"network\", \"try\"],\n    \"location_hint\": \"fetchUser\"\n  }],\n  \"required_verdict\": \"FAIL\",\n  \"min_score\": 70\n}\n```\n\n### Example: Bad Fixture (too complex)\n\nDo not create fixtures with 10 different issues. The agent may find 7, miss 3, and you cannot tell if the misses are regressions or noise. One fixture = one primary concern.\n\n## Integration with Canavar\n\nWhen a benchmark run produces a regression, log it to the Canavar error ledger:\n\n```bash\nnode ~/.claude/hooks/dist/canavar-cli.mjs errors\n```\n\nCanavar cross-training means a regression in code-reviewer will inject a warning into all producer agents that use code-reviewer output, preventing cascading quality failures.\n\n## Quick Reference\n\n```bash\n# Before changing an agent:\nnode ~/.claude/benchmarks/run.mjs --agent code-reviewer --save-as before\n\n# After changing the agent:\nnode ~/.claude/benchmarks/run.mjs --agent code-reviewer --compare before\n\n# Full regression check:\nnode ~/.claude/benchmarks/run.mjs --compare --fail-on-regression\n\n# Update baselines after confirmed improvement:\nnode ~/.claude/benchmarks/run.mjs --baseline update\n```\n\n---\n\n**Remember**: A benchmark suite that is never run is decoration. Run benchmarks before every agent change. Protect quality proactively, not reactively.","author":"@vibeeval","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/vibeeval/vibecosystem/tree/main/skills/agent-benchmark","license":"MIT","category":"data","lang":"en","tokens":2779,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}