In a prior team, we accomplished the goal of "a newcomer should be able to figure out the history of the code they're looking at, and thereby understand why it

In a prior team, we accomplished the goal of "a newcomer should be able to figure out the history of the code they're looking at, and thereby understand why it is this way" in a simpler, lower-tech way: 1. One commit per PR (so the commit history wasn't polluted with rough drafts and debug logs and such) 2. Every PR links to a bug 3. Design discussions happen in bugs Then when you see some weird code, you can "blame" back to the commit, and from there look at the bug to see why the commit was needed. We also really encouraged people to separate refactoring from new features (refactor first, in a descriptive PR, then add the feature), so that you avoided the problem of seeing a complex refactoring in a PR called "add foo" I agree with other commenters that encoding the design history of your project in its operation doesn't seem helpful, and in my opinion that's because it's solving the wrong problem. Finding the places in a complicated project that need to change is only hard because knowing, to a fairly complete degree, how the system already works is hard, and knowing how a system already works is mostly the product of understanding the problem that it solves deeply. Experienced engineers on a project usually have no problem figuring out which parts of a system need to be changed, because they already know the system well, and they don't know they system well by virtue of having all the code memorized, which would be impossible, but by having participated in all of the design discussions. Therefore, the problem that needs to be solved is making the learning process as fast and easy as possible—thus the strict process around documenting changes and their motivation. Allowing people to quickly discover the existing code's motivation gives them the information that will actually need be committed to memory.