avivk5498/agentifind

Overview

This skill sets up a benchmark that measures how effective .claude/CODEBASE.md is at helping AI agents navigate a codebase. It installs hook scripts to run two parallel agents (one with the guide, one without), log all tool usage, enforce read restrictions, and produce analysis comparing efficiency and file access patterns. The benchmark requires running /agentifind first to generate CODEBASE.md and codebase metadata.

How this skill works

The skill verifies required files (.claude/CODEBASE.md and .claude/codebase.json), detects repo type from codebase.json, and creates .claude/hooks with five executable scripts to enforce rules, log tool calls, track turns, analyze results, and reset logs. Hooks record tool usage and block the agent without the guide from reading CODEBASE.md, producing JSONL logs and a human-readable analysis report that compares calls, turns, violations, and files accessed between agents.

When to use it

• Measure whether a generated CODEBASE.md improves agent efficiency and reduces API round-trips
• Compare two agent setups: one allowed to read the guide and one explicitly blocked
• Run experiments on application or infrastructure repositories after generating codebase metadata
• Collect reproducible telemetry for agent tool usage, violations, and turn counts
• Validate changes to CODEBASE.md or navigation guides over time

Best practices

• Run /agentifind first to create .claude/CODEBASE.md and .claude/codebase.json before running the benchmark
• Run both subagents in parallel in the foreground so token/turn reporting is complete
• Keep benchmark runs isolated in a clean workspace; use reset-benchmark.sh between experiments
• Use codebase.json repo_type to choose application vs infrastructure templates for realistic tasks
• Make all hook scripts executable (chmod +x .claude/hooks/*.sh) and keep hooks committed to reproducible experiments

Example use cases

• Application repo: measure difference in file reads and calls for a TypeScript/Next.js codebase when the guide is present
• Infrastructure repo: use the infrastructure template to benchmark resource tracing and blast-radius reasoning for Terraform projects
• Regression test: confirm that an updated CODEBASE.md reduces tool calls and reported turns for common engineering tasks
• Investigation: detect and log attempts by the blocked agent to access restricted .claude files and produce a violations report