adr-index: Keeping AGENTS.md Small with ADRs + a Lightweight Index

After really digging into AI coding tools like Codex, Claude Code, and Gemini, I hit a wall pretty fast.

AGENTS.md (or whatever you use for agent guidelines) eventually becomes a dumpster fire.

At first, it’s great. You write down everything:

• What I’m doing right now
• Decisions I made
• Things to reference later
• Completed tasks

But as the project grows, AGENTS.md turns into a monster:

• It eats up context (wasting tokens $$)
• History gets mixed with rules, creating noise
• Agents miss the important stuff
• It becomes another thing you have to “maintain”

So I pivoted.

• AGENTS.md is for ‘Current Rules + Current Context’ ONLY.
• Decisions move to ADRs (Architecture Decision Records).
• The agent references a lightweight index.json, not the full text of every ADR.

To make this workflow effortless, I built a skill called adr-index.

The Problem: Completed Logs Kill AGENTS.md

Treating AGENTS.md as a persistent log of completed work is a trap. The interest on that technical debt compounds daily.

1. Context Tax: As the file grows, the agent has to read more text for every single prompt. That’s burning tokens for no reason.
2. Signal-to-Noise Ratio: When you have pages of “done” tasks, the “now” gets buried.
3. Maintenance Hell: What started as a rulebook becomes a wiki. And wikis rot.

AGENTS.md should be ephemeral, not cumulative.

The Fix: Decisions in ADRs, Index for the Agent

The goal isn’t to throw away history. It’s to organize it efficiently.

• History (Decisions) -> ADR Markdown files.
• Lookup -> A tiny index.json.

What belongs in an ADR?

• Why did we do this? (Context)
• What did we choose? (Decision)
• What’s the price we pay? (Trade-offs/Consequences)

What DOESN’T belong?

• Trial and error logs
• Debugging journeys
• Commit lists
• Implementation checklists

How adr-index Works (The Tech)

adr-index generates a “Decision Index” without RAG or embeddings. It keeps things dumb and fast.

• Input: docs/adr/*.md
• Output: docs/adr/index.json

1) Header Scanning Only

It doesn’t read the whole file. It scans the top (e.g., first 60 lines). Why? Speed. Less noise. Deterministic generation.

2) Format Validation

It expects a strictly formatted filename/header: # ADR-YYYYMMDD-####-XXX: <title>

Example: # ADR-20260203-0007-A9F: Use JSONB for event payload storage

This format gives us natural sorting by date, avoids collision even if I write multiple ADRs a day, and plays nice with parallel work.

3) Metadata Parsing

It grabs the metadata if it exists:

• Tags:
• Status: (Proposed | Accepted | Deprecated)
• Date:
• TL;DR:

4) Excludes the Fluff

Ignores README.md, templates, etc.

5) JSON Generation

The output index.json is minimal: id, title, tags, status, date, tldr, path. Unicode is preserved so diffs look clean.

Workflow: When to Run It?

Only when you touch an ADR.

• After adding/editing an ADR.
• Before a git commit (commit the ADR and the index together).
• Before opening a PR.

Commands:

• Codex CLI: $adr-index
• Claude Code / Gemini CLI: /adr-index

Managing AGENTS.md

The rule is simple.

• Never accumulate “Done” lists in AGENTS.md.
• Record decisions in ADRs.
• If needed, put a link or a one-line summary in AGENTS.md, but keep it brief.

Example flow:

1. Working: AGENTS.md has specific tasks.
2. Decision made: Write ADR.
3. Run adr-index: Updates index.json.
4. Done: Remove the task from AGENTS.md (or replace with ADR link).

AGENTS.md stays lean naturally.

When to write an ADR? (Heuristics)

If any of these are true, writing an ADR is cheaper than not writing one:

• You compared options and picked one.
• This introduces a constraint for future work.
• Reversing this later would be painful.
• The code alone doesn’t explain “Why”.
• You feel a strong urge to write a paragraph in AGENTS.md about it.

When in doubt, write the ADR.

Open Source: adr-index v0.1.0

It’s small, it’s simple, and it keeps my agents from hallucinating on old context.

• Decisions stay in ADRs.
• Agents read index.json.
• Tokens saved, context preserved.

Repo: https://github.com/studiojin-dev/adr-index-skill

Written with help from GPT-5.2. It’s getting scary good.

Note: I’m a solo developer based in Korea. To share my journey with a wider audience, I used AI to help translate my thoughts into English. If any phrasing feels a bit “too AI” or unnatural, please bear with me—I’m spending most of my energy on the code!