Hacker News Reader

Great advice and PoV. One nit: I recommend against the filename "DESIGN.md" for architectural invariants, in light of the emerging use of that filename for UI / design system / CSS tokens (colors, fonts, typography, etc).

See https://designmd.ai/ for examples.

View on HN

Good point. "decisions.md" is a good starting spot.

The point, of course, is that you need some way to document decisions and pivots and eurekas (including rejected ones) over the lifetime of the project. It's a key part of invariant discovery and then committing to them.

Reply on news.ycombinator.com