r/softwaredevelopment • • 22h ago

"Harness" is eating testing vocabulary

2 Upvotes

Every LLM answer now wants an "eval harness" for what I'd just call tests or evals. After 20 years in the industry, it feels like marketing air in the room. Harness never had a crisp boundary; test, QA, and eval did. I'd rather keep those words.


r/softwaredevelopment • • 51m ago

ADR-lite: what you can cut from an architecture decision record when the “reader” is a future work session

• Upvotes

Architecture decision records (ADRs) are a well-known technique for keeping the reasoning behind a decision. As I recall, the common format (popularized by Michael Nygard) has a title, status, context, decision and consequences. That works well for decisions a team will live with for years. I’ve been thinking about a much lighter version for something smaller: a single working session, where the “next reader” is you after a break, a teammate picking up the branch, or an AI assistant starting a fresh session.

Here’s how I’d map the full format to five lines (this is my own adaptation, not a standard):

Full ADR field ADR-lite line Note
Title + Decision Decision: one sentence “Retry in the gateway, not the client.”
Context Reason: one sentence Why this and not the obvious alternative
Consequences / alternatives considered Rejected: what you ruled out, and why The line most summaries lose
(Often missing) Open: what’s still undecided Keeps unknowns from looking settled
(Not in ADR) Next: the next concrete step For resuming work
Status dropped Supersede or delete the old entry instead

An example, hypothetical (from a refactor scenario I wrote about, not a real project):

Decision: Retry in the gateway, not the client.
Reason:   Gateway can see which requests are safe to retry.
Rejected: Client-side retry (some requests are unsafe to repeat).
Open:     How to mark requests as safe to retry.
Next:     Update integration tests for the gateway path.

Why “Rejected” matters most: the code shows what was chosen, not what was ruled out. A rejected design leaves no trace in the repository, so it tends to get proposed again, and then argued again.

A test for whether to write one: could someone reasonably propose the opposite later? If not, skip it.

Where the lighter version loses something:

  • No “status” means you have to keep the log current yourself. A stale entry that confidently says the wrong thing is worse than none.
  • Five lines can’t carry a decision with a long list of trade-offs. That’s what a full ADR is for.
  • It’s only useful if the next reader actually reads it. A record nobody opens is just overhead.

For teams already using ADRs: do you have a lighter format for day-to-day decisions, or do small decisions just live in PR descriptions and chat?

I wrote about this with three claims and the strongest objection to each. I’m the author, and the article ends with two resources of mine on AI sessions (one free, one paid), so treat the link as optional: https://medium.com/@nagatomopedro05/what-a-session-summary-forgets-three-claims-three-objections-dc35b96909d2