agent-docs

# Documentation for Agents

Structure and patterns for documentation that AI agents consume — the files and directories that help Claude, Codex, and other agents understand and work with your project.

For human-facing documentation (READMEs, guides, API docs), see `docs-write`.

## File Architecture

The recommended setup separates tool-agnostic agent guidelines from tool-specific configuration:

```
project/
├── AGENTS.md              # Canonical agent instructions (tool-agnostic)
├── CLAUDE.md              # Entry point that @-mentions AGENTS.md
└── .claude/
    ├── CLAUDE.md          # Claude-specific instructions
    ├── commands/          # Slash commands
    ├── skills/            # Project-specific skills
    ├── rules/             # Modular rule files
    └── settings.json      # Permissions, MCP servers
```

### Why This Structure?

- **AGENTS.md** works across tools (Claude, Codex, Cursor, etc.)
- **@-mentions** avoid duplication and keep CLAUDE.md minimal
- **.claude/** holds Claude-specific extensions without polluting shared docs
- **Modular rules** allow topic-specific guidance without bloating main files

## AGENTS.md

The canonical source of agent instructions. Tool-agnostic — works for Claude, Codex, and other AI assistants.

**Location**: Project root

**Purpose**: Project context, conventions, and guidelines that any AI agent should follow.

### Structure Template

```markdown
# AGENTS.md

Guidelines for AI agents and developers working in this repository.

## Project Overview

Brief description of what this project does and its current status.

## Project Structure

- `src/` — Source code
- `tests/` — Test files
- `docs/` — Documentation

## Commands

\`\`\`bash
bun test              # Run tests
bun run build         # Build project
bun run lint          # Lint and format
\`\`\`

## Architecture

Key architectural decisions and patterns used in this codebase.

## Development Principles

Core principles: TDD, error handling patterns, dependency p