Skip to content

Instantly share code, notes, and snippets.

@0xdevalias

0xdevalias/technical-design-docs-rfcs-adrs-decision-logs-etc.md

Created October 1, 2025 01:28
Show Gist options
  • Save 0xdevalias/7fbbed02d61190c617393e2e51372a11 to your computer and use it in GitHub Desktop.
Save 0xdevalias/7fbbed02d61190c617393e2e51372a11 to your computer and use it in GitHub Desktop.
Download ZIP
Some notes on technical design documentation practices such as RFCs, ADRs, decision logs, and related approaches for software projects.
Raw
technical-design-docs-rfcs-adrs-decision-logs-etc.md

Technical Design Docs (RFCs, ADRs, Decision Logs, etc)

Some notes on technical design documentation practices such as RFCs, ADRs, decision logs, and related approaches for software projects.

Table of Contents

Unsorted

  • https://github.com/github/spec-kit

    • Spec Kit

    • Toolkit to help you get started with Spec-Driven Development

    • An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.

    • Spec-Driven Development flips the script on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than just guiding them.

Thoughts / comments as I've articulated them elsewhere

This section collects some of my prior GitHub comments or issues, as well as occasionally related discussions that align with the theme of technical documentation practices (RFCs, ADRs, decision logs, etc.).

On openai/codex

Issue 2765: Codex CLI session transcripts for reproducibility

I am closing this issue for now as what I originally wanted seems achievable with the available tools. Might open a new one later on in case I come up with a draft of how to implement what I wanted.

While it is achievable with current tools, I still personally see that there would be benefit in this being a feature, or at least some improved documentation / 'how to' guide included in the Codex docs for how to achieve it.

Though at least for my case, I think I less want the depth of a 'session transcript' and probably more something closer to an Architecture Decision Record (ADR) type thing:

  • https://adr.github.io/

    • An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An Architectural Decision Record (ADR) captures a single AD and its rationale; Put it simply, ADR can help you understand the reasons for a chosen architectural decision, along with its trade-offs and consequences. The collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM), but ADR usage can be extended to design and other decisions (“any decision record”).

  • https://adr.github.io/madr/

    • Markdown Architectural Decision Records

    • An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement of architectural significance. This decision is documented in an Architectural Decision Record (ADR), which details a single AD and its underlying rationale. To capture these records in a lean way, the Markdown Architectural Decision Records (MADRs) have been invented: MADR is a streamlined template for recording architectural significant decisions in a structured manner.

    • https://github.com/adr/madr/tree/4.0.0

I haven't thought too deeply about it; and I know it would be possible by just saving the complete transcripts (though that would be quite noisy/verbose); but essentially having an easy / 'automated'(ish) way to capture the important context and requirements I share in a codex chat 'in the moment', in a way that can be referred back to in future to improve the Agent's 'intuitive memory' for that project/etc; as I find I will often dictate things during a conversation that would be persistently useful; but the added friction of manually finding and capturing those things in a useful way means I more often than not just avoid doing it.

In some ways it feels like it has crossover with AGENTS.md; in other ways it feels like I could just save the full transcript (either in the repo, or attached to a PR or similar); but while I don't have a fully thought through plan of what it would look like or what would work best; it does feel like there is a 'useful middle ground' for a built in feature like this.

It's also possible that this feature might end up requiring too much 'individual customisation' and not be truly universal; in which case I wonder if there are 'supporting features' that would make sense to be built in. The ones that immediately come to mind are some form of 'Codex CLI extensions' support (though I guess maybe that is already achievable to some degree with MCP; but I was initially thinking something that can hook deeper into Codex); and/or some kind of 'lifecycle hooks' that would allow us to trigger custom functionality based on certain events (eg. when a chat ends/is closed/etc) (though again, maybe that is mostly achievable with a combination of AGENTS.md + MCP + etc)

Some other related processes similar'ish to Architectural Design Records (ADRs) for potential inspiration:

Originally posted by @0xdevalias in openai/codex#2765 (comment)

See Also

My Other Related Deepdive Gist's and Projects

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment