agent-ready-repo-setup

Agent-Ready Repository Setup

Priorities

Agent navigability > Type safety > Convention consistency

Goal

Create repositories where AI agents can work autonomously with minimal guidance. Design choices optimize for agent collaboration: rapid navigation, self-verification, and debugging without visual inspection.

Context / Trigger Conditions

Use this skill when:

• Starting a new project from scratch
• User mentions making a repo "agent-ready", "AI-friendly", or "optimized for Claude"
• Setting up documentation (CLAUDE.md, AGENTS.md, ARCHITECTURE.md)
• Configuring logging, testing, or CI/CD for a new project
• Refactoring a project to be more agent-navigable
• User asks about vertical slice architecture or feature organization

Reasoning-Based Principles

1. Why Root Documentation Matters

Principle: Agents cannot scan files to infer conventions — provide explicit, executable reference at the root.

What to document: Tech stack with versions, build commands, code style, testing requirements.

AGENTS.md over README.md: README is explanatory; AGENTS.md is imperative and command-focused.

Example:

## Build Commands
bun install && bun run build && bun run dev && bun test

## Code Style
- Use interfaces for object shapes
- Prefer explicit types on function parameters
- Write tests for all public APIs

Adaptation: New projects get full AGENTS.md; existing repos document current state and propose improvements separately.

2. Why Strict Type Systems Help Agents

Principle: Agents generate code without visual inspection — shift errors left to compile time for immediate tooling feedback.

TypeScript strict mode catches errors before runtime: noUncheckedIndexedAccess forces handling undefined, exactOptionalPropertyTypes prevents property bugs, noImplicitOverride catches inheritance mistakes.

Why this helps agents: items[0].name gets immediate tsc feedback requiring items[0]?.name, catching bugs without running code.

Example (TypeScript):

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true
  }
}

Adaptation: Enable from day one for new projects; use mypy --strict (Python) or JSDoc @ts-check (JavaScript); enable per-module for existing repos.

3. Why Architecture Affects Agent Navigation

Principle: Agents navigate via file paths and grep, building mental models from structure — vertical slices co-locate related code to reduce navigation.

Layered (MVC): src/models/, controllers/, views/ separate by type

Vertical slice: src/features/checkout/ contains api/, components/, hooks/, types.ts, tests/

Why vertical slices help agents: Co-location reduces navigation, clear feature boundaries, reduced context pollution, tests alongside implementation.

When layered makes sense: Libraries/frameworks where layers ARE product boundaries.

Adaptation: Default to vertical slices for new projects; add incrementally in existing layered codebases; architecture matters less in small projects (<10 files).

4. Why Structured Logging Helps Agents Debug

Principle: Agents diagnose failures from log history, not debuggers — emit machine-parseable JSON with context for post-hoc debugging.

Critical patterns: Log success AND failure, correlation IDs for tracing, structured context ({ orderId, operation, status }), automatic redaction.

Example (Pino for Node.js):

import pino from 'pino';

export const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  redact: {
    paths: ['*.password', '*.apiKey', '*.secret', 'req.headers.authorization'],
    censor: '[REDACTED]',
  },
});

async function processOrder(orderId: string) {
  const log = logger.child({ orderId, operation: 'processOrder' });
  log.info({ status: 'started' }, 'Processing order');

  try {
    const order = await db.orders.process(orderId);
    log.info({ status: 'completed', success: true }, 'Order processed');
    return order;
  } catch (error) {
    log.error({ status: 'failed', success: false, error: error.message }, 'Order failed');
    throw error;
  }
}

Why this helps agents: Grep by orderId for full execution timeline; structured fields enable programmatic filtering.

Adaptation: Set up from day one for new projects; migrate high-traffic paths first for existing; libraries expose events/hooks, not logs.

5. Why Machine-Parseable Test Output Matters

Principle: Agents verify work by parsing test results, not visually scanning terminal — emit JUnit XML, TAP, or JSON for programmatic parsing.

Why JUnit XML: Industry standard; agents extract pass/fail, failure messages, stack traces, test locations.

Example (Vitest):

export default defineConfig({
  test: {
    reporters: ['verbose', 'junit'],
    outputFile: { junit: './test-results/junit.xml' },
    includeTaskLocation: true,  // Adds file:line to XML for agent navigation
  }
});

White-box testing pattern:

function parseToken(token: string) { /* ... */ }
function validateSignature(sig: string) { /* ... */ }

export function authenticate(token: string) {
  const parsed = parseToken(token);
  validateSignature(parsed.signature);
  return parsed;
}

export const __test__ = {
  _parseToken: parseToken,
  _validateSignature: validateSignature,
};

Why this helps agents: When authenticate() fails, write targeted tests for __test__._parseToken() to isolate failure.

Adaptation: Configure from day one for new projects; add reporters alongside existing ones (most frameworks support JUnit XML).

6. Why Runtime Validation Helps Agents

Principle: Agents trust data shapes they cannot verify — fail fast at startup with clear errors, not at runtime with cryptic failures.

Example (Zod for environment variables):

import { z } from 'zod';

const envSchema = z.object({
  PORT: z.coerce.number().min(1000).max(65535),
  DATABASE_URL: z.string().url(),
  NODE_ENV: z.enum(['development', 'test', 'production']),
  API_KEY: z.string().min(1),
});

export const env = envSchema.parse(process.env);  // Crash immediately if invalid

Why this helps agents: Missing DATABASE_URL produces clear "Expected string, received undefined" instead of cryptic runtime errors.

Adaptation: Validate env vars at startup for new projects; add incrementally for critical paths in existing.

7. Why Pre-commit Hooks Help Agents

Principle: Agents might commit formatting/linting errors without feedback — automate quality checks before commits reach version control.

Example (Husky + lint-staged):

{
  "scripts": { "prepare": "husky install" },
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md}": ["prettier --write"]
  }
}

Why this helps agents: Agent runs git commit, hooks auto-fix formatting/linting errors.

Adaptation: Set up from day one for new projects; introduce incrementally for existing.

8. Why MCP Integration Extends Agent Capabilities

Principle: Agents have limited built-in tools — use Model Context Protocol (MCP) to standardize external integrations (docs, databases, APIs, web research).

Example (.mcp.json):

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["@upstash/context7-mcp@latest"]
    }
  }
}

Why this helps agents: Query Context7 for current API docs instead of guessing from training data.

Adaptation: Add for critical integrations (docs, databases) in new projects; integrate when agents struggle with information gaps in existing.

Implementation Approach

For New Projects

Start with highest-impact items:

1. AGENTS.md/CLAUDE.md: Highest-impact file. Make it concrete and command-focused.
2. Strict typing: Enable from day one
3. Structured logging: Set up logger utility before business logic
4. Test output format: Configure in test runner setup
5. Pre-commit hooks: Add after initial code works

For Existing Projects

Incremental adoption: Document current state in AGENTS.md, then propose improvements. Add typing per-file/module. Migrate logging starting with high-traffic paths. Respect existing tools (Winston vs Pino) — document, don't force changes.

For Non-TypeScript Projects

Python: mypy strict mode, Pydantic, structlog, pytest with JUnit XML Go: Strict compilation (default), slog, table-driven tests Ruby: Sorbet, semantic_logger, RSpec with JUnit formatter

Verification

After setup, verify:

1. Type checking passes: bun run typecheck runs clean
2. Tests produce parseable output: Confirm JUnit XML exists
3. Logs are structured: Run test operation, verify JSON output
4. Pre-commit hooks work: Make formatting error, attempt commit, verify auto-fix

Anti-Patterns to Avoid

Anti-Pattern	Reasoning-Based Alternative
Deep layered architecture	Vertical slices co-locate related code
Missing/loose types	Strict typing catches errors at compile time
Only error logging	Log success and failure with structured fields
Free-form log strings	Structured JSON with correlation IDs
Manual pre-commit checks	Automated hooks enforce consistency

Edge Cases and Adaptations

Existing conventions: Document current patterns in AGENTS.md, propose improvements separately.

Non-TypeScript projects: Adapt principles (strict typing → mypy/sorbet, Pino → structlog/slog).

Small projects (<10 files): Focus on documentation and type safety over architecture.

Libraries vs applications: Different patterns (no logging, more white-box testing, broader type constraints).

Tool disagreement: Document what exists; agents work with any tool if configuration is clear.

Notes

• Vertical slice architecture: Agents navigate feature-based organization significantly better than layered architecture
• AGENTS.md adoption: Widely adopted as the highest-impact documentation file for agent collaboration
• Agent-generated code quality: Strict typing and testing substantially improve code quality
• MCP standardization: Model Context Protocol is the de facto standard for agent tool integration

References

• AGENTS.md Official Site
• How to write a great agents.md - GitHub Blog
• Claude Code Best Practices - Anthropic
• Testing Pyramid for AI Agents - Block Engineering
• Context Engineering - Spotify Engineering
• Pino Logger Guide