Write a compatibility note

You now know how to read the machine: macOS build, architecture, translation state, active developer directory. This lesson turns those observations into something a teammate can use.

A useful project note states what you tested, not what you assume will work. “Works on macOS” is an assumption. “Built and tested on macOS 15.5, arm64, Command Line Tools clang 17” is evidence.

Create the note

Create docs/macos-setup.md in one real project you work on. Include the Mac architecture, macOS build, developer directory, runtime version, and any translated dependency. Next to each value, keep the exact command used to collect it, so the next person can compare instead of guessing:

# macOS compatibility — api-server

Last verified: 2026-08-03

| Value               | Command                     | Result                            |
| ------------------- | --------------------------- | --------------------------------- |
| macOS build         | `sw_vers`                   | 15.5 (24F74)                      |
| Architecture        | `uname -m`                  | arm64, native shell               |
| Developer directory | `xcode-select --print-path` | /Library/Developer/CommandLineTools |
| Node                | `node --version`            | v22.17.0                          |

Ten lines, and every line is reproducible.

Add the Known boundaries section

Add a section named Known boundaries for the edges you actually hit: Intel-only tools, minimum macOS versions, and required permissions.

## Known boundaries

- `legacy-report-tool` ships x86_64 only; runs under Rosetta, untested natively
- Requires macOS 14 or later (uses a newer network API)
- Terminal needs Full Disk Access to run the integration tests against ~/Library

Every entry here saves someone else the afternoon you already lost discovering it.

Test the note on a person

Ask another developer to compare the note with their machine. Give them the file and nothing else. Any question they cannot answer from the document is a missing setup requirement — add it and try again.

The failure mode to avoid is the note that describes intent instead of observation. “Should work on Intel” is intent. If nobody ran the project on an Intel Mac, write “untested on Intel” instead. A note that admits its gaps stays trustworthy; a note that papers over them gets ignored after the first time it’s wrong.