ADR Insight
AI-powered search and reasoning over Architecture Decision Records
Why This Exists
Architecture Decision Records are one of the most valuable artifacts a team can maintain — but they're only valuable if people actually read them. ADR Insight makes an entire ADR collection queryable through natural language. Instead of grepping through markdown files, you ask a question and get a synthesized answer with citations to the source decisions.
What Makes This Interesting
- Full RAG pipeline in Go — query embedding, vector similarity search (SQLite + sqlite-vec), context expansion, and LLM synthesis (Anthropic Claude), all orchestrated through clean interfaces
- Spec-driven development — every feature starts as a specification, goes through clarification, planning, ADR generation, task breakdown, and analysis before a line of code is written. Built with a modified version of GitHub's spec-kit that adds ADR generation to the workflow.
- ADRs are the product — the project's own Architecture Decision Records serve triple duty: project documentation, demo dataset for the RAG pipeline, and interview talking points. Ask this system about its own design.
- LLM-as-judge evaluation — an automated evaluation harness uses a second LLM call to score the system's own answers for accuracy and completeness, alongside mechanical retrieval metrics (precision/recall). Regressions are caught in CI before merge — the LLM evaluates the LLM.
- LLM-powered ADR intelligence — an LLM is also used for ADR relationship classification and keyword identification, enriching the knowledge graph beyond what static analysis alone can provide.
Sample Queries
Try asking questions that require reasoning across multiple ADRs:
- “What tradeoffs were made by choosing SQLite over PostgreSQL, and how would you migrate if the system needed horizontal scaling?”
- “How do the embedding and synthesis components interact, and what would change if we switched LLM providers?”
- “What decisions were driven by the constraint of keeping the system deployable as a single binary?”
- “If this system needed to support multiple teams with separate ADR collections, which architectural decisions would need to be revisited?”
- “What is the chunking strategy and why was it chosen over alternatives like sliding window or semantic chunking?”
- “How does the system handle the case where a question has no relevant ADRs?”
- “What are all the ways SQLite is used in this system, and how do those uses depend on each other?”
At Scale
This is a walking skeleton — intentionally simple to demonstrate end-to-end thinking. In a larger system, the same architectural patterns would extend to:
- Swapping SQLite for PostgreSQL + pgvector for concurrent access and horizontal scaling
- Adding incremental indexing with change detection instead of full reindex
- Streaming LLM responses for better perceived latency
- Multi-tenant support with per-project ADR collections
- Evaluation harness measuring retrieval quality and answer accuracy
- Observability pipeline — structured logging, metrics, distributed tracing
The interface-driven architecture means each of these changes is isolated to one component without rippling through the rest of the system.