GitHubWhat they did
Hiroki Kondo builds karasu, an architecture diagram tool, mostly with Claude Code, and has kept 495 Architecture Decision Records in docs/adr/ since March 2026, including the options he turned down and why. Claude Code co-authored 395 of the commits that added an ADR. After a July experiment, he added a required step to his own Claude Code skills for design docs and for starting development: search the ADRs for related decisions, especially rejections, and stop to confirm if a request overturns one. He then went back through a month of session logs (149 main sessions, 442 subagents), plus 1,342 issues and 2,397 PRs, to see what the step actually did.
How it went
In 15 of the 17 sessions that used the design-doc skill, the agent cited an ADR that had rejected or conflicted with the request. In one case he asked to move PR auto-merge into a scheduled GitHub Actions job; the agent found an older ADR that had rejected Actions merging because merges made with the Actions token do not trigger deploy workflows, and that reason shaped the final design. The cost is friction: questions about overriding an ADR came up 29 times across 27 sessions, even when he meant to change course.
Worth knowing
He says this is observation, not proof that ADRs caused better outcomes, and the logs cover only the last month. ADRs keep growing (the median went from about 2,300 to about 6,900 characters), and partial supersessions confuse his index. Writing down when a decision may be overturned helps the agent ask better questions, but he rarely knows that up front.