# ADR: dispatch via CLI first (illustrative example)

## Status
Accepted

## Context
The main agent requires an API key even when CLIs are authenticated locally.

Four sections, one decision. An agent reading it knows what was decided, why, and what must not break.

## Why ADRs beat tool memory

Each CLI's memory is invisible to the others. A decision stored in Claude Code's memory doesn't exist for Codex. An ADR lives in the repo:

| Property | Why it matters with several agents |
|---|---|
| Versioned in Git | you can see when and in which commit a decision changed |
| Readable by any CLI | it's just markdown |
| Reviewable in a PR | a bad decision gets caught before it becomes code |

lemon-code reached 67 ADR files, from 0001 (architecture overview) to 0060 (Cursor CLI runtime). The first twelve are the founding record. From 0013 on, many are evolution proposals with a declared source, such as the Claude Code changelog.

## A single instruction source

lemon-code's `AGENTS.md` opens by declaring itself the single source of truth for agent behavior; `CLAUDE.md` and `GEMINI.md` only point to it. Early on I had three instruction files drifting apart. The `ai:sync-check` script checks the configured skill and command symlink paths and parity for selected built-in skill copies. It does not detect duplicated instruction text in general.

## The 0049 mistake

My best guess (interpretation, not recorded anywhere): parallel sessions listed the folder, saw 0048 as the last number and created 0049. The same happened on a smaller scale with 0050, 0051, 0052 and 0055, which have two files each. The ADR README already noted another numbering slip: `005-agent-swarm-handoff.md` should have four digits and was kept to preserve links.

Takeaways:

- **A sequential number is a shared resource.** With several writers it needs an owner: a script that reserves it, or names based on date and slug.
- **Collisions don't break anything immediately.** That's why they slip through.
- **Renaming is expensive.** Links and commit references point to the old name.

## Checklist: do your ADRs work for agents?

- [ ] Each ADR has Status, Context, Decision and Consequences.
- [ ] One instruction file; the others only point to it.
- [ ] Automated validation checks the symlinks and built-in copies declared by the project.
- [ ] Numbering has an owner.
- [ ] The ADR index marks accepted versus proposed.
- [ ] Rules agents must not break live in Consequences, not in a chat.

## Conclusion

With several agents in one repo, project memory has to live in the repo. Short ADRs with a fixed format and a single instruction source are the logbook every shift reads. The six `0049-` files are a reminder that even the logbook needs rules for who writes.

Monday's post moves up a layer: how I put a native SwiftUI app on top of the CLI without reimplementing anything.

If your team runs several coding agents and decisions keep getting lost between sessions, organizing that memory is work I do at [LEMON.DEV](https://lemon.dev.br).

## References

- [Michael Nygard, Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- [adr.github.io, templates and tools](https://adr.github.io/)
- [AGENTS.md, open convention](https://agents.md/)

## Related reading

- [Versioning AI decisions](https://lemon.dev.br/en/blog/versionamento-reprodutibilidade-decisões-ia)
- [Guardrails and approvals in a coding agent](https://lemon.dev.br/en/blog/guardrails-aprovacoes-agente-codigo)