AGENTS.md@demo · git:20260118.04d5605 · 2026-01-18 · sha256 d3433568a089cffd

AGENTS.md@demo git:20260118.04d5605A

Immutable. This exact content never changes and is served at /api/v1/blob/d3433568a089cffd.

# AGENTS.md — Instructions for AI Coding Agents

This document tells AI agents how to work with this demo project.

## Overview

This demo uses **DECIDER** to manage Architecture Decision Records (ADRs). ADRs document architectural decisions with machine-readable constraints that you MUST follow.

## Install decider (if missing)

If `decider` is not available, install the pinned version:

```bash
# macOS/Linux
./scripts/install-decider.sh

# Windows PowerShell
.\scripts\install-decider.ps1
```

This installs to `tools/decider/`. Add to PATH:

```bash
export PATH="$PWD/tools/decider:$PATH"
```

## Agent Pre-flight (Required)

Before starting significant work, run:

```bash
decider check adr --dir docs/adr
```

When touching ADR system files (`docs/adr/`, templates, index), use strict mode:

```bash
decider check adr --dir docs/adr --strict
```

**Stop on violations**: If ADR checks fail, fix the issues before proceeding.

**Re-run before finishing**: After completing work, re-run the check to ensure compliance.

## Before Making Changes

### 1. Query Applicable ADRs

Before modifying code, find which ADRs apply to the files you're changing:

```bash
decider list --dir docs/adr --path "src/db/users.go"
```

### 2. Read Constraints and Invariants

Each applicable ADR contains:
- **Constraints**: Rules you MUST follow
- **Invariants**: Properties that must always be true

Example:
```
ADR-0001: Use PostgreSQL for Persistence
  Constraints:
    - All database access must go through the repository pattern
    - Use prepared statements for all queries
    - Never expose raw SQL outside the db package
```

### 3. Follow the Rules

Treat constraints as hard requirements. If you're unsure how to comply, ask for clarification.

### 4. Verify Compliance

After making changes, verify compliance:

```bash
# Find ADRs that apply to your changed files
decider list --dir docs/adr --path "path/to/changed/file"

# Validate all ADRs are properly formatted
decider check adr --dir docs/adr --strict
```

## Demo Project Structure

```
demo/
├── AGENTS.md              # This file
├── CLAUDE.md              # Claude-specific instructions
├── README.md              # Demo walkthrough
├── scripts/
│   ├── install-decider.sh
│   └── install-decider.ps1
├── tools/
│   ├── decider.version    # Pinned version (v0.1.0)
│   └── decider/           # Installed binary
├── docs/adr/
│   ├── README.md          # ADR system overview
│   ├── index.yaml         # Auto-generated index
│   ├── templates/adr.md   # ADR template
│   └── *.md               # Individual ADRs
└── src/                   # Demo source directories
```

## ADR Workflow

### Reading ADRs

```bash
# List all ADRs
decider list --dir docs/adr

# Show details of a specific ADR
decider show ADR-0001 --dir docs/adr

# Find ADRs by tag
decider list --dir docs/adr --tag database

# Find ADRs by scope path
decider list --dir docs/adr --path "src/db/**"
```

### Validating ADRs

```bash
# Basic validation
decider check adr --dir docs/adr

# Strict validation (includes rationale pattern check)
decider check adr --dir docs/adr --strict
```

### Creating ADRs (when needed)

```bash
decider new "Your Decision Title" --dir docs/adr --tags tag1,tag2 --paths "affected/**"
```

Then edit the generated file to fill in Context, Decision (with rationale pattern), Alternatives, and Consequences.

## Mandatory Rationale Pattern

All ADRs in this project MUST use this pattern:

### For Adopted Options
```markdown
### [Option]: Adopted

**Adopted because:**
- Concrete reason tied to decision drivers

**Adopted despite:**
- Known trade-off or downside
```

### For Rejected Alternatives
```markdown
### [Alternative]: Rejected

**Rejected because:**
- Concrete reason for rejection

**Rejected despite:**
- Legitimate strength of this option
```

## Useful Commands

```bash
# Install decider
./scripts/install-decider.sh

# Validate all ADRs
decider check adr --dir docs/adr --strict

# List ADRs
decider list --dir docs/adr

# Show ADR details
decider show ADR-0001 --dir docs/adr

# Find ADRs for a file
decider list --dir docs/adr --path "src/db/users.go"

# Update index
decider index --dir docs/adr
```