ADRs for AI

ADRs for AI is a developer toolkit for preserving the reasoning that happens between a person and an AI coding assistant. It treats that reasoning as part of the project rather than disposable chat history. Recommendations, alternatives, open questions, answers, confidence, and later changes can live in plain Markdown records inside the repository. The result is a durable trail of why a technical choice was made, not just the code that choice produced. That matters when a new agent session, a teammate, or a future maintainer needs to understand the constraints behind an authentication design, schema, API, or other architectural decision.

The main working surface is a VS Code extension built around Architectural Deliberation Records. It scans a project for decision files, using docs/adr by default, and shows them in an ADR Explorer with status and unresolved question counts. A dedicated panel gathers open questions from across the project so a reviewer can answer them without hunting through files or old conversations. The extension understands navigation markers for questions, answers, and notes, but it can also display ordinary MADR files with fewer structured features. It can scaffold a first record, and the companion template supplies starter files, directives, and a methodology for teams beginning from an empty repository.

The format is designed for an iterative conversation. An AI collaborator can record the options it considered, its recommendation, the supporting rationale, and the conditions that could change the answer. A person can then accept the recommendation, override it, or supply missing judgment. Answers are saved while they are being written, which protects a draft when an agent edits a nearby file, a refresh occurs, or the workspace is reindexed. Questions can be paused when a decision is blocked or retired when they become moot, without falsely marking them as answered. Every record remains readable in Markdown and can be reviewed through normal Git history.

It fits developers and teams that use coding agents for work where intent matters after the first implementation. A solo developer can use it as memory across many short AI sessions. A team can use the records to make reviewable human rulings visible beside agent recommendations. Multi-root workspace support is useful when a larger effort contains several repositories or subprojects with their own decision trees. Deep links point to specific record sections, while curated tours let a maintainer choose and order the questions that deserve attention instead of presenting every unresolved item as one undifferentiated backlog.

The toolkit goes beyond passive documentation. Its sidebar badge makes outstanding questions visible during normal editing, diagnostics help surface malformed records, and an ADR-specific commit flow can stage decision changes while leaving unrelated work alone. Seeds provide a place for early notes that have not yet become settled decisions. An included MCP surface lets compatible agents query the same record rather than relying on a summary copied into a prompt. Those pieces share one underlying idea. The repository is the source of truth, so the reasoning can move across model providers, sessions, and interfaces without being trapped in a proprietary conversation store.

There is also an iPhone companion for reviewing decisions away from the editor. It imports a GitHub repository, presents open questions as reviewable dossiers, and lets the user accept a recommendation or write a different answer. The response is committed back to the repository. The app says its GitHub credential stays in the device Keychain, communicates directly with GitHub, and does not use the developer's own server. It requires a repository that already follows the ADRs for AI record format, so it complements the desktop workflow rather than replacing the extension and template.

The core VS Code workflow doesn't require an account, server, or API key. An Anthropic API key is optional and only enables AI-assisted extras, while the record browsing and answering workflow works without one. The iPhone app is listed as free, and no paid plan is presented for the toolkit. This is still a specialized and relatively young approach, and its value depends on a team consistently recording decisions rather than leaving the important discussion in chat. For projects that already use Git, Markdown, VS Code, and coding agents, it offers a concrete way to keep human judgment and model reasoning attached to the work they shaped.