(This is basically #16717 again.)

Quick background: if you write a header after the body has been written and status has been set in an HTTP handler, that's a bug because it has no effect. If you're testing using an httptest.ResponseRecorder, its HeaderMap will record the header and might make you think that your code is working when it's not. This is #8857. In response to that bug the behavior was changed to snapshot the headers instead, but that caused another problem (#15560) so it was reverted.

Instead, you're now supposed to use Result to get an http.Response and then look at resp.Header.

The documentation is not clear enough about this. I previously filed #16717 and 8e4ea2f added the following documentation to ResponseRecorder.HeaderMap:

// HeaderMap contains the headers explicitly set by the Handler.
//
// To get the implicit headers set by the server (such as
// automatic Content-Type), use the Result method.
HeaderMap http.Header

I think we need to be clearer and explicitly discourage looking at HeaderMap.

I've recently fixed a production bug where headers weren't being set and the tests specifically looked for them using HeaderMap. Then I found a whole bunch more places across many code bases where tests looked for headers to be set in HeaderMap. None of those would have caught headers written after Write.

/cc @bradfitz