25 lines
1.5 KiB
Markdown
25 lines
1.5 KiB
Markdown
# ADR System — Research Phase
|
|
|
|
_Last updated: 2026-07-03_
|
|
|
|
This directory captures research for standardizing how Architecture Decision Records (ADRs)
|
|
are organized and used across the user's projects, as a precursor to building a Claude Code
|
|
plugin that automates ADR creation and relevance-scoped retrieval. **Nothing here is built
|
|
yet** — this is the survey/research phase only, requested to answer "what do we have, and what
|
|
could we have with a little engineering elbow grease."
|
|
|
|
- **`01-current-state-survey.md`** — audit of every project under `~/dev/`, `~/clients/`, and
|
|
`~/projects/` for existing ADR practices (organization, templates, tooling, or absence
|
|
thereof).
|
|
- **`02-external-research.md`** — research on ADR best practices generally (Nygard, MADR,
|
|
Y-Statements, lifecycle/governance) and on how Claude Code / AI-agent users specifically have
|
|
integrated ADRs into their workflow.
|
|
- **`03-synthesis-and-opportunities.md`** — synthesis answering the three "how might we" goals
|
|
(know when to create/query, systematize creation for consistency, and query with high
|
|
relevance/low bloat) and naming concrete design options for a future `os-adr` plugin.
|
|
|
|
Provenance note: `02-external-research.md` cites web sources gathered by research agents in a
|
|
single pass; several specific tool/repo names and one incident anecdote are flagged inline as
|
|
**[unverified]** because they were not independently checked against the primary source in this
|
|
pass. Verify before depending on any specific tool name in that file.
|