I have one rule across my open-source and internal software projects: when a pull request changes system boundaries, data flow, or concurrency, its description should show the design and the local evidence needed to review that risk.
That may mean a high-level design diagram, a low-level design diagram, a class or interface diagram, a sequence diagram, or a smaller combination of them. A documentation change or a 50-line bug fix does not need four diagrams by default. It does need enough explanation and test evidence for the change being made.
Some developers find this strict. They think a 50-line bug fix or a small refactor only needs a two-sentence summary and a green CI badge. Text summaries can gloss over race conditions, circular dependencies, and edge cases. A current diagram can make connections and sequences easier to inspect, but it is still a model of the system, not a substitute for reading the code and tests.
When you lead projects and review code from agents or other engineers, part of the job is making system design and contracts visible. Requiring the right diagram for the right change can reduce guesswork during review.
Why Text Summaries Can Miss Code-Review Risks
When an engineer or an agent opens a pull request, the description usually says something like:
“Refactored the WebSocket frame parser to handle reconnection automatically and clean up stale request callbacks.”
That sounds clear, but it tells you little about how the components interact under load.
- Did the socket transport layer acquire a direct dependency on the request router?
- What happens to pending callbacks when the socket drops mid-flight?
- Does the reconnect handler re-initialize buffers before or after opening the new socket connection?
You cannot answer those questions from that paragraph alone. To find out, you have to open the diff, jump between five files, trace function calls in your head, and check for a subtle async timing issue.
A diagram can reduce that guesswork when it is detailed enough and kept in sync with the code. It can also hide problems if it leaves out an important path, so the diagram still needs to be checked against the implementation.
The Diagrams That Match the Change
I write these diagrams directly in Mermaid syntax inside the Markdown description when the change warrants them. Each one gives a different view of the risk.
High-Level Design (HLD)
The HLD shows system boundaries, external services, network transport layers, and data sources.
It answers: Where does this change fit in the overall system?
When building bxios, my REST-over-WebSocket JavaScript library, the HLD keeps a clear line between the client application interface, the binary MessagePack encoder, the WebSocket connection manager, and the remote server endpoint. If a PR tries to push server routing logic into the client-side transport layer, the HLD makes that boundary change easy to discuss before anyone looks at the code diff.
Low-Level Design (LLD)
The LLD shows internal module layout, file structures, state stores, and error-handling paths.
It answers: How are the internal pieces organized?
This can expose bad abstractions and growing complexity early. If a small feature addition requires three intermediate utility modules and a global event bus, the LLD gives the reviewer a concrete way to question that design.
Class and Interface Diagram
The class diagram shows object structures, interface contracts, method signatures, and structural dependencies.
It answers: What are the static code relationships?
This is one place to look for circular dependencies and leaky abstractions. During bxios development, an early PR attempted to let the low-level socket transport invoke methods on the high-level request manager directly. The class diagram made the cyclic dependency visible. We fixed it by introducing a clean event emitter interface instead.
Sequence Diagram
The sequence diagram shows time order, async messages, payload flows, timeouts, and teardowns.
It answers: What happens step-by-step during execution?
Sequence diagrams are a useful check for race conditions. They can expose timing issues that limited tests miss, such as incoming WebSocket frames arriving during a socket reconnect attempt. A diagram can make ordering risks around frame-buffer initialization and connection setup easier to inspect, but it does not prove that the rest of the implementation is correct.
Real Local Test and Build Output Is Useful Evidence
Diagrams describe the intended design. They do not prove that the code builds or passes tests. For that, the PR also needs evidence from the submitted checkout.
A green CI pipeline is useful, but waiting 10 minutes for remote GitHub Actions during every small iteration is slow. Relying only on CI can also encourage pushing untested code just to see whether the remote runner passes.
My rule is to paste the commands and terminal output from the submitted checkout into the PR description when the change needs that evidence. The output should come from the real run, not from a template.
Pasting local execution logs can show three useful facts, assuming the commands ran from the exact checkout being submitted:
- The developer or agent ran the code locally before opening the PR.
- Type checking with
tsc --noEmitcompleted and reported its result. - The test suite ran against the checkout used for the submission.
Showing the command and its output makes it easier to catch a forgotten export or a broken import path before merge. Logs still have limits. They do not cover tests that were never written, and they do not replace a code review.
Reviews and Better Systems
Requiring design notes and terminal logs for the changes that need them adds some friction. It can also make review more focused.
When I review a PR, I do not want to spend 30 minutes untangling a complex diff. I open the PR, check the test output to confirm what ran, review the HLD and LLD for the stated architecture, inspect the class diagram for coupling, and walk through the sequence diagram for timing issues. Then I read the code and compare the diagrams with the implementation.
If the diagrams are current and the test logs are clear, the review may take less time. There is no honest three-minute guarantee, especially for a large or unfamiliar change. The time saved depends on the change, the quality of the evidence, and how much context the reviewer already has.
Code is an implementation detail, but design, structure, and evidence help a project stay maintainable over time. If an architecture-changing PR cannot show how its boundaries and execution flow are meant to work, I do not consider it ready for main. Smaller changes can use a smaller review packet.