agent-readyness

AI agents are already writing, refactoring, and debugging code at scale. But they don't fail gracefully like human developers—they fail catastrophically. The properties that make code "AI-friendly" are similar to those that make it "human-friendly," but agents have zero tolerance for deviation (Borg et al., 2026).

Humans compensate for bad code with intuition, tribal knowledge, and pattern recognition. Agents cannot. Where a senior developer slows down, an agent breaks.

The Bottom Line:

Investing in code quality is the highest-leverage action you can take to enable AI agent productivity.

You could spend $10M/year on the best LLM API credits. Or you could refactor your God Classes, add architecture docs, and improve test coverage—and get better results with cheaper models.

The research is clear:

• ✅ Clean code reduces agent break rates by 7-15 percentage points
• ✅ Modular architecture enables 4.5x better context retrieval
• ✅ Documentation boosts success rates by 32.8%
• ✅ Test-driven workflows achieve 82.8% task completion

Agent Readiness isn't a nice-to-have—it's the difference between an agent that ships code and one that creates busywork.

📖 Read the detailed research evidence →

Quick Start

Install

go install github.com/ingo-eichhorst/agent-readyness/cmd/ars@latest

Make sure $GOPATH/bin (usually ~/go/bin) is in your PATH.

Run Your First Scan

# Disable LLM features for your first test and faster scans (CI/CD)
ars scan /path/to/repo --no-llm

# Generate beautiful HTML report
ars scan /path/to/repo --no-llm --output-html report.html

# Scan a repo with all metrics (C4: Documentation & C7: Agent need Claude CLI)
ars scan /path/to/repo

That's it! You'll get a comprehensive analysis of your codebase's agent-readiness across 7 research-backed categories.

Features

📐 Architecture

Agent Readiness Score follows a pipeline architecture with pluggable analyzers. For detailed architecture documentation:

• System Architecture Overview - High-level component diagram
• Pipeline Flow - Execution flow from scan to output
• Analyzer Architecture - Category analyzers and language support
• C7 Agent Evaluation - Live agent testing workflow
• Data Model - Core types and structures

For AI agents and detailed implementation guidance, see CLAUDE.md and agent.md.

Prerequisites

Required

• Go 1.25+ - The programming language runtime

  📦 Install Go

  macOS:

  brew install go
  # OR download from: https://go.dev/dl/
  

  Linux:

  wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
  sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
  export PATH=$PATH:/usr/local/go/bin
  

  Windows:

  # Download and run installer from: https://go.dev/dl/
  # Or via Chocolatey:
  choco install golang
  

  Verify installation: go version

Optional (for LLM Features)

• Claude Code CLI - For advanced documentation analysis (C4) and live agent evaluation (C7)

  🤖 Install Claude Code CLI

  macOS / Linux:

  curl -fsSL https://claude.ai/install.sh | bash
  

  Windows (PowerShell):

  irm https://claude.ai/install.ps1 | iex
  

  Setup:

  # Complete one-time OAuth authentication
  claude auth login
  
  # Verify installation
  claude --version
  

  Note: No API key configuration needed - the CLI handles authentication automatically.

Installation

Via Go Install (Recommended)

go install github.com/ingo-eichhorst/agent-readyness/cmd/ars@latest

The binary will be installed to $GOPATH/bin (usually ~/go/bin). Make sure this is in your PATH.

Build from Source

git clone https://github.com/ingo-eichhorst/agent-readyness.git
cd agent-readyness
go build -o ars ./cmd/ars

Pre-built Binaries

Pre-built binaries will be available on the releases page for future releases.

Usage

Basic Commands

# Scan current directory
ars scan .

# Scan specific directory
ars scan /path/to/project

# Generate interactive HTML report
ars scan . --output-html report.html

# JSON output for CI/CD integration
ars scan . --json > results.json

LLM Features

ARS includes optional AI-powered analysis that automatically enables when Claude CLI is detected:

# LLM features auto-enabled when Claude CLI is available
ars scan .
# Output: "Claude CLI detected (claude 2.x.x) - LLM features enabled"
# Both C4 (documentation analysis) and C7 (agent evaluation) run automatically

# Explicitly disable LLM features for faster scans (CI/CD)
ars scan . --no-llm
# Output: "LLM features disabled (--no-llm flag)"

Debug Mode

When investigating C7 Agent Evaluation scores, use debug mode:

# Show debug output (prompts, responses, scoring traces)
ars scan . --debug

# Save responses for offline analysis (no Claude CLI calls on replay)
ars scan . --debug --debug-dir ./c7-debug

# Pipe output to files
ars scan . --debug --json > results.json 2>debug.log

🔍 What Gets Analyzed

Agent Readiness Score evaluates your codebase across 7 research-backed categories:

Score Tiers

Documentation

• RESEARCH.md - Detailed academic evidence and citations
• CHANGELOG.md - Release history and upgrade guidance
• CONTRIBUTING.md - How to contribute to this project
• CLAUDE.md - Detailed architecture for AI agents
• AGENTS.md - Precise instructions for AI coding agents

🤝 Contributing

We welcome contributions from both humans and AI agents! 🤖🤝👥

For Human Contributors

1. Check out issues labeled good first issue
2. Read CONTRIBUTING.md for setup and workflow
3. Submit PRs following Conventional Commits

For AI Coding Agents

1. Read AGENTS.md for precise technical boundaries
2. Follow exact commands and code patterns specified
3. Complement with CLAUDE.md for architecture details

Development Setup

# Clone and build
git clone https://github.com/ingo-eichhorst/agent-readyness.git
cd agent-readyness
go build -o ars ./cmd/ars

# Run tests
go test ./...

# Run tests with coverage
go test ./... -coverprofile=cover.out
go tool cover -html=cover.out

# Update coverage badge (run this script to see current coverage)
./scripts/update-coverage-badge.sh

# Format code
gofmt -w .

# Run scan on the project itself
./ars scan .

📊 Example Output

Agent Readiness Score: 6.6 / 10
Tier: Agent-Assisted 🟡
────────────────────────────────────────
C1: Code Quality             7.2 / 10
C2: Semantic Explicitness    8.1 / 10
C3: Architectural Design     5.4 / 10
C4: Documentation Quality    4.8 / 10
C5: Temporal Dynamics        7.3 / 10
C6: Testing Infrastructure   9.1 / 10
C7: Agent Evaluation         8.9 / 10
────────────────────────────────────────

Top Recommendations
══════════════════════════════════════
  1. Improve Documentation Coverage
     Impact: +1.2 points
     Effort: Medium
     Action: Add missing README sections and API docs

  2. Reduce Architectural Complexity
     Impact: +0.8 points
     Effort: High
     Action: Break down large modules and reduce coupling

Star History

If you find this project useful, please consider giving it a star! ⭐

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributors

Thanks to these wonderful people for their contributions!

Acknowledgments

Built with research from leading institutions and grounded in peer-reviewed publications. See RESEARCH.md for 58+ academic citations spanning:

• Software Engineering (McCabe, Fowler, Martin, Gamma)
• Programming Language Theory (Pierce, Cardelli, Wright)
• Empirical Software Studies (Nagappan, Bird, Hassan, Mockus)
• AI & LLM Research (Jimenez, Kapoor, Ouyang, Haroon, Borg)