How to Document Rejected Code Decisions So Future Developers Understand Why

Software repositories often record what code does but rarely explain why certain approaches were rejected, leaving future developers without crucial context. A practical workflow suggests saving rejection reasoning in structured Markdown decision records that specify the constraint violated, the reason for rejection, and the conditions under which the decision should be revisited. For example, a process-local caching approach might be rejected due to cross-worker consistency requirements, with the record stored alongside searchable code path references. These records should distinguish between approaches that were considered and declined versus those that were tried and rolled back in production. When circumstances change, such as a new invalidation mechanism becoming available, the original record should be formally reviewed rather than automatically overridden, with updated evidence and its limitations clearly documented.