Questions and improvements for Architecture Design Records process

[lisa-tarbo]

Claude review of OCS ADR process placed this in the top decile of ADR practices relative to typical industry adoption!!

The ADR promise vs reality

OCS Reality:

1. 52 ADR files in /docs/adr/ where 13 are not accepted
2. No ADRs created - Last updated today with a new ADR added :-)
3. Senior devs forget to check/reference them. We have ADR visibility. Currently Total: 379 citations across all 53 ADRs (0000–0052) — every ADR is cited at least once
4. New developers can find them - An ADR index linked to from other pages

Recent Improvements

• I have documented an ADR developer guide here
• I have implemented a separation of concerns for AI agent instructions [AgentOps] Separation of concerns for extraction of ADRs (moving instructions out of agents.md) #4130

Questions about ease of use and improvements

1. Double check the AI agent workflows are improved or worse after changes to AGENTS.md, DOMAIN.md and new docs/agents/adr_process.md
2. I am not 100% sure how the ADR process should be linked from the AI assisted development process as this guide should be updated
3. Claude suggested to add a lightweight "does this need an ADR" checklist. For example does it change public contract, is it impossible to reverse, will future engineer need to find the why to a change.

[snopoke]

• I am not 100% sure how the ADR process should be linked from the AI assisted development process as this guide should be updated

I think it is only tangentially related. Fine to link it but only as a reference / FYI.

• Claude suggested to add a lightweight "does this need an ADR" checklist. For example does it change public contract, is it impossible to reverse, will future engineer need to find the why to a change.

This would be useful. The other factor I find useful to consider is whether it impacts more than one place in the code ie. is this a decision just for this right now or does it have broader implications.

[lisa-tarbo]

Thanks to @snopoke , we have the whole developer workflow documented https://developers.openchatstudio.com/getting-started/dev-workflow/

It now links in Claude GitHub Automation, AI Assisted development and ADRs into a complete workflow